@bongos/core 1.19.845 → 1.19.847

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.845",
-  "core_contract": "1.19.845",
-  "source_commit": "5b6a49f8f6e903a829ce733c7fa198fc5fb56341",
+  "core_version": "1.19.847",
+  "core_contract": "1.19.847",
+  "source_commit": "2f39aee80129563c843fb3b14b31a00db502f851",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T19:09:03.983Z",
+  "built_at": "2026-09-17T19:42:18.427Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 495,
+    "docs_redacted": 496,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2272,
+    "functional_verbatim": 2273,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2793,
-  "tree_sha256": "7082ae84102704894dfb0addd6bd5f72c3e3fb82767acdeda4c8489543d67aaa",
+  "file_count": 2795,
+  "tree_sha256": "6e729d424a5377af457b9b765d44e5af905a4228a5f2df22ee259583224231a0",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2009,10 +2009,15 @@
       "mode": "0000644",
       "sha256": "62ffb9c1aeeaaafd5c51767f1ffff1c67adb3563e8d55ceb81ef77511184faa4"
     },
+    {
+      "path": "docs/adr/0304-routine-reads-run-without-a-prompt-and-anything-a-flag-can-turn-into-a-write-is-exact-form.md",
+      "mode": "0000644",
+      "sha256": "104b5675fe52c1725dbbc78ab6fde9fd676b4020bf0e3f05411733c95d4342e0"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "48323e44fced698a0da997eeb16564ab3b04430c8233a8f7997c0fec2b123401"
+      "sha256": "61dd72c5f0d4157062fb93585252448e5493afd25cb014fb747bf0e20037a2ab"
     },
     {
       "path": "docs/api-reference.md",
@@ -2567,7 +2572,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "b575f34143de0be30fadfd63bea76f77305fa175beee3960291414ff6b55d611"
+      "sha256": "eaa7dca723187a394a3b6ee252bbb81b13b76cc384a4651b6ee74a859af9d611"
     },
     {
       "path": "docs/handoff-template.md",
@@ -2577,7 +2582,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "86ddda19705a19edeadcdb048bdcaa429534f4cc9033fcf730f31663dc06b2e7"
+      "sha256": "6ba668dea0868f1ab54467d18278e494c3fc4eb121d19313c6d85d2c80d89e63"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7902,12 +7907,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "359df85b8fed3ee87c46b3eedb3c194f6d2bdd617577172ddf8f3ba21583d4a3"
+      "sha256": "6adf112f9a6622910cb13b7dd741da5a7d1c84976c286e13068974bb8717c629"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "35c760c7bc338c24c0f71075f5c578cb0b75a0d5bf2663f091e2a77722c5bcf9"
+      "sha256": "f7dc6b6b5522f7b4e1bddf7f62cd371fda49d1304497cb6b5de979c5f7a2ac93"
     },
     {
       "path": "public-docs/index.html",
@@ -8217,7 +8222,7 @@
     {
       "path": "scripts/gds/claude-materialize.js",
       "mode": "0000644",
-      "sha256": "53411af3a058d5fb22029a2ae923ef259fb1a45b1e39c20fd28e004a8c4d369f"
+      "sha256": "de8dcb51a250334621b104e99f7bc5f857f4422718c3c3ed8519cd5d0ebc8739"
     },
     {
       "path": "scripts/gds/claude-md-template.js",
@@ -9842,7 +9847,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "af8e3015ca7eeb60f3c6ee804d7212fdd17fe7010c81d84de453fb1ad60f6598"
+      "sha256": "c2347ac91ce5aa5e5f46bcb3e0734bd151e2abbe1f2347290d75891229223a17"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10407,7 +10412,7 @@
     {
       "path": "tests/box_ship_permissions.mjs",
       "mode": "0000644",
-      "sha256": "5347fc776e8edb533223534707ddc7085af21654298d9d2169d711ecc5cfce2c"
+      "sha256": "063c94d759fa8a79b8c402145801ae2a4d9863bef591fb5adf57697e15effc39"
     },
     {
       "path": "tests/box_sync.mjs",
@@ -10562,7 +10567,7 @@
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
-      "sha256": "7acfe432856010881b234b258d45fcf65f976e0e711d01b823d90990a0c7179c"
+      "sha256": "42df08d261aaeb7cf94db3eef0e95b06af138d8d317b57f12dc4cb2c23d9f81a"
     },
     {
       "path": "tests/clawback_confirmed_backlog.mjs",
@@ -11127,7 +11132,7 @@
     {
       "path": "tests/git_guard.mjs",
       "mode": "0000644",
-      "sha256": "1b0b13310fb1afa544784d18fe0fa3ac2abc0f5ecc01e3ec0cb71c227df296ae"
+      "sha256": "95ec763418aceec86f239edc1e78154c0fb9f67ffcb566c3062c75eceeb09b24"
     },
     {
       "path": "tests/git_merge_regen.mjs",
@@ -11744,6 +11749,11 @@
       "mode": "0000644",
       "sha256": "7035673d4b9e55166acc19d5c40a2128c0aceb233bca6856eace34bebc1139e4"
     },
+    {
+      "path": "tests/hook_shell_tools.mjs",
+      "mode": "0000644",
+      "sha256": "88db0fedd800ad8a8f6fd9d912844238bfb7bb944d5bf648eb8818eca6854466"
+    },
     {
       "path": "tests/hook_user_agents.mjs",
       "mode": "0000644",
@@ -12052,7 +12062,7 @@
     {
       "path": "tests/lifecycle-card.mjs",
       "mode": "0000644",
-      "sha256": "3bf8585f0cb4afa7db94d3a8db37d0fea34336dfab3053f518aae029199b1563"
+      "sha256": "a308fb62ff11b442c20e3eeb3eb9617a1b3ad1abcba4ec4b2cc6b349b3e6aa5e"
     },
     {
       "path": "tests/lifecycle_breakdown_view.mjs",
@@ -13152,7 +13162,7 @@
     {
       "path": "tests/secret_gate.mjs",
       "mode": "0000644",
-      "sha256": "20de62b7d869763c703317dae4bc3896cbf4308d1211c8fcbffbfbd32465b1b5"
+      "sha256": "46ea51955dbcc4874684fdb06b298e744e7e019d2f3971ae7953d37ede96958a"
     },
     {
       "path": "tests/security_docs.mjs",

package/docs/adr/0304-routine-reads-run-without-a-prompt-and-anything-a-flag-can-turn-into-a-write-is-exact-form.md

@@ -0,0 +1,84 @@
+# ADR 0304 — Routine reads run without a prompt; anything a flag can turn into a write is exact-form
+
+**Status:** accepted · **Date:** 2026-09-17 · **Task:** [task 1003992](https://cloudbongos.com/builders#/task/1003992) (goal 1000095 — BONGOS-V2)
+
+**Related:** [ADR 0104](0104-trust-gds-api-channel-in-auto-mode.md) (the allow-list this extends — it named read wrappers as the next step) · [ADR 0016](0016-trust-boundary-server-enforced-permissions.md) (an allow-rule grants no authority) · [ADR 0043](0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md) (git-guard is the cooperative layer) · [ADR 0302](0302-the-third-identical-failure-stops-the-session-and-asks.md) (same investigation)
+
+## Context
+
+The shipped `.claude/settings.json` pre-allowed six commands. Much of what a session runs to look
+around — `gh pr view`, `git fetch origin`, `node scripts/gds/status.js` — stopped and asked the
+builder for permission. The 2026-09-17 investigation of a non-technical builder's stalls found
+this is a prompt they cannot evaluate: they are asked to approve a command they do not read, many
+times an hour, and the only safe answer they have is "yes". A prompt that is always answered yes
+protects nothing and teaches the builder to stop reading prompts.
+
+## Decision
+
+Pre-allow the **read-only subset**, in the core's `.claude/settings.json` and — rule for rule, in
+verb form — in the starter an instance receives (`STARTER_ALLOW`, task 1003962):
+
+- `git status` as a prefix rule.
+- `git branch` and `git fetch` as **exact forms only** (`git branch --list`, `--show-current`,
+  `-a`, `-vv`; `git fetch`, `git fetch origin`, `git fetch origin main`).
+- `gh pr view | checks | list` and `gh run view | list` as prefix rules.
+- The gds CLIs audited read-only under every flag they accept: `start`, `status`, `recall`, `me`,
+  `doctor`, `preflight`, `skill-preflight`, `ship-check`, `fitness`, `strand-watch`,
+  `stale-worktrees`, `read-session-export`. (`recall` POSTs, but to the search endpoint — a query.
+  `ship-check` and `fitness` run the repo's own checks, the same trust as the already-allowed
+  `ship.js`: a rule naming a script in the tree trusts the tree.) Audited and left out:
+  `backlog-review.js`, whose default walk POSTs promote / abandon, and `key-status.js`, whose
+  `--recheck` rewrites the local session file.
+
+**The rule behind the split.** `Bash(x:*)` is a prefix rule: it allows every flag that can follow
+`x`. So a command gets a prefix rule only when no flag turns it into a write or an exec.
+`git fetch --upload-pack=<cmd>` runs a command, `git fetch origin x:main` moves a local branch, and
+`git branch -D` deletes one — so those two subcommands are listed in the exact forms a session
+actually uses, and anything else under them still asks.
+
+**`git diff`, `git log` and `git show` get no rule at all.** The task asked for them, the first
+cut had them as prefix rules, and review caught what that did — both reproduced on this repo:
+`git log -1 --format=<text> --output=<path>` writes chosen content to any path (a
+`.git/hooks/pre-push` is code execution), and `git diff --no-index -- /dev/null <path>` prints any
+file, including the ones the `Read(...)` deny-list protects. Claude Code already runs the
+read-only forms of these commands without a prompt in every permission mode, and checks their
+flags when it does; an allow-rule is matched first and switches that check off. So for these three
+the rule bought nothing and cost the flag check. By this ADR's own test they fail it.
+
+**git-guard stays the backstop, and the lists are pinned.** A PreToolUse hook runs whether or not
+a command is pre-allowed, so git-guard still blocks its four shapes. `tests/box_ship_permissions.mjs`
+goes further: no allow-rule may *cover* a command git-guard blocks (blocked samples per guard rule;
+a new guard rule fails the suite until it has one); no allow-rule may cover a write dressed as a
+read (`--output`, `--no-index`, `--upload-pack`, a refspec); and the whole allow-list is pinned —
+every rule is a named gds script or one of the thirteen git/gh strings in the test — so
+widening it is a deliberate, reviewed edit.
+
+## Consequences
+
+- A session on a laptop or a box in auto mode reads PR and CI state, fetches, and runs the
+  read-only gds CLIs without interrupting the builder. `bypassPermissions` boxes are unaffected
+  (the rules are a no-op there).
+- An allow-rule matches the command text, not the program: it is a convenience, never a security
+  boundary. That is why the dangerous cases are handled by *not writing the rule* rather than by an
+  `ask` or `deny` pattern for `--output` — Claude Code's own docs note such argument patterns are
+  evaded by quoting (`--out''put`).
+- Rules are `Bash` only — the evidence is a hosted Linux box. `PowerShell(...)` twins are a
+  follow-up ([task 1004014](https://cloudbongos.com/builders#/task/1004014)), possible now that
+  [task 1003999](https://cloudbongos.com/builders#/task/1003999) has put that tool behind the same
+  guards; allowing first and guarding second was the wrong order.
+- An instance that already has a `.claude/settings.json` keeps its own; only a fresh starter carries
+  the new rules (the never-clobber rule of task 1003962).
+
+## Rejected
+
+- **`Bash(git:*)` or `Bash(gh:*)`.** One rule instead of thirteen, and it pre-allows `git push`,
+  `git reset --hard`, `gh pr merge` and `gh api -X DELETE`.
+- **Prefix rules for `git diff | log | show`, with `ask` rules for `--output` and `--no-index`.**
+  Evaluated in the order deny → ask → allow, so it works on the text a session normally writes — and
+  is evaded by quoting. The harness's built-in handling already covers the safe forms, so the pair
+  of rules would add a leaky guard to remove a prompt that does not exist.
+- **Prefix rules for `git fetch` / `git branch --list`.** `git branch --list -D x` is covered by the
+  prefix and blocked by git-guard — harmless in practice (git refuses the combination) but it makes
+  "nothing the guard blocks is allowed" false, and that sentence is worth keeping true.
+- **`bypassPermissions` everywhere** (task 1251's box default). It is a mode, not a list: a builder
+  who cycles modes or works from a laptop is back to prompts, and it removes the prompt for writes too.

package/docs/adr/README.md

@@ -395,3 +395,4 @@ This keeps the decision history honest and traceable.
 | 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 |
 | 0303 | [**Provisioning verifies the base Caddyfile, and never edits it** ([task 1002860](https://cloudbongos.com/builders#/task/1002860), goal 1000106, from idea 1000524). The runner assumed the box's `/etc/caddy/Caddyfile` carried the `on_demand_tls` tls-check ask and `import /etc/caddy/sites/*.caddy`, and reloaded with `allowFail` — a box missing either provisioned "successfully" and the instance was unreachable. It now reads Caddy's RESOLVED config (`caddy adapt`: unprivileged, no key access, indifferent to how the directives are written) before touching the box (the ask) and after writing the snippet (the domain is served ⇒ the import reaches it), refusing with the exact line to add, and the reload is loud. Rejected: editing the base file (`on_demand_tls` must sit inside the global block an append cannot place, and a bad write takes down the control plane's own apex); `caddy validate` (loads certificate keys, needs root).](0303-provisioning-verifies-the-base-caddyfile-and-never-edits-it.md) | provisioning / infra |
+| 0304 | [**Routine reads run without a prompt; anything a flag can turn into a write is exact-form** ([task 1003992](https://cloudbongos.com/builders#/task/1003992), goal 1000095). The shipped `.claude/settings.json` pre-allowed six commands, so every `gh pr view` or `git fetch` asked a non-technical builder to approve a command they cannot evaluate. The read-only subset is now pre-allowed — `git status`, `gh pr view/checks/list`, `gh run view/list` and the gds CLIs audited read-only under every flag as prefix rules; `git branch` and `git fetch` as exact forms only, because a flag turns either into a write or an exec — and the instance starter mirrors it rule for rule. `git diff/log/show` get NO rule: the harness already runs their read-only forms unprompted with a flag check, and a prefix rule switched that check off (`--output=<path>` writes anywhere, `diff --no-index` reads deny-listed files — both reproduced in review). A test pins the whole allow-list, that no rule covers a command git-guard blocks, and that no rule covers a write dressed as a read. Rejected: `Bash(git:*)`, prefix-plus-`ask` for diff/log/show (argument patterns are evaded by quoting), prefix rules for fetch/branch, `bypassPermissions` everywhere.](0304-routine-reads-run-without-a-prompt-and-anything-a-flag-can-turn-into-a-write-is-exact-form.md) | GDS / sessions / permissions |

package/docs/file-map.md

@@ -475,10 +475,10 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 
 ```
 .claude/hooks/
-├── secret-gate.js            ← PreToolUse (Edit|Write|MultiEdit|NotebookEdit|Bash): cooperative, fail-OPEN block of secret-shaped content before it reaches the tree or a shell (task 1003125, ADR 0022)
+├── secret-gate.js            ← PreToolUse (Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell): cooperative, fail-OPEN block of secret-shaped content before it reaches the tree or a shell (task 1003125, ADR 0022)
 ├── run-node.sh               ← the node resolver every hook command runs through (task 1003548): $OTB_NODE_BIN → PATH → known install dirs → nvm; one actionable line + exit 1 when none is found. 1,055 hook runs had died silently with `node: command not found`
 ├── edit-hints.js             ← PostToolUse (Edit|Write|MultiEdit): lints a saved SKILL.md's frontmatter (scripts/gds/skill-lint.js) and names the generator an edited path makes stale (copy-registry, repo-map blocks, file-map, openapi, §13 snippet) with its command (task 1003548)
-├── git-guard.js              ← PreToolUse (Bash): same contract as secret-gate — blocks `git stash` (repo-global stack, learning 1000215), raw `git worktree remove` (follows the node_modules junction, task 1002809), `git push origin main` (PR-only) and `git branch -D`, each with its remedy; kill-switch BONGOS_GIT_GUARD_OFF=1 (task 1003365)
+├── git-guard.js              ← PreToolUse (Bash|PowerShell): same contract as secret-gate — blocks `git stash` (repo-global stack, learning 1000215), raw `git worktree remove` (follows the node_modules junction, task 1002809), `git push origin main` (PR-only) and `git branch -D`, each with its remedy; kill-switch BONGOS_GIT_GUARD_OFF=1 (task 1003365)
 ├── _core-resolve.js          ← shared helper, not a hook: locates a core module/script across the monolith vs `node_modules/@cloudbongos/core` layouts; required by most hooks here and by four routine scripts under `.claude/scheduled-tasks/`
 ├── cascade-route.js          ← PreToolUse (Task|Agent): cheapest-sufficient start-model advisory for a subagent spawn (ADR 0024); inert unless OTB_AUTONOMY_ENABLED=1
 ├── land-watch-card.js        ← UserPromptSubmit: delivers the SHIPPED banner once an async CI land completes (reads `scripts/gds/land-watch.js`)
@@ -489,8 +489,9 @@ To install on a new machine, symlink each routine's directory under `~/.claude/s
 ├── recall-hints.js           ← SessionStart: when the session opens holding a claim, surface the top project-knowledge hits for that task via POST /api/gds/search (#963/V4.R25, ADR 0060)
 ├── 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)
+├── lifecycle-card.js         ← PostToolUse (Bash|PowerShell): 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)
+├── shell-tools.js            ← shared helper, not a hook: the ONE list of tool names that carry a shell command (`Bash`, `PowerShell`) + the `matcher` string the settings entries must use. git-guard, secret-gate, lifecycle-card and stuck-detector all test through it; four private copies of `Bash` had left every Windows session unguarded, silently (task 1003999, pinned by tests/hook_shell_tools.mjs)
 ├── 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)

package/docs/module-api-changelog.md

@@ -2164,5 +2164,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.843 with no explicit bump. run 35262101669. (task 1002620)
   1.19.845 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.844 with no explicit bump. run 35263096514. (task 1002620)
+  1.19.846 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.845 with no explicit bump. run 35264882014. (task 1002620)
+  1.19.847 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.846 with no explicit bump. run 35266409194. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.845",
+  "version": "1.19.847",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.845",
+      "version": "1.19.847",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.845",
+  "version": "1.19.847",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/claude-materialize.js

@@ -347,6 +347,37 @@ const STARTER_ALLOW = [
   'Bash(bongos reauth:*)',
   'Bash(bongos paste-token:*)',
   'Bash(bongos exec scripts/gds/api.js:*)',
+  // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
+  // are exact forms on purpose: a flag turns either into a write or an exec. No
+  // `git diff|log|show` rule, also on purpose: the harness already runs their
+  // read-only forms unprompted, and a prefix rule would switch off its flag check
+  // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
+  // tests/box_ship_permissions.mjs pins this list to the core's, rule for rule.
+  'Bash(bongos start:*)',
+  'Bash(bongos status:*)',
+  'Bash(bongos recall:*)',
+  'Bash(bongos exec scripts/gds/me.js:*)',
+  'Bash(bongos doctor:*)',
+  'Bash(bongos exec scripts/gds/preflight.js:*)',
+  'Bash(bongos exec scripts/gds/skill-preflight.js:*)',
+  'Bash(bongos exec scripts/gds/ship-check.js:*)',
+  'Bash(bongos exec scripts/gds/fitness.js:*)',
+  'Bash(bongos exec scripts/gds/strand-watch.js:*)',
+  'Bash(bongos exec scripts/gds/stale-worktrees.js:*)',
+  'Bash(bongos exec scripts/gds/read-session-export.js:*)',
+  'Bash(git status:*)',
+  'Bash(git branch --list)',
+  'Bash(git branch --show-current)',
+  'Bash(git branch -a)',
+  'Bash(git branch -vv)',
+  'Bash(git fetch)',
+  'Bash(git fetch origin)',
+  'Bash(git fetch origin main)',
+  'Bash(gh pr view:*)',
+  'Bash(gh pr checks:*)',
+  'Bash(gh pr list:*)',
+  'Bash(gh run view:*)',
+  'Bash(gh run list:*)',
 ];
 
 // The starter an instance gets when the core root carries no settings.json — a

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.845'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.847'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_ship_permissions.mjs

@@ -12,11 +12,15 @@ import { strict as assert } from 'node:assert';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { skipUnlessPresent } from './helpers.mjs';
+import { createRequire } from 'node:module';
+import { skipUnlessPresent, requireHostModule } from './helpers.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const settingsPath = path.join(__dirname, '..', '.claude', 'settings.json');
 skipUnlessPresent('.claude/settings.json');
+const require = createRequire(import.meta.url);
+const guard = requireHostModule(require, '../.claude/hooks/git-guard.js');
+const { STARTER_ALLOW, bongosify } = require('../scripts/gds/claude-materialize.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -68,6 +72,131 @@ test('every allow-rule points at a script that actually exists (no inert rules)'
   }
 });
 
+// ---------------------------------------------------------------------------
+// task 1003992 — the read-only subset (ADR 0304). A non-technical builder was
+// interrupted for every `gh pr view` and `git fetch`; those are now pre-allowed.
+// An allow-rule skips the prompt, so the list must never reach a command
+// git-guard blocks, and must stay read-only.
+// ---------------------------------------------------------------------------
+
+// How Claude Code reads a Bash rule: `Bash(x:*)` covers x and anything starting
+// "x "; `Bash(x)` covers exactly x. A chained command is covered only when every
+// part is, so `git status && git stash` is not covered by a `git status` rule.
+function ruleCovers(rule, part) {
+  const m = rule.match(/^Bash\((.*?)(:\*)?\)$/);
+  if (!m) return false;
+  return part === m[1] || (Boolean(m[2]) && part.startsWith(`${m[1]} `));
+}
+function allowCovers(allow, command) {
+  const parts = command.split(/&&|\|\||[;|&\n]/).map((s) => s.trim()).filter(Boolean);
+  return parts.every((part) => allow.some((rule) => ruleCovers(rule, part)));
+}
+const isBlocked = (command) => guard.decide({ tool_name: 'Bash', tool_input: { command } }, {}).block;
+
+// At least one sample per git-guard rule, keyed by the rule's own name.
+const BLOCKED_SAMPLES = {
+  'git stash': ['git stash', 'git stash pop', 'git stash push -m wip', 'git status && git stash'],
+  'git worktree remove': ['git worktree remove ../wt', 'git worktree remove --force ../wt'],
+  'git push origin main': ['git push origin main', 'git push -u origin HEAD:main', 'git push --force origin task-1:main'],
+  'git branch -D': ['git branch -D task-1', 'git branch --list -D task-1', 'git branch -a -D task-1'],
+};
+
+test('every git-guard rule has blocked samples here (a new rule forces a new sample)', () => {
+  for (const [name] of guard.RULES) {
+    assert.ok((BLOCKED_SAMPLES[name] || []).length, `no blocked sample for git-guard rule "${name}"`);
+  }
+  for (const samples of Object.values(BLOCKED_SAMPLES)) {
+    for (const cmd of samples) assert.ok(isBlocked(cmd), `sample is not actually blocked by git-guard: ${cmd}`);
+  }
+});
+
+test('no allow-rule covers a command git-guard blocks', () => {
+  const allow = settings.permissions.allow;
+  for (const rule of allow) {
+    const text = rule.replace(/^Bash\(/, '').replace(/(:\*)?\)$/, '');
+    assert.ok(!isBlocked(text), `allow-rule is itself a git-guard-blocked command: ${rule}`);
+  }
+  for (const cmd of Object.values(BLOCKED_SAMPLES).flat()) {
+    assert.ok(!allowCovers(allow, cmd), `an allow-rule covers a git-guard-blocked command: ${cmd}`);
+  }
+});
+
+test('the check has teeth: a too-broad git rule IS caught', () => {
+  const samples = Object.values(BLOCKED_SAMPLES).flat();
+  for (const broad of ['Bash(git:*)', 'Bash(git stash:*)', 'Bash(git worktree:*)', 'Bash(git push:*)', 'Bash(git branch:*)', 'Bash(git branch --list:*)']) {
+    assert.ok(samples.some((cmd) => allowCovers([broad], cmd)), `${broad} should cover a blocked sample`);
+  }
+});
+
+// The whole git/gh allow-list, pinned. A flag can turn a read into a write or an
+// exec (`git fetch --upload-pack=<cmd>`, `git fetch origin x:main`, `git branch -D`),
+// so `branch` and `fetch` appear only as the exact commands a session runs.
+//
+// NO `git diff|log|show` rule, on purpose. Claude Code already runs their read-only
+// forms without a prompt in every mode and checks their flags; a prefix rule would
+// switch that check off (see WRITES_DRESSED_AS_READS below — both were reproduced).
+const GIT_GH_RULES = [
+  'Bash(git status:*)',
+  'Bash(git branch --list)', 'Bash(git branch --show-current)', 'Bash(git branch -a)', 'Bash(git branch -vv)',
+  'Bash(git fetch)', 'Bash(git fetch origin)', 'Bash(git fetch origin main)',
+  'Bash(gh pr view:*)', 'Bash(gh pr checks:*)', 'Bash(gh pr list:*)', 'Bash(gh run view:*)', 'Bash(gh run list:*)',
+];
+// gds CLIs audited read-only under EVERY flag they take — a prefix rule allows them all.
+// Audited and left OUT: backlog-review.js (POSTs from its default walk) and
+// key-status.js (`--recheck` rewrites the local session file).
+const READ_ONLY_CLIS = ['start', 'status', 'recall', 'me', 'doctor', 'preflight', 'skill-preflight',
+  'ship-check', 'fitness', 'strand-watch', 'stale-worktrees', 'read-session-export'];
+const BLESSED_WRITERS = ['ship', 'claim', 'reauth', 'release', 'paste-token', 'api']; // tasks 1051 / 1716
+
+const SCRIPT_RULE = /^Bash\(node scripts\/gds\/([a-z-]+)\.js:\*\)$/;
+
+test('every allow-rule that is not a gds script is in the pinned git/gh set (adding one is a deliberate edit here)', () => {
+  // Catches `Bash(gh:*)`, `Bash(gh *)`, `Bash(git -C x status:*)`, a bare `Bash` — anything unlisted.
+  const rest = settings.permissions.allow.filter((rule) => !SCRIPT_RULE.test(rule));
+  assert.deepEqual([...rest].sort(), [...GIT_GH_RULES].sort());
+});
+
+// "Read" commands whose flags write a file, read one the Read deny-list protects,
+// run a command, or move a branch. None may ever run without a prompt.
+const WRITES_DRESSED_AS_READS = [
+  "git log -1 --format='#!/bin/sh' --output=.git/hooks/pre-push",
+  'git show --output=/tmp/x HEAD',
+  'git diff --output=/tmp/x',
+  'git diff --no-index -- /dev/null .env',
+  'git fetch --upload-pack=./x origin',
+  'git fetch origin task-1:main',
+];
+
+test('no allow-rule lets a write dressed as a read through (--output, --no-index, --upload-pack, a refspec)', () => {
+  for (const cmd of WRITES_DRESSED_AS_READS) {
+    assert.ok(!allowCovers(settings.permissions.allow, cmd), `runs without a prompt: ${cmd}`);
+  }
+  // Teeth: the prefix rules this list deliberately does NOT carry would let them through.
+  const tempting = ['Bash(git log:*)', 'Bash(git show:*)', 'Bash(git diff:*)', 'Bash(git fetch:*)'];
+  for (const cmd of WRITES_DRESSED_AS_READS) assert.ok(allowCovers(tempting, cmd), `teeth: ${cmd}`);
+});
+
+test('every gds-script allow-rule is a blessed writer or an audited read-only CLI', () => {
+  const known = new Set([...BLESSED_WRITERS, ...READ_ONLY_CLIS]);
+  for (const rule of settings.permissions.allow) {
+    const m = rule.match(SCRIPT_RULE);
+    if (m) assert.ok(known.has(m[1]), `${m[1]}.js is pre-allowed but not audited here — a prefix rule allows every flag it takes`);
+  }
+});
+
+test('the read-only subset is pre-allowed', () => {
+  const allow = settings.permissions.allow;
+  for (const cmd of ['git status', 'git status --short', 'git branch --list', 'git fetch origin',
+    'gh pr view 922', 'gh pr checks 922', 'gh pr list', 'gh run view 1 --log-failed', 'gh run list --limit 5',
+    ...READ_ONLY_CLIS.map((s) => `node scripts/gds/${s}.js`)]) {
+    assert.ok(allowCovers(allow, cmd), `should run without a prompt: ${cmd}`);
+  }
+});
+
+test('the instance starter mirrors this list in verb form (claude-materialize.js STARTER_ALLOW)', () => {
+  assert.deepEqual([...STARTER_ALLOW].sort(), settings.permissions.allow.map((rule) => bongosify(rule)).sort());
+});
+
 console.log('');
 console.log(`box_ship_permissions: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/claude_materialize.mjs

@@ -729,6 +729,7 @@ t('every allow-rule names a verb the CLI actually registers', () => {
   // is silently inert — it looks like a permission and grants nothing, so the
   // builder still meets the classifier and nobody can see why.
   for (const rule of m.STARTER_ALLOW) {
+    if (!rule.startsWith('Bash(bongos ')) continue; // the git/gh reads (task 1003992) name no verb
     const inner = rule.replace(/^Bash\(/, '').replace(/:\*\)$/, '');
     const verb = inner.split(' ')[1];
     assert.ok(cliVerbs[verb], `allow-rule "${rule}" names "${verb}", which is not a registered bongos verb`);

package/tests/git_guard.mjs

@@ -31,6 +31,14 @@ function bash(command, env) {
   return runHook(JSON.stringify({ tool_name: 'Bash', tool_input: { command } }), env);
 }
 
+// The same command as a Windows box sends it. Claude Code's shell tool is named
+// `PowerShell` there, carrying the identical `tool_input.command` — and this hook
+// matched `Bash` alone, so every guarded shape was unguarded on Windows (task
+// 1003999).
+function pwsh(command, env) {
+  return runHook(JSON.stringify({ tool_name: 'PowerShell', tool_input: { command } }), env);
+}
+
 test('blocks every git stash form except the read-only list', () => {
   for (const cmd of [
     'git stash',
@@ -96,7 +104,21 @@ test('allows the read-only, the supported, and the ordinary', () => {
   }
 });
 
-test('non-Bash tools and unknown payload shapes fail open', () => {
+test('a Windows session is guarded: the PowerShell tool blocks the same shapes', () => {
+  for (const cmd of ['git stash', 'git push origin main', 'git worktree remove wt-x', 'git branch -D feature']) {
+    const r = pwsh(cmd);
+    assert.equal(r.status, 2, `PowerShell went unguarded for: ${cmd}`);
+    assert.match(r.stderr, /git-guard: blocked/);
+  }
+});
+
+test('the PowerShell tool keeps the same false-positive floor as Bash', () => {
+  for (const cmd of ['git stash list', 'git push origin my-branch', 'npm test']) {
+    assert.equal(pwsh(cmd).status, 0, `false positive on PowerShell: ${cmd}`);
+  }
+});
+
+test('a non-shell tool and unknown payload shapes still fail open', () => {
   assert.equal(
     runHook(JSON.stringify({ tool_name: 'Write', tool_input: { file_path: 'x.js', content: 'git stash' } })).status,
     0,

package/tests/hook_shell_tools.mjs

@@ -0,0 +1,115 @@
+// tests/hook_shell_tools.mjs — the settings matcher and the in-hook tool check are
+// two halves of one gate, and this pins that they agree (task 1003999).
+//
+// THE BUG THIS CLOSES. A hook runs only if its `matcher` in .claude/settings.json
+// names the tool, and acts only if its own `tool_name` check admits it. Widening
+// one without the other changes nothing. Three hooks hard-coded `'Bash'` on both
+// halves, so on a Windows box — where Claude Code's shell tool is named
+// `PowerShell` and carries the identical `tool_input.command` — git-guard did not
+// see a `git push origin main`, secret-gate did not scan a command for
+// credentials, and lifecycle-card printed no claim or ship card.
+//
+// It failed silently in the worst way: the hooks ran, matched nothing and exited
+// 0, which looks exactly like a clean command. So the drift is what gets asserted
+// here, not the behaviour — tests/git_guard.mjs owns the behaviour, with a real
+// PowerShell payload against the live hook.
+//
+// Adding a future shell tool is one edit in .claude/hooks/shell-tools.js; this
+// test then names every settings entry that must follow.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const require = createRequire(import.meta.url);
+const { SHELL_TOOLS, MATCHER, isShellTool } = require(
+  path.join(ROOT, '.claude', 'hooks', 'shell-tools.js'),
+);
+
+const settings = JSON.parse(
+  fs.readFileSync(path.join(ROOT, '.claude', 'settings.json'), 'utf8'),
+);
+
+// Every hook whose job is to guard or read a shell command. The bare basename is
+// how the settings `command` string names it.
+const SHELL_HOOKS = [
+  'git-guard.js',
+  'secret-gate.js',
+  'lifecycle-card.js',
+  'stuck-detector.js',
+];
+
+// Flatten settings.hooks into [{event, matcher, command}] so an entry can be found
+// by the hook file it runs, wherever it sits.
+function entries() {
+  const out = [];
+  for (const [event, groups] of Object.entries(settings.hooks || {})) {
+    for (const group of groups || []) {
+      for (const h of group.hooks || []) {
+        out.push({ event, matcher: group.matcher || '', command: h.command || '' });
+      }
+    }
+  }
+  return out;
+}
+
+test('every shell-reading hook is registered, and its matcher names every shell tool', () => {
+  const all = entries();
+  for (const hook of SHELL_HOOKS) {
+    const found = all.filter((e) => e.command.includes(hook));
+    assert.ok(found.length > 0, `${hook} is not registered in settings.json at all`);
+    for (const e of found) {
+      const named = e.matcher.split('|').map((s) => s.trim());
+      for (const tool of SHELL_TOOLS) {
+        assert.ok(
+          named.includes(tool),
+          `${hook} (${e.event}) matcher "${e.matcher}" omits ${tool} — ` +
+            'that shell tool reaches the hook not at all, silently',
+        );
+      }
+    }
+  }
+});
+
+test('no shell-reading hook still hard-codes a single tool name', () => {
+  for (const hook of SHELL_HOOKS) {
+    const src = fs.readFileSync(path.join(ROOT, '.claude', 'hooks', hook), 'utf8');
+    // The precise shape that caused this: an equality test against one tool name.
+    // A hook may still MENTION 'Bash' (comments, a candidateTexts case for a
+    // non-shell tool), so only the comparison is refused.
+    for (const tool of SHELL_TOOLS) {
+      const re = new RegExp(`(!==|===)\\s*['"]${tool}['"]|['"]${tool}['"]\\s*(!==|===)`);
+      assert.doesNotMatch(
+        src, re,
+        `${hook} compares tool_name against '${tool}' directly — use isShellTool()`,
+      );
+    }
+    assert.match(
+      src, /require\(['"]\.\/shell-tools['"]\)/,
+      `${hook} does not share the shell-tool list`,
+    );
+  }
+});
+
+test('MATCHER is built from the list, so it cannot drift from it', () => {
+  assert.equal(MATCHER, SHELL_TOOLS.join('|'));
+  // And it is what the settings entries actually carry, for the bare-shell hooks
+  // (secret-gate also matches the file-writing tools, so it is a superset).
+  const gitGuard = entries().find((e) => e.command.includes('git-guard.js'));
+  assert.equal(gitGuard.matcher, MATCHER);
+});
+
+test('isShellTool admits every listed tool and nothing else, and never throws', () => {
+  for (const tool of SHELL_TOOLS) assert.equal(isShellTool(tool), true, tool);
+  for (const other of ['Write', 'Edit', 'Read', 'bash', 'powershell', '']) {
+    assert.equal(isShellTool(other), false, other);
+  }
+  // A hook must not throw on an odd payload — that is a fail-open on a guard.
+  for (const junk of [undefined, null, 0, {}, []]) {
+    assert.equal(isShellTool(junk), false);
+  }
+});

package/tests/lifecycle-card.mjs

@@ -18,9 +18,17 @@
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { requireHostModule } from './helpers.mjs';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const hook = requireHostModule(require, '../.claude/hooks/lifecycle-card.js');
+const HOOK = path.join(
+  path.dirname(fileURLToPath(import.meta.url)), '..', '.claude', 'hooks', 'lifecycle-card.js',
+);
 
 let passed = 0;
 let failed = 0;
@@ -30,6 +38,43 @@ function test(name, fn) {
 }
 const count = (hay, needle) => hay.split(needle).length - 1;
 
+// main() reads stdin and is not exported, so the tool-name gate is only reachable by
+// spawning the hook the way Claude Code does. That gate matched `Bash` alone, so a
+// claim or ship run from a Windows session — where the shell tool is named
+// `PowerShell` — produced no card at all (task 1003999).
+function runHook(payload) {
+  const r = spawnSync(process.execPath, [HOOK], {
+    input: JSON.stringify(payload), encoding: 'utf8',
+    env: { ...process.env, OTB_SESSION_CARDS_OFF: '', OTB_SUBAGENT: '' },
+  });
+  return r.stdout || '';
+}
+
+// A ship run's output as the hook sees it: the widgets-ON marker naming a card file.
+function shipPayload(toolName, cardPath) {
+  return {
+    tool_name: toolName,
+    tool_input: { command: 'node scripts/gds/ship.js 1003999 --summary x' },
+    tool_response: `shipped\n[otb-card-html] ${cardPath}\n`,
+  };
+}
+
+test('a lifecycle card is emitted for every shell tool, not Bash alone', () => {
+  const cardPath = path.join(os.tmpdir(), `otb-test-card-${process.pid}.html`);
+  fs.writeFileSync(cardPath, '<div id="card">shipped</div>');
+  try {
+    for (const tool of ['Bash', 'PowerShell']) {
+      const out = runHook(shipPayload(tool, cardPath));
+      assert.ok(out.includes('additionalContext'), `${tool} got no card directive`);
+      assert.ok(out.includes('show_widget'), `${tool} card directive is malformed`);
+    }
+    // A tool that carries no shell command still gets nothing.
+    assert.equal(runHook(shipPayload('Write', cardPath)).trim(), '');
+  } finally {
+    try { fs.unlinkSync(cardPath); } catch (_) { /* best effort */ }
+  }
+});
+
 // ---------- matchesLifecycle ----------
 
 test('matches claim / ship / release script invocations', () => {

package/tests/secret_gate.mjs

@@ -65,6 +65,51 @@ test('blocks a Bash command smuggling a literal token; allows ordinary commands'
   }
 });
 
+// The identical command as a Windows session sends it: Claude Code names the shell
+// tool `PowerShell` there (task 1003999).
+//
+// WHERE THE REAL DEFECT WAS, precisely. For THIS gate the load-bearing half was the
+// settings `matcher`, which listed `Bash` and so never ran the hook on a Windows box
+// at all; tests/hook_shell_tools.mjs owns that half. candidateTexts() was survivable
+// on its own, because an unrecognised tool falls through to `JSON.stringify(ti)` —
+// which still contains the command, so decide() blocked anyway. Verified by probe:
+// narrowing candidateTexts() back to `=== 'Bash'` left the decide() assertions below
+// GREEN. They are kept because they pin the end-state contract, but they are not what
+// catches a narrowing, so the last assertion goes at candidateTexts() directly: a
+// shell tool must yield the command FIELD, not a stringified blob that happens to
+// contain it. That distinction is the difference between scanning a command and
+// scanning it by accident.
+test('the PowerShell tool is scanned exactly as Bash is, command field and all', () => {
+  assert.equal(
+    gate.decide({ tool_name: 'PowerShell', tool_input: { command: `echo "${FAKE.anthropic}" >> notes.txt` } }, ENV_OFF).block,
+    true,
+    'a secret in a PowerShell command went unscanned',
+  );
+  for (const cmd of ['npm test', 'git commit -m "feat: rotate the key handling (ADR 0022)"']) {
+    assert.equal(
+      gate.decide({ tool_name: 'PowerShell', tool_input: { command: cmd } }, ENV_OFF).block,
+      false, `false positive on PowerShell: ${cmd}`,
+    );
+  }
+  // And it inherits Bash's rule that a command never gets the path allowlist.
+  assert.equal(
+    gate.decide(
+      { tool_name: 'PowerShell', tool_input: { file_path: 'tests/bfg.mjs', command: `echo ${FAKE.github}` } },
+      ENV_OFF,
+    ).block,
+    true,
+    'the allowlist leaked to a PowerShell command',
+  );
+
+  // The assertion that actually reds when the shell-tool branch narrows: the command
+  // field is chosen for it, not reached through the unknown-tool stringify fallback.
+  assert.deepEqual(
+    gate.candidateTexts('PowerShell', { command: 'echo hi', file_path: 'x.js' }),
+    ['echo hi'],
+    'a shell tool must yield its command field, not a stringified payload',
+  );
+});
+
 test('clean writes pass; short/placeholder shapes below the length floors pass', () => {
   for (const content of [
     'const label = "use your ghp_ token here";', // prefix alone, no 30-char body