@plainconceptsplatform/workflows 0.28.11 → 0.28.13

package/loops/actions/verify-route-matrix/verify-route-matrix.sh

@@ -927,6 +927,21 @@ if worker_installed implement; then
   if [ "$IMPLEMENT_RETRY_OK" -eq 1 ]; then PASS=$((PASS + 1)); else FAIL=$((FAIL + 1)); fi
 fi
 
+# A queued worker can start long after it was dispatched. If triage concluded
+# needs-maintainer while the run waited in a queue, the issue carries review and
+# the verdict must stand: the reserve step clears review blindly, so eligibility
+# has to catch it first (Pliny-Bot #372).
+for route in implement refine; do
+  worker_md="${WORKFLOWS_DIR}/agent-${route}.md"
+  [ -f "$worker_md" ] || continue
+  if grep -q 'index("review")' "$worker_md"; then
+    PASS=$((PASS + 1))
+  else
+    FAIL=$((FAIL + 1))
+    echo "FAIL: agent-${route} eligibility does not guard against the review label; a queued worker could override a triage verdict" >&2
+  fi
+done
+
 if worker_installed merge-gate; then
   # A failed attempt must not strip `implement`: identify-gate-subject refuses an issue
   # without it, so the first crash would starve every retry at the subject check.
@@ -2409,7 +2424,7 @@ if [ -f "$APP_ERRORS_MJS" ]; then
   # values and cannot see a field somebody adds next year. Compared as a set, so reordering is
   # fine and an addition is not. run_id is the one that matters: it is unhashed on this
   # telemetry and joins to a conversation and to a person.
-  expected_fields="exceptionType frames fingerprint firstSeen lastSeen occurrences operationName operations problemId roleName"
+  expected_fields="exceptionType frames fingerprint firstSeen lastSeen occurrences operationName operations problemId roleName topFrames message category"
   actual_fields="$(sed -n '/export const FINDING_FIELDS = \[/,/\];/p' "$APP_ERRORS_MJS" |
     grep -oE '"[a-zA-Z]+"' | tr -d '"' | sort | tr '\n' ' ' | sed 's/ $//')"
   if [ "$actual_fields" = "$(echo "$expected_fields" | tr ' ' '\n' | sort | tr '\n' ' ' | sed 's/ $//')" ]; then

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
+```