fix: run closed-enabled cleanup as first teamleader pass

Process closed prdb:enabled issues in a dedicated pre-pass, remove the enabled label only after successful cleanup, and then continue with normal open-issue decision handling.

Author: manuelkiessling

src/GithubIntegration/Facade/GithubIntegrationFacade.php

@@ -22,11 +22,21 @@ public function __construct(
     ) {
     }
 
-    public function getIssuesWithLabel(string $githubUrl, string $githubToken, GithubLabel $label): array
-    {
+    public function getIssuesWithLabel(
+        string      $githubUrl,
+        string      $githubToken,
+        GithubLabel $label,
+        string      $state = 'open',
+    ): array {
         $parsed = GithubUrlParser::parse($githubUrl);
 
-        $rawIssues = $this->githubApiClient->getIssuesWithLabel($parsed->owner, $parsed->repo, $githubToken, $label->value);
+        $rawIssues = $this->githubApiClient->getIssuesWithLabel(
+            $parsed->owner,
+            $parsed->repo,
+            $githubToken,
+            $label->value,
+            $state,
+        );
 
         return array_map(
             static fn (RawGithubIssue $issue): GithubIssueDto => new GithubIssueDto(

src/GithubIntegration/Facade/GithubIntegrationFacadeInterface.php

@@ -15,7 +15,12 @@ interface GithubIntegrationFacadeInterface
     /**
      * @return list<GithubIssueDto>
      */
-    public function getIssuesWithLabel(string $githubUrl, string $githubToken, GithubLabel $label): array;
+    public function getIssuesWithLabel(
+        string      $githubUrl,
+        string      $githubToken,
+        GithubLabel $label,
+        string      $state = 'open',
+    ): array;
 
     /**
      * Returns a single issue by number, or null if it does not exist or is a pull request.

src/GithubIntegration/Infrastructure/Service/GithubApiClient.php

@@ -34,7 +34,7 @@ public function __construct(
     /**
      * @return list<RawGithubIssue>
      */
-    public function getIssuesWithLabel(string $owner, string $repo, string $token, string $labelName): array
+    public function getIssuesWithLabel(string $owner, string $repo, string $token, string $labelName, string $state = 'open'): array
     {
         $issues = [];
         $page   = 1;
@@ -44,7 +44,7 @@ public function getIssuesWithLabel(string $owner, string $repo, string $token, s
             $data = $this->requestJsonWithRetry('GET', "/repos/{$owner}/{$repo}/issues", $token, [
                 'query' => [
                     'labels'   => $labelName,
-                    'state'    => 'open',
+                    'state'    => $state,
                     'per_page' => 100,
                     'page'     => $page,
                 ],

src/TeamleaderAgent/Infrastructure/Handler/ProcessProductConfigHandler.php

@@ -5,6 +5,7 @@
 namespace App\TeamleaderAgent\Infrastructure\Handler;
 
 use App\GithubIntegration\Facade\Dto\GithubCommentDto;
+use App\GithubIntegration\Facade\Dto\GithubIssueDto;
 use App\GithubIntegration\Facade\Dto\GithubPullRequestDto;
 use App\GithubIntegration\Facade\Enum\GithubLabel;
 use App\GithubIntegration\Facade\GithubIntegrationFacadeInterface;
@@ -72,18 +73,19 @@ private function doInvoke(ProductConfigDto $config): void
 
         $this->githubIntegrationFacade->ensureLabelsExist($config->githubUrl, $config->githubToken);
 
-        $issues = $this->githubIntegrationFacade->getIssuesWithLabel(
+        $closedIssues = $this->githubIntegrationFacade->getIssuesWithLabel(
             $config->githubUrl,
             $config->githubToken,
             GithubLabel::Enabled,
+            'closed',
         );
 
-        $this->logger->info('[Teamleader] Found enabled issues', [
-            'count'           => count($issues),
+        $this->logger->info('[Teamleader] Found closed enabled issues for cleanup pass', [
+            'count'           => count($closedIssues),
             'productConfigId' => $config->id,
         ]);
 
-        foreach ($issues as $issue) {
+        foreach ($closedIssues as $issue) {
             $this->logContext->set($config->name, $issue->number);
 
             $lockKey = $this->buildIssueLockKey($config->id, $issue->number);
@@ -112,13 +114,63 @@ private function doInvoke(ProductConfigDto $config): void
                     continue;
                 }
 
-                if ($this->githubIntegrationFacade->isIssueClosed($config->githubUrl, $config->githubToken, $freshIssue->number)) {
-                    $this->workspaceManagementFacade->cleanupWorkspaceForIssue($config->id, $freshIssue->number);
-
-                    $this->logger->info('[Teamleader] Closed enabled issue detected, workspace cleanup triggered', [
+                if (!$this->githubIntegrationFacade->isIssueClosed($config->githubUrl, $config->githubToken, $freshIssue->number)) {
+                    $this->logger->info('[Teamleader] Issue reopened before closed cleanup pass, skipping', [
                         'productConfigId' => $config->id,
                         'issueNumber'     => $freshIssue->number,
                     ]);
+                    continue;
+                }
+
+                $this->cleanupClosedEnabledIssue($config, $freshIssue);
+            } finally {
+                $lock->release();
+            }
+        }
+
+        $openIssues = $this->githubIntegrationFacade->getIssuesWithLabel(
+            $config->githubUrl,
+            $config->githubToken,
+            GithubLabel::Enabled,
+            'open',
+        );
+
+        $this->logger->info('[Teamleader] Found open enabled issues for decision pass', [
+            'count'           => count($openIssues),
+            'productConfigId' => $config->id,
+        ]);
+
+        foreach ($openIssues as $issue) {
+            $this->logContext->set($config->name, $issue->number);
+
+            $lockKey = $this->buildIssueLockKey($config->id, $issue->number);
+            $lock    = $this->lockFactory->createLock($lockKey, 300.0);
+
+            if (!$lock->acquire(false)) {
+                $this->logger->info('[Teamleader] Could not acquire lock, skipping issue', [
+                    'issueNumber' => $issue->number,
+                ]);
+
+                continue;
+            }
+
+            try {
+                $freshIssue = $this->githubIntegrationFacade->getIssueByNumber(
+                    $config->githubUrl,
+                    $config->githubToken,
+                    $issue->number,
+                );
+
+                if ($freshIssue === null) {
+                    $this->logger->warning('[Teamleader] Could not re-fetch issue, skipping', [
+                        'issueNumber' => $issue->number,
+                    ]);
+
+                    continue;
+                }
+
+                if ($this->githubIntegrationFacade->isIssueClosed($config->githubUrl, $config->githubToken, $freshIssue->number)) {
+                    $this->cleanupClosedEnabledIssue($config, $freshIssue);
 
                     continue;
                 }
@@ -149,6 +201,30 @@ private function doInvoke(ProductConfigDto $config): void
         }
     }
 
+    private function cleanupClosedEnabledIssue(ProductConfigDto $config, GithubIssueDto $issue): void
+    {
+        try {
+            $this->workspaceManagementFacade->cleanupWorkspaceForIssue($config->id, $issue->number);
+            $this->githubIntegrationFacade->removeLabelFromIssue(
+                $config->githubUrl,
+                $config->githubToken,
+                $issue->number,
+                GithubLabel::Enabled,
+            );
+
+            $this->logger->info('[Teamleader] Closed enabled issue cleaned up and disabled', [
+                'productConfigId' => $config->id,
+                'issueNumber'     => $issue->number,
+            ]);
+        } catch (Throwable $e) {
+            $this->logger->warning('[Teamleader] Failed closed-issue cleanup pass, keeping enabled label for retry', [
+                'productConfigId' => $config->id,
+                'issueNumber'     => $issue->number,
+                'error'           => $e->getMessage(),
+            ]);
+        }
+    }
+
     private function initiatePlanning(string $githubUrl, string $githubToken, string $productConfigId, int $issueNumber): void
     {
         $runId = Uuid::v4()->toRfc4122();
@@ -561,7 +637,7 @@ private function buildIssueLockKey(string $productConfigId, int $issueNumber): s
         return 'tl-issue-' . md5($productConfigId . ':' . (string) $issueNumber);
     }
 
-    private function ensureTokenUserAssignedToIssue(string $githubUrl, string $githubToken, \App\GithubIntegration\Facade\Dto\GithubIssueDto $issue): void
+    private function ensureTokenUserAssignedToIssue(string $githubUrl, string $githubToken, GithubIssueDto $issue): void
     {
         try {
             $tokenUserLogin = $this->githubIntegrationFacade->getAuthenticatedUserLogin($githubToken);

src/Workflow/docs/workflow.md

@@ -31,10 +31,11 @@ A cron job (cron management itself is out of scope) periodically launches the **
 
 The Teamleader Agent Messenger Handler is a **deterministic coordinator** (not LLM-backed). For the `ProductConfig` it was dispatched for, it:
 
-1. Uses `GithubIntegration` to retrieve all GitHub issues carrying the `prdb:enabled` label
-2. Ensures the GitHub user authenticated by the product token is assigned to each open enabled issue (best effort)
-3. Evaluates each issue's current labels
-4. Takes the first matching action per issue and moves on
+1. Runs a dedicated **closed-enabled cleanup pre-pass**: fetches `prdb:enabled` issues in `closed` state, performs full workspace sweep cleanup, then removes `prdb:enabled` on successful cleanup (keeps label on failure for retry).
+2. Fetches `prdb:enabled` issues in `open` state for normal decision processing.
+3. Ensures the GitHub user authenticated by the product token is assigned to each open enabled issue (best effort).
+4. Evaluates each open issue's current labels.
+5. Takes the first matching action per issue and moves on.
 
 ### Concurrency Contract
 
@@ -58,19 +59,19 @@ The Teamleader evaluates each issue against the following conditions in priority
 
 | # | Condition | Action |
 |---|---|---|
-| 1 | Issue is closed (while still carrying `prdb:enabled`) | **Cleanup workspace**: trigger full workspace sweep cleanup (matching containers/images/workspace directory), then skip further processing for this issue |
-| 2 | Has `prdb:reset-locks` | **Reset issue locks/state + cleanup workspace**: clear issue-scoped DB lock artifacts + run claims, trigger full workspace sweep cleanup, remove `prdb:coordination-ongoing`, `prdb:planning-ongoing`, `prdb:implementation-ongoing`, then remove `prdb:reset-locks` |
-| 3 | Has `prdb:coordination-ongoing` | **Skip** — issue is currently being processed by another run |
-| 4 | Has `prdb:planning-ongoing` or `prdb:implementation-ongoing` | **Skip** — work is already in progress |
-| 5 | Has `prdb:enabled` but no `prdb:planning-*`, `prdb:plan-approved`, or `prdb:implementation-*` labels | **Initiate planning**: add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message |
-| 6 | Has `prdb:planning-feedback-needed` AND a user comment newer than the label's timestamp | **Resume planning**: remove `prdb:planning-feedback-needed`, add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message |
-| 7 | Has `prdb:plan-approved` but no `prdb:implementation-*` labels | **Initiate implementation**: add `prdb:coordination-ongoing` + `prdb:implementation-ongoing`, dispatch Implementation Agent message |
-| 8 | Has `prdb:planning-done` but no `prdb:plan-approved` or `prdb:implementation-*` labels AND a non-bot comment newer than the `prdb:planning-done` label's timestamp | **Revise plan**: remove `prdb:planning-done`, add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message (resume mode) |
-| 9 | Has `prdb:implementation-done` AND the linked PR is still open AND there is newer non-bot PR feedback than the latest code state | **Resume implementation**: remove `prdb:implementation-done`, add `prdb:coordination-ongoing` + `prdb:implementation-ongoing`, dispatch Implementation Agent message with revision context (PR branch name, PR number) |
-| 10 | Has `prdb:planning-done` (with no new feedback) or `prdb:implementation-done` (with no new PR feedback) | **Skip** — awaiting human review or PR merge |
-| 11 | Has `prdb:planning-errored` or `prdb:implementation-errored` | **Skip** — requires manual intervention (see [Error Handling](#error-handling)) |
+| 1 | Has `prdb:reset-locks` | **Reset issue locks/state + cleanup workspace**: clear issue-scoped DB lock artifacts + run claims, trigger full workspace sweep cleanup, remove `prdb:coordination-ongoing`, `prdb:planning-ongoing`, `prdb:implementation-ongoing`, then remove `prdb:reset-locks` |
+| 2 | Has `prdb:coordination-ongoing` | **Skip** — issue is currently being processed by another run |
+| 3 | Has `prdb:planning-ongoing` or `prdb:implementation-ongoing` | **Skip** — work is already in progress |
+| 4 | Has `prdb:enabled` but no `prdb:planning-*`, `prdb:plan-approved`, or `prdb:implementation-*` labels | **Initiate planning**: add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message |
+| 5 | Has `prdb:planning-feedback-needed` AND a user comment newer than the label's timestamp | **Resume planning**: remove `prdb:planning-feedback-needed`, add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message |
+| 6 | Has `prdb:plan-approved` but no `prdb:implementation-*` labels | **Initiate implementation**: add `prdb:coordination-ongoing` + `prdb:implementation-ongoing`, dispatch Implementation Agent message |
+| 7 | Has `prdb:planning-done` but no `prdb:plan-approved` or `prdb:implementation-*` labels AND a non-bot comment newer than the `prdb:planning-done` label's timestamp | **Revise plan**: remove `prdb:planning-done`, add `prdb:coordination-ongoing` + `prdb:planning-ongoing`, dispatch Planning Agent message (resume mode) |
+| 8 | Has `prdb:implementation-done` AND the linked PR is still open AND there is newer non-bot PR feedback than the latest code state | **Resume implementation**: remove `prdb:implementation-done`, add `prdb:coordination-ongoing` + `prdb:implementation-ongoing`, dispatch Implementation Agent message with revision context (PR branch name, PR number) |
+| 9 | Has `prdb:planning-done` (with no new feedback) or `prdb:implementation-done` (with no new PR feedback) | **Skip** — awaiting human review or PR merge |
+| 10 | Has `prdb:planning-errored` or `prdb:implementation-errored` | **Skip** — requires manual intervention (see [Error Handling](#error-handling)) |
 
 For open enabled issues, assignee enforcement runs before decision routing: if the token-authenticated GitHub user is not already assigned, Teamleader assigns that user (best effort; failures are logged and processing continues).
+If an issue closes between the open-issue fetch and per-issue processing, Teamleader falls back to the same cleanup behavior as the closed pre-pass.
 
 ### Phase 3 — Planning
 
@@ -162,8 +163,10 @@ flowchart TD
     CRON([Cron Trigger]) --> RUNNER[Runner Command]
     RUNNER --> CONFIGS[Retrieve all ProductConfigs]
     CONFIGS --> |per ProductConfig| TL[Teamleader Handler]
-    TL --> FETCH[Retrieve issues with prdb:enabled]
-    FETCH --> EVAL{Evaluate issue labels}
+    TL --> FETCH_CLOSED[Retrieve closed issues with prdb:enabled]
+    FETCH_CLOSED --> CLEAN_CLOSED[Cleanup workspace sweep\nRemove prdb:enabled on success]
+    CLEAN_CLOSED --> FETCH_OPEN[Retrieve open issues with prdb:enabled]
+    FETCH_OPEN --> EVAL{Evaluate issue labels}
 
     EVAL --> |New issue| PLAN_START[Add prdb:coordination-ongoing\nAdd prdb:planning-ongoing]
     EVAL --> |Feedback received| PLAN_RESUME[Remove prdb:planning-feedback-needed\nAdd prdb:coordination-ongoing\nAdd prdb:planning-ongoing]
@@ -256,7 +259,7 @@ All ProductBuilder labels use the `prdb:` prefix to avoid collisions with projec
 
 | Label | Set by | Removed by | Description |
 |---|---|---|---|
-| `prdb:enabled` | User (manually) | User (manually) | Marks an issue for ProductBuilder processing. Issues without this label are completely ignored by the system. If an enabled issue is already closed, Teamleader performs workspace cleanup and skips further processing for that issue. |
+| `prdb:enabled` | User (manually) | Teamleader (closed cleanup success) or User (manually) | Marks an issue for ProductBuilder processing. Issues without this label are completely ignored by the system. At the start of each Teamleader run, closed enabled issues are sweep-cleaned first; after successful cleanup Teamleader removes `prdb:enabled`. If cleanup fails, the label is kept so the next run retries. |
 | `prdb:reset-locks` | User (manually, human only) | Teamleader | Emergency issue-scoped recovery trigger. On next Teamleader pass it clears issue-scoped DB lock artifacts and active run claims, performs workspace cleanup for the issue workspace, removes `prdb:coordination-ongoing`/`prdb:planning-ongoing`/`prdb:implementation-ongoing`, then removes this label. |
 | `prdb:coordination-ongoing` | Teamleader | Planning / Implementation Handler | Concurrency guard — prevents concurrent Teamleader runs from double-dispatching work for the same issue. Set before dispatching an agent, removed when the agent handler completes. |
 | `prdb:planning-ongoing` | Teamleader | Planning Handler | A Planning Agent is currently working on this issue. |

tests/Unit/ImplementationAgent/ImplementIssueHandlerTest.php

@@ -159,8 +159,12 @@ public function __construct(
     ) {
     }
 
-    public function getIssuesWithLabel(string $githubUrl, string $githubToken, GithubLabel $label): array
-    {
+    public function getIssuesWithLabel(
+        string      $githubUrl,
+        string      $githubToken,
+        GithubLabel $label,
+        string      $state = 'open',
+    ): array {
         return [];
     }