@plainconceptsplatform/workflows 0.28.12 → 0.28.14

package/loops/actions/housekeeping/action.yml

@@ -66,6 +66,26 @@ runs:
           const age = (iso) => Date.now() - new Date(iso).getTime();
           const days = (ms) => Math.floor(ms / 86400000);
 
+          // 0. Cancel workflow runs stuck in "pending" for over an hour. The ARC fleet is two
+          // VMs, and when it saturates, jobs sit pending indefinitely — GitHub has no queue-time
+          // timeout. A stuck pending implement or refine run holds a fleet slot that the retry
+          // logic below can never free because the run never reaches a terminal state. This
+          // cancel runs on a GitHub-hosted runner, so it works even when the fleet is full.
+          const stuckCutoff = Date.now() - 3600 * 1000; // 1 hour ago
+          let cancelledRuns = 0;
+          for (const run of await github.paginate(github.rest.actions.listWorkflowRuns, {
+            owner: context.repo.owner, repo: context.repo.repo, workflow_id: 'work-router.yml',
+            status: 'pending', per_page: 50,
+          })) {
+            if (new Date(run.created_at).getTime() > stuckCutoff) continue;
+            await act(`cancelling stuck pending run #${run.id} (queued ${new Date(run.created_at).toISOString()})`, async () => {
+              await github.rest.actions.cancelWorkflowRun({
+                owner: context.repo.owner, repo: context.repo.repo, run_id: run.id,
+              });
+              cancelledRuns += 1;
+            });
+          }
+
           const issues = await github.paginate(github.rest.issues.listForRepo, {
             ...context.repo, state: 'open', per_page: 100,
           });
@@ -74,6 +94,37 @@ runs:
           });
           const names = (issue) => issue.labels.map((l) => (typeof l === 'string' ? l : l.name));
 
+          // 0b. Clean orphaned bot-working labels. When a workflow run is cancelled (above) or
+          // dies without clearing bot-working, the issue sits with bot-working + a work label
+          // forever: no stalled marker, so the retry logic below never touches it. Find issues
+          // with bot-working, check whether the most recent run for the linked operation is
+          // still active, and if not, park the issue for retry.
+          for (const issue of issues) {
+            if (issue.pull_request) continue;
+            const labels = names(issue);
+            if (!labels.includes('bot-working')) continue;
+            // Don't touch issues that already have stalled or review — those are handled below.
+            if (labels.includes('stalled') || labels.includes('review')) continue;
+            const work = WORK_LABELS.find((l) => labels.includes(l));
+            if (!work) continue;
+
+            // An issue with bot-working should have a recent or active workflow run.
+            // If bot-working has been on for longer than the retry window, the run is dead.
+            const waited = age(issue.updated_at);
+            if (waited < retryAfterMs) continue;
+
+            await act(`#${issue.number}: releasing orphaned bot-working (parked ${Math.floor(waited / 3600000)}h with no active run)`, async () => {
+              // Park it for retry: add stalled + review, remove bot-working.
+              // The retry logic below will pick it up on the next sweep.
+              await github.rest.issues.addLabels({
+                ...context.repo, issue_number: issue.number,
+                labels: ['stalled', 'review'],
+              });
+              await github.rest.issues.removeLabel({ ...context.repo, issue_number: issue.number, name: 'bot-working' })
+                .catch((error) => { if (error.status !== 404) throw error; });
+            });
+          }
+
           const needsHuman = [];
           // Gate telemetry. Every disposition the gate has ever posted is already on a pull
           // request, marked, so the rate costs one extra listing rather than a store.
@@ -337,6 +388,7 @@ runs:
           await core.summary
             .addHeading('Housekeeping', 2)
             .addList([
+              `Cancelled stuck pending runs: ${cancelledRuns}`,
               `Retried: ${retried}`,
               `Waiting on a person: ${needsHuman.length}`,
               `Stalled, retrying by itself: ${retrying.length}`,

package/loops/docs/diagrams.md

@@ -442,53 +442,6 @@ The version bump, the tag and the Release are deterministic on purpose. The agen
 a file on disk, so a confused model cannot publish a release.
 
 
----
-
-## agent-visual-verify.md
-
-Runs after the merge gate decides auto-merge and before the merge itself. The agent reads the
-change, writes a verification plan as JSON waypoints, and a post-agent shell step drives
-agent-browser to capture screenshots at each waypoint. A final step attaches the screenshots
-to the linked issue as a comment. Failures never block the merge.
-
-```mermaid
-flowchart TD
-    vvStart("Merge Gate<br/>auto-merge verdict") --> vvSubject
-    vvSubject{"subject (rung 4)<br/>PR open? Visual<br/>verify enabled?"}
-    vvSubject -.->|"no"| vvIdle
-    vvSubject -->|"yes"| vvActivation
-    vvActivation("Activation (rung 3)<br/>Checkout, load issue context,<br/>build the prompt") --> vvAgent
-    vvAgent("Agent (rung 5)<br/>Explore the change, write<br/>plan.json with waypoints<br/>(url + selector per step)") --> vvBuild
-    vvBuild("Build and start app<br/>VISUAL_VERIFY_BUILD_COMMAND,<br/>then VISUAL_VERIFY_START_COMMAND<br/>on the configured port") --> vvAppUp{"App up on<br/>the port?"}
-    vvAppUp -.->|"no"| vvWarn
-    vvAppUp -->|"yes"| vvCapture
-    vvCapture["Capture screenshots<br/>agent-browser opens each waypoint,<br/>waits for selectors,<br/>screenshot --full --no-sandbox"] --> vvGotShots{"Any captured?"}
-    vvGotShots -->|"yes"| vvAttach
-    vvGotShots -.->|"no, all failed"| vvWarn
-    vvAttach("Attach to issue<br/>post plan + screenshots<br/>as a single comment") --> vvDone
-    vvDone(("Screenshots posted<br/>visual evidence on the issue"))
-    vvWarn(("Warning posted<br/>no screenshots, merge proceeds"))
-    vvIdle(("Idle<br/>not enabled or not our PR"))
-
-    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
-    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
-    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
-    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
-    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
-    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
-    class vvStart start
-    class vvActivation,vvAgent,vvBuild,vvCapture,vvAttach action
-    class vvSubject,vvAppUp,vvGotShots decision
-    class vvIdle idle
-    class vvWarn failure
-    class vvDone success
-```
-
-The agent does not take screenshots itself. It writes a plan; a shell step runs agent-browser
-against the running app. Chromium needs --no-sandbox on CI runners (set via
-AGENT_BROWSER_ARGS), and the explicit apt-get install covers libraries gent-browser
-install --with-deps misses on ubuntu-24.04.
-
 ---
 
 ## housekeeping
@@ -657,3 +610,52 @@ The route matrix asserts the scanner exists, that both exit paths call `setFaile
 at least as many scans as upstream writes, that each individual check is still present, and that no
 model or `OPENAI_API_KEY` has appeared in the action. Every one of those was mutation-tested; three
 earlier versions of them passed against a deliberately broken guard and were rewritten.
+
+---
+
+## agent-visual-verify.md
+
+Runs after merge-gate decides to auto-merge, before the actual merge, and produces **evidence, not
+code changes**: it writes a verification plan, drives a real browser through the app, and attaches
+screenshots to the linked issue. It is called directly by merge-gate's `conclude` job, so it is not
+a router route. Failures never block the merge — a browser that will not start or an app that never
+comes up emits a warning comment and the merge proceeds.
+
+```mermaid
+flowchart TD
+    vvStart("merge-gate conclude<br/>calls agent-visual-verify") --> vvSubject
+    vvSubject["subject (rung 4)<br/>PR open? linked issue found?"] --> vvConfig
+    vvConfig{"config (rung 4)<br/>VISUAL_VERIFY_ENABLED and<br/>START_COMMAND set?"}
+    vvConfig -.->|"no"| vvIdle
+    vvConfig -->|"yes"| vvFacts
+    vvFacts["Facts (rung 3)<br/>PR branch checked out,<br/>issue context loaded"] --> vvPlan
+    vvPlan{"/repo-verify (rung 5)<br/>reachable UI surface?"}
+    vvPlan -.->|"not-applicable"| vvNoUi
+    vvPlan -->|"yes"| vvStartCmd
+    vvStartCmd{"start command set?<br/>VISUAL_VERIFY_START_COMMAND"}
+    vvStartCmd -.->|"empty"| vvNoStart
+    vvStartCmd -->|"yes"| vvAgent
+    vvAgent["Agent (rung 5)<br/>parse waypoints into plan.json,<br/>one add_comment on the issue"] --> vvCapture
+    vvCapture["post-agent (rung 6)<br/>build + start the app,<br/>agent-browser captures per waypoint"] --> vvAttach
+    vvAttach["attach-screenshots (rung 6)<br/>always(), subject found + enabled"] --> vvShutdown
+    vvShutdown["shut down the app"] --> vvDone
+    vvCapture -.->|"app never started,<br/>no plan, or all waypoints failed"| vvPartial
+    vvDone(("Verified<br/>screenshots attached,<br/>merge proceeds"))
+    vvPartial(("Attach what exists<br/>no-capture explanation,<br/>run stays green"))
+    vvNoUi(("No UI surface<br/>summary comment, stop"))
+    vvNoStart(("Not configured<br/>warning comment, stop"))
+    vvIdle(("Idle<br/>unconfigured or PR not open"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class vvStart start
+    class vvSubject,vvFacts,vvCapture,vvAttach,vvShutdown action
+    class vvConfig,vvPlan,vvStartCmd decision
+    class vvIdle idle
+    class vvNoUi,vvNoStart,vvPartial failure
+    class vvDone success
+```