@bongos/core 1.19.837 → 1.19.838

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.837",
-  "core_contract": "1.19.837",
-  "source_commit": "d3feb6abfa5bf8256137d7be87929d517c266c48",
+  "core_version": "1.19.838",
+  "core_contract": "1.19.838",
+  "source_commit": "f5c78584166eedac7972dcb10f61e55d7c1685e7",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T16:49:51.613Z",
+  "built_at": "2026-09-17T17:02:39.487Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 493,
+    "docs_redacted": 494,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2253,
+    "functional_verbatim": 2257,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2772,
-  "tree_sha256": "ce96f2d9d0c9b141f032d74100c6f505b5c6fdce72de9da3a6a8620538af685b",
+  "file_count": 2777,
+  "tree_sha256": "61bef3a77f3f90a904e83ae13d78fa314c21c944451e91a369fb047fc78d9b7a",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -1994,10 +1994,15 @@
       "mode": "0000644",
       "sha256": "02f7e793bdf3665cf371f273dda6b84701918dc8fd031fac2893a19ed9f0bd9a"
     },
+    {
+      "path": "docs/adr/0302-the-third-identical-failure-stops-the-session-and-asks.md",
+      "mode": "0000644",
+      "sha256": "08ea781a488d7454ca49b17e9540bb4c7bb9f1925aedf8ad4634057a89dd0d22"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "7fec861b916708b1292c3b69c76d2277368ffbaa10cbf0eab3e60b7512afab44"
+      "sha256": "5c20d4bf4c0202a391a617d99daaa97d8a566d9d5c8534b5bd060faa8f8afe02"
     },
     {
       "path": "docs/api-reference.md",
@@ -2552,7 +2557,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "4cacfe54b3e4f80aa1cd7a4b190bf673da867f99d5101cc1c7870ee13021c008"
+      "sha256": "b575f34143de0be30fadfd63bea76f77305fa175beee3960291414ff6b55d611"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2562,7 +2567,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "7b2488f4099bcc1060d6257077010857c05b886459ad106f722ed19b0b5178f0"
+      "sha256": "aed7cd21803eab964c3d296c5f938e8c94b9e05fb865ce3bb5780574a5fdcebb"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3709,10 +3714,20 @@
       "mode": "0000644",
       "sha256": "b576e8518bc8c9af9d5a1a86ace812f292fc2df1225cdfce8578d11703350391"
     },
+    {
+      "path": "modules/agents/migrations/agents_003_output_ref_idx.sql",
+      "mode": "0000644",
+      "sha256": "7a9763f90da032c81aa0b1a8461a2e13b58d9f529c1b857b048648feeadc6fdd"
+    },
     {
       "path": "modules/agents/module.json",
       "mode": "0000644",
-      "sha256": "bdfe0b71f372806fd600cc50ac87c9486ca79f09f69be4e95b5deacd54779d84"
+      "sha256": "4eea1864848b1217fef12070a981fda974d7105449d6a46bdf9ed04068b57c5e"
+    },
+    {
+      "path": "modules/agents/pollers/event-router.js",
+      "mode": "0000644",
+      "sha256": "de64902d694acfc7d32aaf4d8629921f64cf851d600deb077a278b528d34c57d"
     },
     {
       "path": "modules/agents/routes/agents.js",
@@ -4227,7 +4242,7 @@
     {
       "path": "modules/discord/module.json",
       "mode": "0000644",
-      "sha256": "6800aead0d24b615912d2711dbe90ef284e8a31579da7c8a8ce642de81274307"
+      "sha256": "437fa0e5174b2cbdd3c1949a3d048a8c8c09defce85afd04a27c0c635031db1b"
     },
     {
       "path": "modules/discord/pollers/discord-bot.js",
@@ -4242,7 +4257,7 @@
     {
       "path": "modules/discord/routes/discord.js",
       "mode": "0000644",
-      "sha256": "6e771cafa4330cd6cba274040e8d0881f6a9b99dd566366fce266bd6f30b1ebf"
+      "sha256": "b1316f763acef47e6f6a01b61d7d92868e54b5ded091919ad1d2bd8991f10ab8"
     },
     {
       "path": "modules/discord/ship-broadcast.js",
@@ -7852,12 +7867,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "376f02b1d5253b7b790331c0f6639d16da022314d4a83c58ca10a9648337f01e"
+      "sha256": "9baa1aa306e1c7925d66fc09484dc2c214ad13fa47e4d71c39fc6d7ca2d6e8a6"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f8da5247d7da8fdcdb322b12a5ebb362315389a7049ea4d76160115066a6cf3f"
+      "sha256": "9b0fe6c23bdb7eb915bcb6d049e341258d1daa654a791355ac8ca92bfd58a02b"
     },
     {
       "path": "public-docs/index.html",
@@ -8717,7 +8732,7 @@
     {
       "path": "scripts/gds/plain-cards.js",
       "mode": "0000644",
-      "sha256": "7f54da72ae01fa7db57098e3dfd523f9f65a65efa316e8962b9cf7d60faf9be0"
+      "sha256": "63344839b3cb2cba39757b5501759aaef8e1bf100468d7304a56d4e709f2f8cf"
     },
     {
       "path": "scripts/gds/portability-smoke-art.sh",
@@ -9787,7 +9802,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5434f6390d888bb9c3181c449483867da3fd6637a8748fe98f0609cc57f75022"
+      "sha256": "3363fefd57cbb3a31327b1c613ebdd4a325e26071a575237a7e0ec467a3f74c7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9924,6 +9939,11 @@
       "mode": "0000644",
       "sha256": "eea8f9e0bdf2c84fabc81e16c30e4026a7a336c1e705d614e68b805957b9b74a"
     },
+    {
+      "path": "tests/agents_event_router.mjs",
+      "mode": "0000644",
+      "sha256": "919ca0ea3fe5f78a194781f6b634b9da23212073cf0c7cbe8ae36a65cc3fecdb"
+    },
     {
       "path": "tests/agents_routes.mjs",
       "mode": "0000644",
@@ -11682,12 +11702,12 @@
     {
       "path": "tests/hooks_drain.mjs",
       "mode": "0000644",
-      "sha256": "b75138bf26c8ff950f4a14ade3bbb6a53c9010014843217d200aad60edab72dc"
+      "sha256": "84ccd5167165bbf12aba03cdf444b0d94f1e7cc4b4dccbc37ed59afd01cf39cf"
     },
     {
       "path": "tests/host_topology_skips.mjs",
       "mode": "0000644",
-      "sha256": "7d384cd84cdc93b8e7b57df291a4600a40f43346fd2a52168324ecde219f1388"
+      "sha256": "22ac76bc38e6b52262a2afb664b6f883066daaa2864ad71d971f7ff2a6995d28"
     },
     {
       "path": "tests/hub_disconnect_ui.mjs",
@@ -13514,6 +13534,11 @@
       "mode": "0000644",
       "sha256": "eafd4354dc95fae94d720ed4cda05638eb5719c3ab0e3af084e7bf9d41b1be35"
     },
+    {
+      "path": "tests/stuck_detector.mjs",
+      "mode": "0000644",
+      "sha256": "005839daeb067c0de9c93e92f9bfc733c031fe572bf383cb29ea8105b56b8cd3"
+    },
     {
       "path": "tests/subdomain_auth.mjs",
       "mode": "0000644",

package/docs/adr/0302-the-third-identical-failure-stops-the-session-and-asks.md

@@ -0,0 +1,74 @@
+# ADR 0302 — The third identical failure stops the session and asks
+
+**Status:** accepted · **Date:** 2026-09-17 · **Task:** [task 1003990](https://cloudbongos.com/builders#/task/1003990) (goal 1000095 — BONGOS-V2)
+
+**Related:** [ADR 0301](0301-a-red-pr-names-its-failing-tests-in-a-commit-status.md) (a red PR names its failing tests) · [ADR 0291](0291-the-accessibility-dimension-scores-the-transcript-not-the-diff.md) (accessibility is scored after the ship) · [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) (no new gates on the ship path) · [ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) (cooperative, fail-open hook layer)
+
+## Context
+
+The 2026-09-17 investigation of a non-technical builder's stalls found sessions that looped
+without noticing: one pull request re-shipped into the same red check **nine times in four
+hours**, and **45 of 169 claim attempts** in 4.5 days were refusals — the same task id retried
+minutes apart. Each retry costs money the builder watches tick up, and they have no way to tell
+that the agent is going round in a circle (idea 1000281).
+
+Abandoned task 1002828 asked for a written bail-out rule. A rule in a memory file loses to the
+next retry for the same reason the `git stash` ban did: the agent is not looking at it at the
+moment it matters. Nothing else watches a session mid-flight — the accessibility score is
+computed after the ship.
+
+## Decision
+
+1. **Count walls, per session, in a hook.** `.claude/hooks/stuck-detector.js` runs after every
+   shell tool call (`PostToolUse` and `PostToolUseFailure`, `Bash|PowerShell`). On the **third**
+   identical wall — and each one after — it injects one instruction: stop retrying, diagnose
+   (the path is named), or run `/ask-for-help`.
+2. **The failure signature is the `[otb-plain]` card** (task 1003989). Every failure a builder
+   can be parked behind already prints one; its "What happened" line is static per failure code,
+   and its "By design" line already says whether a retry can ever help, which picks the
+   instruction's wording. Signature = that line + the task id in the command + the
+   `the PR is RED` line when present, so a red check that names *different* failing tests each
+   run reads as progress, not a wall. Only a builder CLI **run** (`node …scripts/gds/*.js`,
+   `bongos <verb>`) is read: `cat` or `git diff` over a file that quotes a card prints the
+   same text and is not a failure.
+3. **A waiting card is not a wall.** Cards whose next step is "Nothing to do…" (`land_pending`,
+   a pending check, a pending join request) tell the session to poll; counting them would turn
+   the detector against the behaviour the card asks for. The set is pinned by test.
+4. **The guards count through the same helper.** `git-guard.js` and `worktree-guard.js` call
+   `stuck-strikes.js` when they block — keyed on the rule, and on the file, respectively — and
+   append the instruction to the reason they already return. Three *different* wrong-tree files,
+   each corrected on the next call, is the guard working and is not counted.
+5. **It never blocks, and it echoes nothing.** `additionalContext` only, exit 0, silent without
+   a card. Signatures are hashed before they touch `os.tmpdir()`; the instruction interpolates a
+   count and a digits-only task id, never text a tool printed.
+
+## Alternatives rejected
+
+- **Count any repeated failing command.** Red → green on a test *is* the same command failing
+  repeatedly; the detector would fire on ordinary work and become wallpaper.
+- **Block the fourth attempt.** That is a new gate on the ship path (ADR 0162), and a wrong
+  signature match would strand a builder behind the tool meant to unstick them.
+- **Server-side detection.** The server sees refused claims but not guard blocks or local red
+  runs, and cannot speak into the session at the moment of the retry.
+- **Require `scripts/gds/plain-cards.js` from the hook.** Hooks are instance topology and the
+  script may live in the installed package; reading the printed card keeps the hook
+  dependency-free. The cost is a text coupling to the card's layout, pinned by test.
+
+## Consequences
+
+- Whether a non-zero exit routes to `PostToolUse` or `PostToolUseFailure` is the harness's
+  business; the hook is wired on both and reads the output from any of the four fields either
+  event has used. Only one event fires per call, so nothing is counted twice.
+- The count is per session and lives in the OS temp dir as an **append-only** log of hashed
+  signatures — tool calls run in parallel and three hooks share the file, so a
+  read-modify-write would let one process wipe another's counts. A builder who opens a fresh
+  session after being told to stop starts from zero — acceptable: the instruction's job is to
+  break the loop inside one context, and the refusal itself still stands.
+- Strikes do not decay inside a session: two hits, real progress, then a third hit hours later
+  still draws the instruction. It costs one paragraph the agent can weigh, and a time window
+  short enough to matter would have missed PR 922's runs, which were ~27 minutes apart.
+- A box that cannot read which test failed gets a RED line with no names, so three red runs
+  share a signature whatever their causes. That is the PR 922 case the detector exists for;
+  the instruction says to run the suite locally when the status names nothing.
+- A failure with no plain card is invisible to the detector. `tests/plain_cards.mjs` already
+  reds when a CLI gains a failure code without one, so the two stay in step.

package/docs/adr/README.md

@@ -393,3 +393,4 @@ This keeps the decision history honest and traceable.
 | 0299 | [**The nod queue stays scoped to routed filings; the backlog walk is the widening** ([task 1003748](https://cloudbongos.com/builders#/task/1003748), goal 1000089). `listRoutedAwaitingNod` filters `origin='route'`, and on 2026-09-08 showed 11 of 232 backlog rows. Re-measured after `/backlog-review` (task 1003746) shipped: 115 backlog rows = 109 dep-gated + 2 spikes (not a person's decision) + 1 stranded + 3 awaiting a nod, all four walked by `/backlog-review`. **Decision: do not widen the card.** The omitted population already has a walkable review with the dependency predicate any widening needed; the copy says *reported* work, so the name is honest; a card slice would be a second copy of the walk's four-bucket partition. Revisit if the un-routed nod bucket outgrows a daily walk (then a count + link, derived from the same partition) or if the walk stops being run.](0299-the-nod-queue-stays-scoped-to-routed-filings.md) | ideas / backlog / attention |
 | 0300 | [**A missing protected-surface registry is a broken install, not a module opt-out** ([task 1003662](https://cloudbongos.com/builders#/task/1003662), goal 1000091). Filed as a bug with a remedy attached: `require('./module-scope-map')` throws when `modules/government/protected-surfaces.json` is absent, so make it degrade to an empty protected set + a warning, matching `resolveOptional`. The throw reproduces, and the rest is wrong four times over. **The throw is not in the named file** — `module-scope-map.js` has no throw and no file read; it requires `permission-path-check.js`, whose `loadRegistry()` throws at module scope. **It is a written contract, not an oversight** — that file's header says FAIL-CLOSED in capitals and already pre-answers the layering worry (the read is `fs`, never `require`, so ADR 0083's one-way rule holds; static data, not code; `route-rank-check.js` reads `modules/*/routes/*.js` the same way). **Disabling the module cannot cause it** — enablement is a runtime flag, never a file deletion, and the read never consults it. **"Not yet materialized" cannot either** — no `files[]` allowlist, so `npm pack --dry-run` puts the 13,274-byte registry in the tarball; per ADR 0108 §1 you cannot have `@bongos/core` without it. The `resolveOptional` precedent does not transfer: that is the module **seam/port** resolver for a missing runtime *capability*, whereas this is the static data the boundary is made of, read where there is no server and no DB (a git hook, a CI job) — borrowing it converts "the boundary is unreadable" into "there is no boundary". **Decision: fail-closed stays, no behavior change, the remedy is rejected — and the one genuine defect is fixed: the message now names the cause and the fix** (reinstall the core; do not empty the set), because stating a refusal without a remedy is exactly how a reader concludes the module is optional and files this task. The asymmetry is the point: a false "nothing is protected" is silent, permanent and grants authority; a false "this install is broken" is loud and grants nothing. Revisit only if a core-only checkout without `modules/` becomes legitimate — and then the question is *where the registry lives*, not whether it is optional.](0300-a-missing-protected-surface-registry-is-a-broken-install.md) | governance / permissions |
 | 0301 | [**A red PR names its failing tests in a commit status, and says so when it cannot see** ([task 1003988](https://cloudbongos.com/builders#/task/1003988), goal 1000095). One pull request took nine red CI runs in four hours because the builder box could not learn which test failed: without Checks:read GitHub nulls every check-run node, the server dropped the holes silently, and the red PR was reported as a review-or-pending wait. Now the merge state carries checks_unreadable and a red, unreadable rollup reads failing_check_unreadable; the unit workflow posts the failing test names as a unit-report commit STATUS (readable without the permission) from a separate job that holds the only write token and checks out no PR code; the server returns it as failing_tests, reduced to test-list vocabulary because the PR controls the workflow that wrote it.](0301-a-red-pr-names-its-failing-tests-in-a-commit-status.md) | GDS / shipping pipeline |
+| 0302 | [**The third identical failure stops the session and asks** ([task 1003990](https://cloudbongos.com/builders#/task/1003990), goal 1000095). Sessions looped without noticing: one PR re-shipped into the same red check nine times, and 45 of 169 claim attempts were the same refusal retried minutes apart. A PostToolUse hook now counts walls per session — the signature is the `[otb-plain]` card's "What happened" line + the task id + the RED line, so a red check naming different failing tests each run reads as progress — and on the third identical one injects a single instruction: stop retrying, diagnose (path named), or /ask-for-help. Waiting cards ("Nothing to do…") are never counted; git-guard and worktree-guard count their own blocks through the same helper; it never blocks a tool call and echoes nothing a tool printed. Rejected: counting any repeated failing command (red→green is that), blocking the fourth attempt (a new gate, ADR 0162), server-side detection (cannot see guard blocks or speak into the session).](0302-the-third-identical-failure-stops-the-session-and-asks.md) | GDS / sessions / hooks |

package/docs/file-map.md

@@ -490,6 +490,8 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 ├── conductor.js              ← UserPromptSubmit: MAS Conductor advisory + dispatch directive (#427/#439); self-gates on OTB_CONDUCTOR_OFF / OTB_SUBAGENT
 ├── session-cards.js          ← UserPromptSubmit: deterministic delivery of READ-ONLY in-session cards (builder-start, status) — pre-renders the card + injects a one-step render directive (task 1288)
 ├── lifecycle-card.js         ← PostToolUse: deterministic delivery of MUTATING lifecycle cards (claim/ship/release) — the write-side mirror of session-cards.js (task 1288)
+├── stuck-detector.js         ← PostToolUse + PostToolUseFailure (Bash|PowerShell): the third time one session hits the same wall — the same `[otb-plain]` card for the same task id, or the same red check — it injects ONE instruction: stop retrying, diagnose (path named), or /ask-for-help. Never blocks; silent with no card; kill-switch BONGOS_STUCK_DETECTOR_OFF=1 (task 1003990)
+├── stuck-strikes.js          ← shared helper, not a hook: the per-session strike counter (hashed signatures in os.tmpdir()) + the static instruction text; stuck-detector.js, git-guard.js and worktree-guard.js all count through it (task 1003990)
 ├── pre-compact.js            ← PreCompact: thin reader around eviction-policy.js — emits an eviction directive (blocks to drop + one-line recovery stubs) at the compaction seam (task 1349)
 ├── eviction-policy.js        ← pure deterministic in-session compaction classifier (transcript turns → eviction set + replacement stubs); no I/O, unit-tested in tests/eviction_policy.mjs; consumed by pre-compact.js (task 1348)
 └── stop-refcheck.js          ← Stop: deterministic backstop that catches a bare `#NNN` Bongos ref in live session text (autolinks to a 404 GitHub issue) and asks for the clickable form (follow-on to task 929)

package/docs/module-api-changelog.md

@@ -2148,5 +2148,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.835 with no explicit bump. run 35247495964. (task 1002620)
   1.19.837 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.836 with no explicit bump. run 35248928789. (task 1002620)
+  1.19.838 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.837 with no explicit bump. run 35250225228. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/agents/migrations/agents_003_output_ref_idx.sql

@@ -0,0 +1,41 @@
+-- agents_003_output_ref_idx.sql — the index the DEPTH GUARD reads (task 1002494).
+--
+-- agents_001 gave `agents_runs` three indexes, each built for a question someone
+-- was already asking: per-agent history, walk-forward from a trigger, and the
+-- monthly spend rollup. `output_ref` was not one of them, because until now
+-- nothing read it as a KEY — it was a pointer you followed after you already had
+-- the row.
+--
+-- The event-router reads it the other way round. Its loop guard asks "does any
+-- run's output_ref name this ship?" (`WHERE output_ref = ANY($1::text[])`) on
+-- EVERY fan-out that gets past the touches[] pre-filter — and `agents_runs` is
+-- append-only, growing with every fire AND every refusal, so without this the
+-- guard is a sequential scan over a table that only ever gets longer. The guard
+-- is also FAIL-CLOSED: a read slow enough to time out reads as "attributed" and
+-- silently stops agents firing at all, which is the failure mode that looks like
+-- nothing is wrong.
+--
+-- PARTIAL, on `output_ref IS NOT NULL`. Most rows have none — every no-go is a
+-- row (a refusal that leaves no trace is indistinguishable from a fire that
+-- never happened), and a successful fire with nothing to report writes none
+-- either, which is the outcome most fires should have. The lookup only ever
+-- matches a non-null value, so the nulls are dead weight in the index exactly as
+-- agents_001's own spend index argues about its own nulls.
+--
+-- NOT UNIQUE, deliberately. Two agents may each report on the same ship, and the
+-- `discord` sink's pointer is `discord:<channel>:<taskId>` — stable by
+-- construction, so a re-post of the same subject collides by design. A unique
+-- index would turn a legitimate second observation into an insert failure inside
+-- a fire that already cost money.
+--
+-- Module migrations are ADDITIVE and NAMESPACED (ADR 0083 §Decision #5): the
+-- object is agents_-prefixed, there is no down-migration, and the filename is
+-- agents_-prefixed (ADR 0108 §5). Idempotent: safe to re-run.
+
+BEGIN;
+
+CREATE INDEX IF NOT EXISTS agents_runs_output_ref_idx
+  ON agents_runs (output_ref)
+  WHERE output_ref IS NOT NULL;
+
+COMMIT;

package/modules/agents/module.json

@@ -5,7 +5,7 @@
   "coreVersion": "^1.19.0",
   "default": false,
   "maintenance": { "status": "core-maintained" },
-  "contributes": { "routes": ["agents"], "migrations": true },
+  "contributes": { "routes": ["agents"], "pollers": ["event-router"], "migrations": true },
   "spend": { "requiresPayer": true },
   "provides": [],
   "consumes": ["grade"]