@sabaiway/agent-workflow-kit 14.25.2 → 14.27.0

package/references/modes/upgrade.md

@@ -113,12 +113,12 @@ Requires: ${CLAUDE_SKILL_DIR}/references/shared/report-footer.md · ${CLAUDE_SKI
    - **A skip line that contradicts the observed tree is a FINDING, never pasted as neutral.** Every ensure skip names the fact it proved (the probes that answered absent, the layout it read); if the tree you can see disproves that reason — a "no Node" skip beside deployed Node scripts, a "not deployed" skip beside a stamped `docs/ai` — do not relay the line as an outcome: raise it in the report as a defect of the tool, with the contradicting fact named, and stop short of any step that would build on the skip.
    - **Report step 3's outcome in plain language** — for **each** `pointers` slot (workflow-methodology, orchestration-recipes and autonomy-policy) whether it was *added*, was *already present* (nothing changed), or was *skipped* (the soft-skip from step 3, with its reason — over the line limit / engine too old / the autonomy pointer's anchor absent); the **eight project-configuration ensure** (`configs`) lines exactly as the one ensure run composed them (the ensures and their outcome tokens are enumerated in step 3), each rendered in plain language: what was created, what was left exactly as the user wrote it, and — for a `failed` line — what stopped it; for the navigator, relay the **late** `--only index` line, not the early one; the **`gates-migration`** result — *nothing to migrate*, the shown plan *applied* on your explicit yes, or the plan *left unapplied* (consent not given), with any INERT checker or CUSTOMIZED entries named; the **placed-bridge refresh** (`bridges`) outcome — paste the tool's per-bridge lines verbatim (they are already plain: *refreshed* / *already current* / *skipped — not placed* / `skipped-readonly` with its re-scan verdict / *could not refresh* + recovery); the **agent-rules lens** (`lens`) outcome (*refreshed* / *already current* / *custom edit preserved + note* / *file absent* / *engine too old* / *over the line cap*) and the **Communication-section** outcome (its own set: refreshed / already current / custom preserved + note / section absent — noted / over the cap — refused) and the **story-sessions section** outcome (its own set: refreshed / already current / custom edit preserved + note / section absent — noted / over the file's line cap — refused); the **full-flow offer** (`tier`) lines; the **bridge-settings reconcile** (`bridge-settings`) outcome (paste the tool's line(s) verbatim); and, for a hidden deployment, whether the hidden-mode footprint (`footprint`) was *moved to project-local*, was *already project-local* (nothing changed), or needed a question (ambiguous visibility / a leftover machine-wide block). Plain wording only — never the reconcile/slot/anchor/marker terms (the never-leak-kit-internals Gotcha — `${CLAUDE_SKILL_DIR}/references/shared/deploy-tail.md`).
    - **Never surface the structure number on this exit.** Whatever step 3 did, do **not** recite the `docs/ai` structure version, the internal versioning vocabulary, or the two-axes note here — the number is inert on an equal-head exit; it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md` (shown at the never-downgrade STOP, the explicit status view, or on an explicit ask). Frame the success itself per the final bullet: if step 3 changed anything, say **what changed** in plain human terms; only a pure zero-diff no-op is *settings already current — no update needed*.
-   - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent-gated chat applies: the user picks items in plain language; surface each picked item's posture note, get the explicit confirm, then run EXACTLY the rendered chat one-liners (a HAND-APPLY item is never run by you) — the full lane in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
-   - **Recommendations lanes — both exits.** The agent applies only chat items, on the chat yes. When a console item's apply slot is the route line, only `init` applies it, run by the user in a console from the project's folder. The agent never runs a console item's line, never retries a refused write outside the sandbox and continues past every console item; every failure of a chat step is a STOP.
+   - **Render the mandatory Recommendations section — on this exit too, BEFORE the footer.** Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language: every fact, count and item from the tool, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; show the raw tool block on request. The section is present-even-when-empty (with everything optimal the body is exactly `no recommendations — flow optimal.`) and VERDICT-FIRST — the composed verdict line renders from the frozen templates `{K} item(s) need attention` / `nothing is broken` / `{N} optional recommendation(s), apply any you want` / `optimality NOT attested — {M} probe check(s) skipped`. Then OFFER the consent route: the user picks items in plain language; surface each picked item's posture note and get the explicit confirm; run its lane's rendered lines — chat: the one-liner; harness: the check line, then on the yes to its result the apply line; user: the user's own step — per the full consent route in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Pinned order on this exit: Recommendations block → optional applies → report footer → the commit ask (the advisor/apply lane never lands after the commit ask).
+   - **Recommendations lanes — both exits.** The three lanes (`chat`, `harness`, `user`) and the consent route live in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`; `init` stays a route the user may take.
    - **Live host/session facts are tool-composed only.** Any claim this report makes about the current host or session state — prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts — must trace to **live tool output** from **this session** (the lines you just composed, or a probe you ran this run); a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection. Full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`.
    - **Print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason). The welcome mat closes on **one** caveat-aware next step (a behind member first, else `setup` / `recipes` / `velocity` / `agents` / `hook`).
    - **Then ask before committing — never auto-commit.** If step 3 added the slot (or anything else changed), report it and ask. If step 3 was a pure zero-diff no-op and nothing else changed, give the plain **settings already current — no update needed** message (the *Success state* contract in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`) and still print the read-only version block (installed package versions) + backend line — but **no `docs/ai` structure version and no two-axes note** (nothing changed, so the number is inert here).
 5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 6. **Collect the migration answers FIRST, then apply.** Run `node ${CLAUDE_SKILL_DIR}/tools/migration-notes.mjs --cwd <project>` and relay its stdout lines verbatim, in order; a non-zero exit relays its one named line and STOPs, except `stamp-absent`, which routes back to step 1. Then run the preview `node ${CLAUDE_SKILL_DIR}/tools/migration-blocks.mjs --cwd <project>`. If its lines say both blocks are missing (pre-1.1.0), ask the two questions as ONE structured multi-question prompt; record each answer individually, write nothing until ALL are answered, and carry the answers into the migrations below: a migration whose answer was already collected never re-asks; a single missing block keeps its single ask (step 7). Then apply exactly the notes the tool listed, in its order ("only those newer than the project's stamp" is why, never a second selection). Migrations are **idempotent** — safe to re-run.
 7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. For a block the preview names as needing its answer, **ask the user their conversational language** (`--language`) or **whether the agent may attribute work to itself / AI** (`--attribution`, defaulting to `off`), never re-asking a step-6 answer; then re-run the preview with `--apply` and the answers, relaying its lines. Exit 1 `answer-missing`: ask exactly what its lines name and re-run `--apply` once; a second one STOPs. Any other exit 1 is a named refusal: relay it with its recovery (`cap`: trim `AGENTS.md`, re-run) and STOP before the finalizer and the stamp. **Then, before the stamp, re-run the LATE navigator finalizer:** the migrations of steps 6–7 may have changed `docs/ai` files, so run the one op again — `node ${CLAUDE_SKILL_DIR}/tools/ensure-configs.mjs --reconcile --only index --cwd <project>` — and relay THAT line in the step-8 report (idempotent: an untouched tree reports `already-current`; a failure STOPs this upgrade like any other ensure).
-8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`4.0.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 run-list outcomes, each as step 4 words it: the `pointers` slots, the `footprint` visibility verdict (and what a consented re-run migrated), the **eight project-configuration ensure** (`configs`) lines (enumerated in step 3) — the navigator one being the late `--only index` run at the end of step 7, the **`gates-migration`** result, the **placed-bridge refresh** (`bridges`) lines (pasted verbatim), the **agent-rules lens** (`lens`) + **Communication-section** + **story-sessions section** outcomes (same outcome sets as step 4), the **full-flow offer** (`tier`) outcome, and the **bridge-settings reconcile** (`bridge-settings`) outcome (line(s) pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **render the mandatory Recommendations section**: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language (every fact, count and item, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request; present-even-when-empty: `no recommendations — flow optimal.`), then OFFER the consent-gated chat applies (per picked item: posture note → explicit confirm → run EXACTLY the rendered chat one-liner; a HAND-APPLY item is never run by you — `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Every current host/session claim in this report is tool-composed only** — prompts fired, sandbox scope, whether a bypass was needed, network reachability and approval counts must trace to **live tool output** from **this session**, a memory/handover snapshot is **context, never report facts**, and an unbacked claim is **omitted or explicitly marked unverified** (full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing** — the pinned order on this exit is: Recommendations block → optional applies → report footer → the commit ask.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`4.0.0`, not the package version — mechanics unchanged: the atomic write to the stamp file). In the report, **describe what the upgrade changed in plain human terms** — which parts of their `docs/ai` are now different (the migrations that ran), plus the step-3 run-list outcomes, each as step 4 words it: the `pointers` slots, the `footprint` visibility verdict (and what a consented re-run migrated), the **eight project-configuration ensure** (`configs`) lines (enumerated in step 3) — the navigator one being the late `--only index` run at the end of step 7, the **`gates-migration`** result, the **placed-bridge refresh** (`bridges`) lines (pasted verbatim), the **agent-rules lens** (`lens`) + **Communication-section** + **story-sessions section** outcomes (same outcome sets as step 4), the **full-flow offer** (`tier`) outcome, and the **bridge-settings reconcile** (`bridge-settings`) outcome (line(s) pasted verbatim) — rather than reciting a version number; **omit the raw structure number**, and do **not** print the two-axes note here (it belongs to *Version disclosure* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`, on demand only). Then **render the mandatory Recommendations section**: run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root>` and PRESENT its output — from the `## Recommendations (agent-workflow)` header — in the user's conversational language (every fact, count and item, nothing added or dropped; commands, paths, hosts and rule strings byte-exact; raw tool block on request; present-even-when-empty: `no recommendations — flow optimal.`), then OFFER the consent route (per picked item: posture note → explicit confirm → chat: the one-liner; harness: the check line, then on the yes to its result the apply line; user: the user's own step — `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Every current host/session claim in this report is tool-composed only** — prompts fired, sandbox scope, whether a bypass was needed, network reachability and approval counts must trace to **live tool output** from **this session**, a memory/handover snapshot is **context, never report facts**, and an unbacked claim is **omitted or explicitly marked unverified** (full clause: *Live host/session facts* in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`). Then **print the report footer** in the canonical order (version block → one-line backend-status line → welcome mat — the shared contracts in `${CLAUDE_SKILL_DIR}/references/shared/report-footer.md`; rendered from the helpers, same host-can't-run skip-with-reason; the welcome mat closes on one caveat-aware next step). Then **ask before committing** — the pinned order on this exit is: Recommendations block → optional applies → report footer → the commit ask.

package/references/modes/velocity.md

@@ -50,11 +50,11 @@ Honesty notes: tier entries get **NO PreToolUse-hook residual coverage — with
 
 **The boundary of that qualifier, stated so it is not guessed.** It covers claims about `sandbox.*` keys — the block whose honouring was observed to vary by host. It deliberately does NOT cover `permissions.*` semantics (an allow rule auto-approving a command, `local > project` precedence for a non-sandbox key): that is the harness's own documented permission model, the layer this whole mode rests on, and hedging it would say nothing true. **Stated residual:** which sentences count as settings-derived runtime claims is decided by review, not by a checker — deciding whether a sentence asserts a runtime effect is a question about prose meaning, and this family deliberately has no mechanism that judges that (the same limit that retired the byte-scanning deny rung). A new claim-bearing line therefore has to carry the qualifier by authorship; the acceptance criterion is that every line stating what a `sandbox.*` key DOES carries it, and the tests pin the surfaces that exist today. What does NOT change is the CLASSIFICATION: which red-line a key would weaken, and that a proven bridge-tier exclusion is a note rather than a weakening, are properties of the declaration and stay flat statements.
 
-**The `--bridge-tier` (own opt-in, AD-044).** Seeds what a promptless council review run needs — three surfaces: `permissions.allow` prefix rules, the wrapper names in `sandbox.excludedCommands` (where the host honors the settings sandbox keys the harness runs an excluded command OUTSIDE the sandbox — the wrappers need network — so a plain allowlisted invocation triggers no sandbox-bypass approval; where it does not, the wrapper starts sandboxed and simply prompts or fails loudly — fail-safe, never a silent widening), and the placed bridges' declared hosts in `sandbox.network.allowedDomains` (below). All three land in the **project** `.claude/settings.json` — the file this writer owns; an exclusion placed only in `settings.local.json` was live-observed NOT to route the command outside the sandbox (2026-07-11: the wrapper then starts sandboxed and dies on a read-only HOME + a network prompt), so hand-wiring the local file is not a working substitute for this tier. **Honesty note:** a session whose sandbox is imposed by the harness runtime itself (e.g. an IDE-managed session sandbox) may ignore settings-level exclusions entirely — there the wrappers need the session-level sandbox config (or a per-run consented bypass); the tier's seeded posture is correct for a settings-native sandbox that honours the exclusion and simply prompts again elsewhere (fail-safe, never a silent widening). A harness that reads the settings sandbox keys may still drop this exclusion (observed 2026-10-06: Claude Code 2.1.291 ran an agent's plain `codex-review` inside its sandbox with the project entry present); its lane is the settings-native one in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. Each bridge's observed egress hosts are declared in its `capability.json` `networkHosts` — the single documentation source (observed-minimal — a blocked host names itself at run time; read the manifests, this doc deliberately retypes no host list). The tier ALSO seeds the placed bridges' declared hosts — the `networkHosts` of every bundled manifest whose review wrapper is placed — into the project's `sandbox.network.allowedDomains` (AD-172, which reverses the bridge council of 2026-07-11 for those hosts only): where the host honors the settings sandbox keys, a wrapper a harness keeps sandboxed despite the exclusion is no longer refused them, and every sandboxed command of the project can then reach those hosts, not only the wrappers — that widening is part of this consent, and the `--autonomy` preview reports it as a network weakening. `sandbox.filesystem.allowWrite` stays unseeded: a write allowance on CLI state dirs (`~/.codex`, `~/.gemini/…`) would make credential dirs writable to every sandboxed command, so the writable state dirs stay hand-apply. Per-bridge picture under a harness-managed sandbox (live-observed 2026-07-11/12): an IDE-managed session sandbox ignores hand-applied `sandbox.network.allowedDomains` / `sandbox.filesystem.allowWrite` in BOTH settings scopes — its own per-host network consents govern egress; the durable zero-prompt lanes there are the session/host sandbox config (hosts from `networkHosts` + the CLI state-dir writes) or the per-run consented bypass. codex additionally needs a writable HOME (EROFS `~/.codex`); note the apex-vs-wildcard nuance — an apex domain is NOT covered by its `*.`-wildcard form, so the manifests carry both forms where observed (the blocked host names itself at run time). The upgrade Recommendations advisor surfaces exactly this recipe (hosts ∪ resolved `writableDirs`) as the `sandbox-lane` discoverability item — a consent-gated **ack writer** converging on a neutral fingerprint acknowledgement recorded into the family-owned `docs/ai/acks.json` (the writable state dirs stay hand-apply; the hosts are the tier's), with the posture notes at the consent moment (`${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). Membership is the FROZEN review-wrapper constant, **never** the execution/probe wrappers (`codex-exec`, `agy-run` keep their human prompt — delegated execution is not covered by this consent; codex-exec's nested-sandbox recovery is the canon's observed-failure lane, not a preemptive tier seed), and only the **`code` review mode** — a `plan`/`diff` invocation takes a file argument that can point OUTSIDE the repo, so those modes keep their prompt; each wrapper entry derives ONLY when its bridge is **placed on PATH** (an absent bridge is a stated skip). The seeded byte-forms (this list IS the documented-invocation source for the bridge tier):
+**The `--bridge-tier` (own opt-in, AD-044).** Seeds the USED bridges from every recipe's review and execute slots in `docs/ai/orchestration.json`, resolved over host readiness to the effective recipe: a degraded recipe uses its resolved providers; an absent config takes the computed default. A bridge no slot uses gets nothing. Per used review role it seeds `Bash(<wrapper> code:*)` into `permissions.allow` and, with agy-review used, the quoted grounding pre-step rule. Per used role it seeds `<wrapper> *` into `sandbox.excludedCommands`, the manifest's `networkHosts` into `sandbox.network.allowedDomains`, and its resolved `writableDirs` into `sandbox.filesystem.allowWrite`, home-relative under the home and absolute outside it, with env overrides honoured. All entries land in the **project** `.claude/settings.json`, preserving existing entries and sibling keys. **Where the host honors the settings sandbox keys**, an exclusion means the wrapper runs outside the sandbox; a host means every sandboxed command of the project can reach it; a dir means every sandboxed command can write it — each widening is part of this consent. A session-imposed sandbox may ignore those keys; its lane is in `${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`. An exclusion placed only in `settings.local.json` was live-observed NOT to route the command outside the sandbox (2026-07-11: the wrapper then starts sandboxed and dies on a read-only HOME), so hand-wiring the local file is no substitute for this tier. Under a harness-managed session sandbox (live-observed 2026-07-11/12) an IDE-managed sandbox ignores `sandbox.network.allowedDomains` and `sandbox.filesystem.allowWrite` in BOTH settings scopes — its own per-host consents govern egress, and the durable lanes there are the session sandbox config (the hosts plus the CLI state-dir writes) or the per-run consented bypass. Each bridge's observed egress hosts are declared in its `capability.json` `networkHosts` — the single documentation source (this doc retypes no host list); an apex domain is NOT covered by its `*.`-wildcard form, so the manifests carry both forms where observed. The upgrade Recommendations advisor surfaces the same recipe (hosts ∪ resolved `writableDirs`) as the `sandbox-lane` discoverability item — a consent-gated **ack writer** converging on a neutral fingerprint acknowledgement recorded into the family-owned `docs/ai/acks.json`, with the posture notes at the consent moment (`${CLAUDE_SKILL_DIR}/references/modes/recommendations.md`). **Bare-entry reading (measured 2026-10-06):** an exclusion uses Bash rule syntax; a bare name matches only the argument-free command, so the tier writes the form with ` *`; an earlier bare entry stays and does not satisfy that surface. Where an execute slot delegates, codex-exec gets its exclusion, hosts and state dirs, but no allow rule, so a delegated run keeps its prompt. Only the code review mode is auto-allowed; plan/diff keep their prompt. The grounding rule uses the double-quoted absolute kit path the procedures advisor renders; an unseedable path is a stated skip. Its writer guard accepts only system-temp scratch or a fresh gitignored in-repo destination, refusing tracked, non-ignored, existing in-repo, outside-repo non-temp and symlink/non-regular destinations. The seeded byte-forms (this list IS the documented-invocation source for the bridge tier):
 
-- `Bash(codex-review code:*)` — the code-mode prefix, args wildcard; plus `codex-review` in `sandbox.excludedCommands`
-- `Bash(agy-review code:*)` — the code-mode prefix, args wildcard; plus `agy-review` in `sandbox.excludedCommands`
-- `Bash(node "${CLAUDE_SKILL_DIR}/tools/grounding.mjs":*)` — the grounding pre-step, **double-quoted absolute path**: exactly the byte-form the `procedures` advisor renders, so the pasted pre-step matches the rule (seeded↔rendered byte-parity). It derives ONLY when `agy-review` is placed (the pre-step exists for agy's grounded reviews; codex grounds natively) — a codex-only install never auto-allows this writer. The quoted form is accepted for THIS one tool only — never a general quote allowance; an unseedable kit path (spaces/metacharacters) is a stated skip. Its writer surface is closed by the tool's own guard: `--out` accepts only system-temp scratch (rewritable) or a FRESH gitignored in-repo path (create-only, exclusive write) — tracked, in-repo-not-ignored, EXISTING in-repo (even gitignored), outside-repo non-temp, and symlink/non-regular destinations are all refused.
+- `Bash(codex-review code:*)` — the review code-mode allow rule; `codex-review *` — its sandbox.excludedCommands entry.
+- `Bash(agy-review code:*)` — the review code-mode allow rule; `agy-review *` — its sandbox.excludedCommands entry; `Bash(node "${CLAUDE_SKILL_DIR}/tools/grounding.mjs":*)` — its quoted grounding pre-step rule.
+- `codex-exec *` — the sandbox.excludedCommands entry for a used execute role; no allow rule.
 
 **Consented posture (printed on every `--bridge-tier` run, stated not pretended away):** an auto-allowed review wrapper runs **UNATTENDED** — it reads any repo file it is pointed at and sends the assembled payload to its **subscription backend**; prefix rules cannot inspect arguments, so a code-mode argument that names a readable file (agy's `--facts`/`--decided`) rides the same consent. That is the tier's purpose (unattended council review runs) and its residual. Tier entries get no PreToolUse-hook coverage — the same documented residual class as the autonomy red-line rules. The grounding entry's writer surface is bounded by `grounding.mjs`'s own scratch-destination guard (a tracked or in-repo-not-ignored `--out` is refused by the tool itself).
 

package/tools/apply-danger-check.mjs

@@ -0,0 +1,369 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  CLAUDE_DIR, RENDER_OWNED_REDLINE_RULES,
+  SAFE_DEFAULT_MODES, SETTINGS_FILE, SETTINGS_LOCAL_FILE, UNIVERSAL_READONLY_ALLOWLIST,
+  deriveKitToolsAllowlist, detectAtRoot, mergeAutonomySettings,
+  writeAutonomyProfile, writeVelocityProfile,
+} from './velocity-profile.mjs';
+import { KIT_GROUNDING_TOOL, bundledSandboxRecipe, usedBridges } from './bridge-sandbox-recipe.mjs';
+import { mergeAllowWrite, stateDirsOf } from './bridge-state-dirs.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { HOOK_FILE_REL, HOOKS_DIR, buildHookSettingsEntry, mergeHookEntry, writeGateHook } from './gate-hook.mjs';
+import { writeMcp } from './mcp.mjs';
+import { ENABLED_KEY, MCP_JSON_REL, SERVERS_KEY, SERVER_NAME, allowRulesFor, buildServerEntry } from './mcp-registration.mjs';
+import { AGENTS_DIR, writeCheapAgents } from './cheap-agents.mjs';
+import { planFor } from './jev-skill.mjs';
+import { SKILL_FILES, claudeDirOf, skillTargets } from './jev-facts.mjs';
+import { findOnPath } from './detect-backends.mjs';
+import { consoleArgv } from './write-lanes.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { dirCovers as covers } from './declared-paths.mjs';
+
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+const SKILL_VARIANTS = ['jev-skill', 'jev-skill.earlier'];
+const VELOCITY_VARIANTS = ['velocity-core', 'kit-tools-tier', 'bridge-tier'];
+const HOOK_VARIANTS = ['gate-hook', 'read-lane.missing'];
+const MCP_VARIANTS = ['mcp-channel', 'mcp-channel.differing'];
+const AGENT_VARIANTS = ['agents', 'executor-vehicle'];
+const VARIANTS = [...VELOCITY_VARIANTS, 'autonomy-render', ...HOOK_VARIANTS, ...MCP_VARIANTS, ...AGENT_VARIANTS, ...SKILL_VARIANTS];
+const CREDENTIALS = 'sandbox.credentials.envVars';
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const stable = (value) => object(value)
+  ? `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stable(value[key])}`).join(',')}}`
+  : Array.isArray(value) ? `[${value.map(stable).join(',')}]` : JSON.stringify(value);
+const equal = (left, right) => stable(left) === stable(right);
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const textValue = (value) => typeof value === 'string' ? value : JSON.stringify(value);
+
+export const CHANGE_CLASSES = Object.freeze([
+  'hosts reachable', 'paths writable', 'commands outside the sandbox',
+  'prompts removed', 'commands the harness runs', 'nothing widened',
+]);
+export const KEY_TABLE = Object.freeze({
+  'sandbox.network.allowedDomains': 0,
+  'sandbox.filesystem.allowWrite': 1,
+  'sandbox.excludedCommands': 2,
+  'permissions.allow': 3,
+  'permissions.defaultMode': 3,
+  'sandbox.autoAllowBashIfSandboxed': 3,
+  'permissions.ask': 3,
+  'permissions.deny': 3,
+  'sandbox.enabled': 3,
+  'hooks.PreToolUse': 4,
+  [ENABLED_KEY]: 4,
+  [SERVERS_KEY]: 4,
+  [CREDENTIALS]: 5,
+});
+const SCALARS = ['permissions.defaultMode', 'sandbox.enabled', 'sandbox.autoAllowBashIfSandboxed'];
+const valid = (key, value, element = false) => {
+  if (key.startsWith(`${SERVERS_KEY}.`) || key === SERVERS_KEY) return object(value);
+  if (key === 'permissions.defaultMode') return typeof value === 'string';
+  if (SCALARS.includes(key)) return typeof value === 'boolean';
+  if (!element) return Array.isArray(value) && value.every((entry) => valid(key, entry, true));
+  if (key === CREDENTIALS) return object(value) && typeof value.name === 'string' && typeof value.mode === 'string';
+  return key === 'hooks.PreToolUse' ? object(value) : typeof value === 'string';
+};
+const keyOf = (key) => key.startsWith(`${SERVERS_KEY}.`) ? SERVERS_KEY : key;
+
+export const diffFiles = (before, after) => {
+  const entries = [];
+  const scalar = (key, left, right) => {
+    if (equal(left, right)) return;
+    if (left === undefined) entries.push({ key, change: 'added', value: right });
+    else if (right === undefined) entries.push({ key, change: 'removed', value: left });
+    else entries.push({ key, change: 'altered', value: right, previous: left });
+  };
+  const walk = (left, right, key) => {
+    if (equal(left, right)) return;
+    const known = Object.hasOwn(KEY_TABLE, key);
+    if (known && [left, right].some((value) => value !== undefined && !valid(key, value))) {
+      scalar(key, left, right);
+    } else if (key === SERVERS_KEY) {
+      for (const name of new Set([...Object.keys(left ?? {}), ...Object.keys(right ?? {})])) {
+        scalar(`${key}.${name}`, left?.[name], right?.[name]);
+      }
+    } else if (known && !SCALARS.includes(key)) {
+      const old = left ?? [];
+      const next = right ?? [];
+      const unpaired = old.filter((value) => !next.some((entry) => equal(value, entry)));
+      const changes = next.filter((value) => !old.some((entry) => equal(value, entry))).map((value) => {
+        const at = key === CREDENTIALS ? unpaired.findIndex((entry) => entry.name === value.name) : -1;
+        return at < 0 ? { key, change: 'added', value } : { key, change: 'altered', value, previous: unpaired.splice(at, 1)[0] };
+      });
+      for (const value of unpaired) entries.push({ key, change: 'removed', value });
+      entries.push(...changes);
+    } else if (!known && (key === '' || Object.keys(KEY_TABLE).some((path) => path.startsWith(`${key}.`)))
+      && [left, right].every((value) => value === undefined || object(value))) {
+      for (const name of new Set([...Object.keys(left ?? {}), ...Object.keys(right ?? {})])) {
+        walk(left?.[name], right?.[name], key ? `${key}.${name}` : name);
+      }
+    } else scalar(key, left, right);
+  };
+  walk(before ?? {}, after ?? {}, '');
+  const order = Object.keys(KEY_TABLE);
+  const rank = (key) => order.includes(keyOf(key)) ? order.indexOf(keyOf(key)) : order.length;
+  return entries.sort((a, b) => rank(a.key) - rank(b.key));
+};
+
+const classOf = ({ key, change, value }) => {
+  const base = keyOf(key);
+  if (!Object.hasOwn(KEY_TABLE, base)) return null;
+  let index = KEY_TABLE[base];
+  if (change === 'removed') index = ['permissions.ask', 'permissions.deny', CREDENTIALS].includes(key) ? 3 : 5;
+  else if (['permissions.ask', 'permissions.deny'].includes(key)) index = 5;
+  else if (key === 'permissions.defaultMode') index = value === 'acceptEdits' ? 3 : 5;
+  else if (key === 'sandbox.enabled') index = value === false ? 3 : 5;
+  else if (key === 'sandbox.autoAllowBashIfSandboxed') index = value === true ? 3 : 5;
+  return CHANGE_CLASSES[index];
+};
+export const judgeChange = ({ variant, files, scope }) => {
+  const entries = [];
+  const refused = [];
+  for (const { path, before, after } of files) {
+    for (const diff of diffFiles(before, after)) {
+      const entry = { ...diff, path, class: classOf(diff) };
+      entries.push(entry);
+      const { key, change } = diff;
+      const atKey = (data) => key.split('.').reduce((value, name) => value?.[name], data);
+      const wrongType = [atKey(before), atKey(after)].some((value) => value !== undefined && !valid(key, value));
+      const reason = entry.class === null ? 'unknown key' : wrongType ? 'wrong type'
+        : key === CREDENTIALS && change !== 'added' ? 'credentials entry removed or altered'
+          : !scope.admits(entry) ? `beyond the declared scope of ${variant}` : null;
+      if (reason) refused.push({ path, key, reason });
+    }
+  }
+  return { entries, refused };
+};
+const writerFacts = (facts, deps) => ({
+  ...deps, ...facts,
+  detect: deps.detect ?? facts.detect,
+  findWrapper: (name) => findOnPath(name, { getenv: facts.env }).state === 'present',
+  findOnPath: (name) => findOnPath(name, { getenv: facts.env }),
+});
+
+export const scopeOf = (variant, facts, deps = {}) => {
+  const allowed = {};
+  const set = (key, values) => {
+    allowed[key] = (value) => values.some((entry) => equal(entry, value));
+  };
+  if (VELOCITY_VARIANTS.includes(variant)) {
+    const allow = [...UNIVERSAL_READONLY_ALLOWLIST];
+    if (variant === 'kit-tools-tier') allow.push(...deriveKitToolsAllowlist({ projectDir: facts.root }));
+    if (variant === 'bridge-tier') {
+      const detect = deps.detect ?? facts.detect ?? (() => detectAtRoot(facts.root, { env: facts.env, home: facts.home }));
+      const used = usedBridges(loadConfig(facts.root).config, detect());
+      const recipe = bundledSandboxRecipe(used, { groundingAbsPath: join(facts.toolsDir, '..', KIT_GROUNDING_TOOL) });
+      allow.push(...recipe.allow);
+      set('sandbox.excludedCommands', recipe.excludedCommands);
+      set('sandbox.network.allowedDomains', recipe.hosts);
+      set('sandbox.filesystem.allowWrite', stateDirsOf(recipe.dirEntries, facts));
+    }
+    set('permissions.allow', allow);
+  } else if (variant === 'autonomy-render') {
+    set('permissions.defaultMode', SAFE_DEFAULT_MODES);
+    set('sandbox.enabled', [true]);
+    set('sandbox.autoAllowBashIfSandboxed', [true, false]);
+    set('permissions.ask', RENDER_OWNED_REDLINE_RULES);
+    set('permissions.deny', RENDER_OWNED_REDLINE_RULES);
+    allowed[CREDENTIALS] = (value) => value.mode === 'deny';
+  } else if (HOOK_VARIANTS.includes(variant)) set('hooks.PreToolUse', [buildHookSettingsEntry()]);
+  else if (MCP_VARIANTS.includes(variant)) {
+    set(`${SERVERS_KEY}.${SERVER_NAME}`, [buildServerEntry(join(facts.toolsDir, 'mcp-server.mjs'))]);
+    set(ENABLED_KEY, [SERVER_NAME]);
+    set('permissions.allow', allowRulesFor());
+  }
+  const targets = SKILL_VARIANTS.includes(variant) ? skillTargets({ home: facts.home,
+    claudeDir: facts.claudeDir ?? claudeDirOf(facts.env, facts.home, facts.platform).dir }) : [];
+  const filePaths = HOOK_VARIANTS.includes(variant) ? [join(facts.root, HOOK_FILE_REL)] : [];
+  const directories = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render'
+    || HOOK_VARIANTS.includes(variant) || MCP_VARIANTS.includes(variant) || AGENT_VARIANTS.includes(variant)
+    ? [join(facts.root, CLAUDE_DIR)] : [];
+  if (HOOK_VARIANTS.includes(variant)) directories.push(join(facts.root, HOOKS_DIR));
+  if (AGENT_VARIANTS.includes(variant)) directories.push(join(facts.root, AGENTS_DIR));
+  for (const target of targets) {
+    for (let at = target.root; at !== target.base && covers(target.base, at); at = dirname(at)) directories.push(at);
+    filePaths.push(target.path);
+  }
+  return {
+    admits: ({ path, key, change, value }) => {
+      const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL : path === SETTINGS_FILE;
+      const gains = variant === 'bridge-tier' || key === 'hooks.PreToolUse' || key === ENABLED_KEY || key === CREDENTIALS;
+      return correctFile && (!gains || change === 'added') && Boolean(allowed[key]?.(value));
+    },
+    admitsPath: (path, directory = false) => directory ? directories.includes(path)
+      : filePaths.includes(path) || (AGENT_VARIANTS.includes(variant) && covers(join(facts.root, AGENTS_DIR), path)),
+  };
+};
+
+const jsonAt = (path) => existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) : null;
+const halted = (lines) => Object.assign(new Error(lines.join('\n')), { code: 'CHECK_HALTED', lines });
+const maskedFiles = (variant, facts) => {
+  const paths = VELOCITY_VARIANTS.includes(variant) || variant === 'autonomy-render' || HOOK_VARIANTS.includes(variant)
+    ? [SETTINGS_FILE, SETTINGS_LOCAL_FILE] : MCP_VARIANTS.includes(variant) ? [MCP_JSON_REL, SETTINGS_FILE] : [];
+  return paths.flatMap((path) => lstatSync(join(facts.root, path), { throwIfNoEntry: false })?.isCharacterDevice()
+    ? [`masked: ${path}`] : []);
+};
+export const plannedChange = (variant, facts, deps = {}) => {
+  const files = [];
+  const writes = [];
+  const temporaries = [];
+  const writerDeps = writerFacts(facts, deps);
+  const addFile = (path, before, after) => {
+    files.push({ path, before: before ?? null, after });
+  };
+  try {
+    const masks = maskedFiles(variant, facts);
+    if (masks.length) throw halted(masks);
+    if (VELOCITY_VARIANTS.includes(variant)) {
+      const plan = writeVelocityProfile({ cwd: facts.root, dryRun: true,
+        kitTools: variant === 'kit-tools-tier', bridgeTier: variant === 'bridge-tier' }, writerDeps);
+      const before = plan.projectSettings.data ?? {};
+      let after = structuredClone(before);
+      after.permissions = { ...before.permissions,
+        allow: [...(before.permissions?.allow ?? []), ...plan.toAdd, ...plan.tierToAdd, ...plan.bridgeToAdd] };
+      if (plan.excludedToAdd.length || plan.hostsToAdd.length) {
+        after.sandbox = { ...before.sandbox };
+        if (plan.excludedToAdd.length) after.sandbox.excludedCommands = [...(before.sandbox?.excludedCommands ?? []), ...plan.excludedToAdd];
+        if (plan.hostsToAdd.length) after.sandbox.network = { ...before.sandbox?.network,
+          allowedDomains: [...(before.sandbox?.network?.allowedDomains ?? []), ...plan.hostsToAdd] };
+      }
+      after = mergeAllowWrite(after, plan.dirsToAdd);
+      addFile(SETTINGS_FILE, plan.projectSettings.data, after);
+    } else if (variant === 'autonomy-render') {
+      const render = writeAutonomyProfile({ cwd: facts.root, apply: false }, writerDeps);
+      const before = jsonAt(join(facts.root, SETTINGS_FILE));
+      addFile(SETTINGS_FILE, before, mergeAutonomySettings(before, render));
+    } else if (HOOK_VARIANTS.includes(variant)) {
+      const plan = writeGateHook({ cwd: facts.root, dryRun: true }, writerDeps);
+      if (plan.wirePlanned) addFile(SETTINGS_FILE, plan.projectSettings.data, mergeHookEntry(plan.projectSettings.data));
+      if (plan.placePlanned) writes.push({ path: join(facts.root, HOOK_FILE_REL), bytes: plan.bundleContent });
+    } else if (MCP_VARIANTS.includes(variant)) {
+      const result = writeMcp({ cwd: facts.root, dryRun: true, replace: variant === 'mcp-channel.differing' }, writerDeps);
+      const { plan, registration } = result;
+      if (plan.writeMcpJson) addFile(MCP_JSON_REL, registration.mcpJson.data, JSON.parse(plan.mcpBody));
+      if (plan.writeSettings) addFile(SETTINGS_FILE, registration.settings.data, JSON.parse(plan.settingsBody));
+    } else if (AGENT_VARIANTS.includes(variant)) {
+      const plan = writeCheapAgents({ cwd: facts.root, dryRun: true }, writerDeps);
+      for (const item of plan.plan.filter(({ action }) => ['place', 're-derive'].includes(action))) {
+        writes.push({ path: item.abs, bytes: item.content });
+      }
+    } else if (SKILL_VARIANTS.includes(variant)) {
+      const plan = planFor({ ...writerDeps, lstat: lstatSync, readdir: readdirSync, readFile: readFileSync });
+      for (const target of plan.targets.filter(({ action }) => ['install', 'replace'].includes(action))) {
+        const stem = basename(target.path);
+        const bytes = Object.keys(SKILL_FILES).sort().map((name) => [name,
+          readFileSync(join(facts.toolsDir, '..', 'references', 'vendor', stem, SKILL_FILES[name]))]);
+        writes.push({ path: target.path, bytes: Buffer.concat(bytes.flatMap(([name, body]) => [Buffer.from(`${name}\0`), body])), directory: true });
+        temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-tmp-*`);
+        if (target.action === 'replace') temporaries.push(`temporary: ${dirname(target.root)}/.${stem}.kit-old-*`);
+      }
+    } else throw new Error(`unsupported variant: ${variant}`);
+  } catch (error) {
+    throw error.code === 'CHECK_HALTED' ? error : halted([error.message]);
+  }
+  const directories = new Set();
+  const changedFiles = files.filter(({ before, after }) => diffFiles(before, after).length);
+  for (const path of [...changedFiles.map(({ path }) => join(facts.root, path)), ...writes.map(({ path }) => path)]) {
+    for (let parent = dirname(path); !existsSync(parent); parent = dirname(parent)) directories.add(parent);
+  }
+  return { files, writes, temporaries, directories: [...directories] };
+};
+
+export const checkApply = (variant, facts, deps = {}) => {
+  const plan = plannedChange(variant, facts, deps);
+  const scope = scopeOf(variant, facts, deps);
+  const { entries, refused } = judgeChange({ variant, files: plan.files, scope });
+  const lines = [];
+  const display = (path) => facts.root && covers(facts.root, path) ? relative(facts.root, path) : path;
+  for (const file of plan.files) {
+    const changes = entries.filter(({ path }) => path === file.path);
+    if (!changes.length) continue;
+    lines.push(`${file.path}:`);
+    for (const entry of changes) {
+      const old = entry.change === 'altered' ? `${textValue(entry.previous)} → ` : '';
+      lines.push(`  ${entry.key}: ${entry.change} ${old}${textValue(entry.value)} — ${entry.class ?? 'unknown'}`);
+    }
+  }
+  const pathLine = (path, directory, line) => {
+    lines.push(line);
+    if (!scope.admitsPath(path, directory)) refused.push({ path: display(path), key: display(path),
+      reason: `beyond the declared scope of ${variant}` });
+  };
+  for (const write of plan.writes) pathLine(write.path, false, `writes: ${display(write.path)} sha256:${sha(write.bytes)}`);
+  for (const path of plan.directories) pathLine(path, true, `writes: ${display(path)}/ created`);
+  lines.push(...plan.temporaries);
+  if (refused.length) {
+    for (const entry of refused) lines.push(`refused: ${entry.path} ${entry.key} — ${entry.reason}`);
+    lines.push('nothing written');
+  } else lines.push(lines.length ? `scope: within the declared scope of ${variant}` : `nothing to change: ${variant} is already applied`);
+  const digest = sha(lines.join('\n'));
+  return { lines: [...lines, `digest: ${digest}`], digest, refused };
+};
+
+const USAGE = 'usage: apply-danger-check --variant <v> --cwd <root> [--claude-dir <abs>] [--apply --expect <digest>]';
+const parse = (argv, platform) => {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--apply') args.apply = true;
+    else if (['--variant', '--cwd', '--claude-dir', '--expect'].includes(flag)) {
+      const value = argv[index + 1];
+      if (!value || value.startsWith('-')) throw new Error(`${flag} takes a value`);
+      args[flag.slice(2)] = value;
+      index += 1;
+    } else throw new Error(`unknown argument: ${flag}`);
+  }
+  if (!VARIANTS.includes(args.variant) || !args.cwd) throw new Error('--variant and --cwd are required for a harness variant');
+  if (args['claude-dir'] && (!SKILL_VARIANTS.includes(args.variant)
+    || !(platform === 'win32' ? win32.isAbsolute : isAbsolute)(args['claude-dir']))) throw new Error('--claude-dir requires a skill variant and an absolute path');
+  if (Boolean(args.apply) !== Boolean(args.expect) || (args.expect && !/^[0-9a-f]{64}$/.test(args.expect))) {
+    throw new Error('--apply requires --expect with 64 lowercase hex characters');
+  }
+  args.root = resolve(args.cwd);
+  if (!statSync(args.root).isDirectory()) throw new Error('--cwd must be a directory');
+  return args;
+};
+export const main = (argv, io = {}) => {
+  const resolved = { log: console.log, error: console.error, env: process.env, home: homedir(),
+    platform: process.platform, toolsDir: TOOLS,
+    spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
+  let args;
+  try {
+    args = parse(argv, resolved.platform);
+  } catch (error) {
+    resolved.error(error.message);
+    return 2;
+  }
+  if (args.help) {
+    resolved.log(USAGE);
+    return 0;
+  }
+  const facts = { toolsDir: resolved.toolsDir, root: args.root, env: resolved.env, home: resolved.home,
+    platform: resolved.platform, claudeDir: args['claude-dir'] };
+  let result;
+  try {
+    result = checkApply(args.variant, facts, { detect: resolved.detect });
+  } catch (error) {
+    for (const line of error.lines ?? [error.message]) resolved.log(line);
+    return 3;
+  }
+  for (const line of result.lines) resolved.log(line);
+  if (result.refused.length) return 1;
+  if (!args.apply) return 0;
+  if (args.expect !== result.digest) return 5;
+  const spawnFacts = facts.claudeDir ? { ...facts, env: { ...facts.env, CLAUDE_CONFIG_DIR: facts.claudeDir } } : facts;
+  const child = resolved.spawn(consoleArgv(args.variant, spawnFacts).apply,
+    { cwd: facts.root, env: resolved.env, stdio: 'inherit' });
+  if (child.status === 0) return 0;
+  resolved.error(`apply exited ${child.status}`);
+  return 6;
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/bridge-sandbox-recipe.mjs

@@ -1,23 +1,91 @@
-// bridge-sandbox-recipe.mjs — the one reader of the bundled bridges' declared sandbox surfaces
-// (contract: bridges/velocity-profile). The bridge tier seeds the hosts it returns and the
-// Recommendations sandbox-lane recipe renders hosts and dirs from it, so the two cannot drift.
+// bridge-sandbox-recipe.mjs — the one reader of the bundled bridges' declared sandbox surfaces and
+// the one derivation of the bridge tier (contract: bridges/velocity-profile, revision 4). The tier
+// writer, the advisor's delta, the danger check and the autonomy preview read the same
+// `bundledSandboxRecipe(usedBridges(...))`, so the four cannot drift.
 //
 // Dependency-free, Node >= 22. No side effects on import.
 
 import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
+import { ACTIVITIES, BACKEND_PRIORITY, REVIEW_CMD_ALIASES } from './carriers.mjs';
+import { planRecipe, resolveActivityRecipe } from './recipes.mjs';
+import { isReadyMember } from './review-roster-resolve.mjs';
+import { isSeedablePathToken } from './repo-lex.mjs';
 
-// The manifest-declared session-sandbox recipe surfaces of every BUNDLED bridge whose review
-// wrapper is in the wired set — networkHosts ∪ writableDirs, derived from the manifests (the
-// single documentation source), never hardcoded here.
-export const bundledSandboxRecipe = (placedWrappers, deps) => {
+// The review wrappers, spelled bare as invoked. Only their `code` mode is auto-allowed: a bare
+// `Bash(<wrapper>:*)` prefix would also cover the plan/diff file-argument modes, whose targets can
+// point outside the repo, so those keep their prompt.
+export const BRIDGE_REVIEW_WRAPPERS = Object.freeze(['codex-review', 'agy-review']);
+export const BRIDGE_REVIEW_MODE = 'code';
+// The grounding pre-step (agy's facts assembler), seeded in the EXACT quoted byte-form the
+// procedures advisor renders, so seeded and rendered stay byte-equal.
+export const KIT_GROUNDING_TOOL = 'tools/grounding.mjs';
+const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const GROUNDING_WRAPPER = 'agy-review';
+// An exclusion is Bash rule syntax: a bare name matches only the argument-free command, so the
+// tier writes `<wrapper> *`, which matches it with arguments.
+export const exclusionOf = (wrapper) => `${wrapper} *`;
+
+const ROLE_ORDER = Object.freeze(['review', 'execute']);
+const SLOT_ROLE = Object.freeze({ review: 'review', execute: 'execute' });
+
+// The bridges the project's recipes USE: every review slot and every execute-type slot of every
+// activity, resolved to its EFFECTIVE recipe over the config and the readiness (a degraded recipe
+// names what it degrades to; an absent config is the computed default). A ready provider has its
+// wrapper on PATH, so used implies placed; a bridge no slot uses is absent however placed.
+export const usedBridges = (config, readiness) => {
+  const roles = new Map();
+  const take = (bridge, role) => {
+    if (!BACKEND_PRIORITY.includes(bridge)) return;
+    if (!roles.has(bridge)) roles.set(bridge, new Set());
+    roles.get(bridge).add(role);
+  };
+  for (const [activity, def] of Object.entries(ACTIVITIES)) {
+    for (const [slot, type] of Object.entries(def.slots)) {
+      const role = SLOT_ROLE[type];
+      if (role === undefined) continue;
+      const resolved = resolveActivityRecipe({ config: config ?? {}, readiness, activity, slot });
+      if (resolved.roster) {
+        for (const row of resolved.roster) {
+          if (row.kind === 'bridge' && isReadyMember(row)) take(REVIEW_CMD_ALIASES[row.member].backend, role);
+        }
+        continue;
+      }
+      for (const step of planRecipe(resolved.recipe, readiness).dispatch) take(step.backend, role);
+    }
+  }
+  return [...roles.keys()].sort().map((bridge) => ({
+    bridge,
+    roles: ROLE_ORDER.filter((role) => roles.get(bridge).has(role)),
+  }));
+};
+
+// An array of review-wrapper NAMES (the sandbox-lane call) reads as review-role entries.
+const rolesFor = (used, manifest) => {
+  if (used.every((entry) => typeof entry === 'string')) {
+    return used.includes(manifest?.roles?.review?.cmd) ? ['review'] : [];
+  }
+  return used.find((entry) => entry?.bridge === manifest?.name)?.roles ?? [];
+};
+
+const pushOnce = (list, value) => {
+  if (!list.includes(value)) list.push(value);
+};
+
+// The surfaces of the used bridges over the bundled manifests, in manifest-name order, each list in
+// its own order, a value already taken skipped.
+export const bundledSandboxRecipe = (used, deps = {}) => {
   const readFile = deps.readFile ?? readFileSync;
   const readDir = deps.readdir ?? readdirSync;
   const bundleRoot = deps.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
+  const allow = [];
+  const excludedCommands = [];
   const hosts = [];
   const dirEntries = [];
-  for (const dir of readDir(bundleRoot)) {
+  const skips = [];
+  for (const dir of [...readDir(bundleRoot)].sort()) {
     // An unreadable/unparsable bundled manifest must NOT thin the recipe silently — a partial
     // recipe rendered as complete is worse than none. The throw reaches the caller: a stated skip
     // in the advisor, a STOP with zero writes in the bridge tier.
@@ -29,12 +97,31 @@ export const bundledSandboxRecipe = (placedWrappers, deps) => {
       if (err?.code === 'ENOTDIR') continue;
       throw new Error(`bundled manifest unreadable: ${join(dir, 'capability.json')} — ${err?.message ?? err}`);
     }
-    const reviewCmd = manifest?.roles?.review?.cmd;
-    if (!reviewCmd || !placedWrappers.includes(reviewCmd)) continue;
-    if (Array.isArray(manifest.networkHosts)) {
-      for (const h of manifest.networkHosts) if (!hosts.includes(h)) hosts.push(h);
+    const roles = rolesFor(used, manifest);
+    if (roles.length === 0) continue;
+    for (const role of roles) {
+      const cmd = manifest?.roles?.[role]?.cmd;
+      if (!cmd) continue;
+      pushOnce(excludedCommands, exclusionOf(cmd));
+      if (role !== 'review') continue;
+      pushOnce(allow, `Bash(${cmd} ${BRIDGE_REVIEW_MODE}:*)`);
+      if (cmd === GROUNDING_WRAPPER) {
+        // groundingAbsPath binds the danger check's scope to the kit path it checks
+        // (apply-danger-check.mjs) and lets a test build an unseedable path; the writer never passes it.
+        const groundingAbs = deps.groundingAbsPath ?? join(KIT_ROOT, KIT_GROUNDING_TOOL);
+        if (isSeedablePathToken(groundingAbs)) pushOnce(allow, `Bash(node "${groundingAbs}":*)`);
+        else skips.push({
+          entry: groundingAbs,
+          reason: 'the kit path is not a POSIX absolute path free of spaces/metacharacters/quoting — the grounding pre-step rule is not seeded (its prompt stays); add a hand-picked entry if you accept the spelling',
+        });
+      }
+    }
+    if (Array.isArray(manifest.networkHosts)) for (const host of manifest.networkHosts) pushOnce(hosts, host);
+    if (Array.isArray(manifest.writableDirs)) {
+      for (const entry of manifest.writableDirs) {
+        if (!dirEntries.some((taken) => JSON.stringify(taken) === JSON.stringify(entry))) dirEntries.push(entry);
+      }
     }
-    if (Array.isArray(manifest.writableDirs)) dirEntries.push(...manifest.writableDirs);
   }
-  return { hosts, dirEntries };
+  return { allow, excludedCommands, hosts, dirEntries, skips };
 };