@sabaiway/agent-workflow-kit 14.23.0 → 14.25.0

package/tools/mcp.mjs

@@ -16,7 +16,7 @@
 //     would be a client error on every startup;
 //   • merge-don't-clobber — foreign servers, foreign settings keys and existing allow rules are
 //     preserved; re-apply adds nothing twice; the file's EOL is kept;
-//   • a same-name entry that STRUCTURALLY DIFFERS is REFUSED unwritten (key order is ignored, so a
+//   • without `--replace`, a same-name entry that STRUCTURALLY DIFFERS is REFUSED unwritten (key order is ignored, so a
 //     re-serialized identical entry is the SAME registration) — silently changing what an MCP server
 //     launches is exactly what consent must not slide past; the recovery is named;
 //   • the preflight is READ-ONLY: an absent `.claude/` is a NAMED state, and the dir is created on
@@ -32,11 +32,16 @@
 // Exit codes: 0 done / dry-run (incl. the hand-apply masked state); 1 precondition STOP; 2 usage.
 // Dependency-free beyond the kit's own exports, Node >= 22. No side effects on import.
 
-import { lstatSync } from 'node:fs';
+import {
+  lstatSync, openSync, closeSync, fstatSync, writeFileSync, ftruncateSync, fsyncSync,
+  renameSync, constants,
+} from 'node:fs';
 import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertCreatableDirSafe, writeContainedFileAtomic } from './atomic-write.mjs';
 import { isDirectRun } from './direct-run.mjs';
+import { describeNonRegular } from './fs-read-nofollow.mjs';
+import { assertContainedRealPath } from './fs-safe.mjs';
 import {
   CLAUDE_DIR_REL,
   ENABLED_KEY,
@@ -67,16 +72,16 @@ const LF = '\n';
 const JSON_INDENT = 2;
 
 export const MCP_TOOL = fileURLToPath(import.meta.url);
-export const applyMcpCommand = (root) => `node ${q(MCP_TOOL)} --apply --cwd ${q(root)}`;
+export const applyMcpCommand = (root, replace = false) => `node ${q(MCP_TOOL)}${replace ? ' --replace' : ''} --apply --cwd ${q(root)}`;
 
-const USAGE = `usage: mcp [--dry-run | --apply] [--cwd <dir>] [--help]
+const USAGE = `usage: mcp [--dry-run | --apply] [--replace] [--cwd <dir>] [--help]
 
 Registers this kit's stdio MCP server in ONE project: the "${SERVER_NAME}" entry in
 ${MCP_JSON_REL}, and "${ENABLED_KEY}" + the two tool allow rules in ${SETTINGS_REL}.
 Default is --dry-run (a preview that prints the exact entry and writes nothing).
---apply writes: ${MCP_JSON_REL} first, then ${SETTINGS_REL}; merge-don't-clobber, EOL kept.
+--apply writes: ${MCP_JSON_REL} first, then ${SETTINGS_REL}; merge-don't-clobber, EOL kept. An existing target is written in place; --replace replaces a differing entry only with --apply.
 
-An existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
+Without --replace, an existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
 order is ignored). Where ${MCP_JSON_REL} is a device node, FIFO or socket — an OS sandbox
 mask is the usual cause — the entry to merge is printed and nothing is written.
 Never writes settings.local.json; never commits.`;
@@ -122,7 +127,7 @@ const assertTargetUsable = (target, { maskedAllowed = false } = {}) => {
   }
 };
 
-export const preflightMcp = ({ cwd }, deps = {}) => {
+export const preflightMcp = ({ cwd, replace = false }, deps = {}) => {
   const root = resolve(cwd ?? deps.cwd ?? process.cwd());
   // The ROOT is judged BEFORE the registration is read, not merely before the first write: reading
   // first would follow the very link this refuses, which is exactly what the shipped claim denies.
@@ -152,7 +157,7 @@ export const preflightMcp = ({ cwd }, deps = {}) => {
   }
   assertTargetUsable(registration.mcpJson, { maskedAllowed: true });
   assertTargetUsable(registration.settings);
-  if (registration.mcpJson.differs) {
+  if (registration.mcpJson.differs && !replace) {
     throw makeMcpError(
       MCP_DIFFERS,
       `${MCP_JSON_REL} already carries an "${SERVER_NAME}" server entry that STRUCTURALLY DIFFERS from this kit copy's registration — refusing to change what it launches; review that entry and remove or rename it, then re-run`,
@@ -173,8 +178,53 @@ export const planMcp = (registration) => ({
 
 // ── the writer ─────────────────────────────────────────────────────────────────────────
 
-export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
-  const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd() }, deps);
+const writeTarget = (root, target, body, deps, stop) => {
+  const leaf = lstatNoFollow(target.abs, deps.lstat);
+  if (target.state === STATE.ABSENT) {
+    const assertAbsent = (dst) => {
+      if (lstatNoFollow(dst, deps.lstat) !== null) {
+        throw Object.assign(new Error('EEXIST'), { code: 'EEXIST' });
+      }
+    };
+    assertAbsent(target.abs);
+    const rename = (tmp, dst) => {
+      assertAbsent(dst);
+      (deps.rename ?? renameSync)(tmp, dst);
+    };
+    return writeContainedFileAtomic(root, target.abs, body, { ...deps, rename }, { stop, label: target.rel });
+  }
+  if (leaf?.isSymbolicLink()) {
+    throw stop(`${target.rel} is a symlink — refusing to replace it (a write would clobber the link target)`);
+  }
+  try {
+    assertContainedRealPath(root, target.abs, deps);
+  } catch (err) {
+    throw stop(String(err?.message ?? err).replace(/^\[agent-workflow-kit\] /, ''));
+  }
+  const flags = deps.constants ?? constants;
+  if (!flags.O_NOFOLLOW || !flags.O_NONBLOCK) {
+    throw stop('this platform exposes no usable O_NOFOLLOW|O_NONBLOCK open flags — refusing to open (fail closed)');
+  }
+  const fd = (deps.open ?? openSync)(target.abs, flags.O_WRONLY | flags.O_NOFOLLOW | flags.O_NONBLOCK);
+  try {
+    const stat = (deps.fstat ?? fstatSync)(fd);
+    if (!stat.isFile()) {
+      throw stop(`${target.rel} is a ${describeNonRegular(stat)} — refusing to write through it`);
+    }
+    if (leaf === null || stat.dev !== leaf.dev || stat.ino !== leaf.ino) {
+      throw stop('the leaf changed identity between lstat and open (fail closed)');
+    }
+    const bytes = Buffer.from(body, 'utf8');
+    (deps.writeFile ?? writeFileSync)(fd, bytes);
+    (deps.ftruncate ?? ftruncateSync)(fd, bytes.length);
+    (deps.fsync ?? fsyncSync)(fd);
+  } finally {
+    (deps.close ?? closeSync)(fd);
+  }
+};
+
+export const writeMcp = ({ cwd, dryRun = true, replace = false } = {}, deps = {}) => {
+  const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd(), replace }, deps);
   const base = { ...preflight, dryRun, wrote: false };
   if (preflight.masked) return { ...base, fragments: renderFragments(preflight.registration) };
   if (dryRun) return base;
@@ -182,7 +232,7 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
   const { root, registration, plan } = preflight;
   const stop = (message) => makeMcpError(MCP_SYMLINK, message);
   if (plan.writeMcpJson) {
-    writeContainedFileAtomic(root, registration.mcpJson.abs, plan.mcpBody, deps, { stop, label: MCP_JSON_REL });
+    writeTarget(root, registration.mcpJson, plan.mcpBody, deps, stop);
   }
   if (plan.writeSettings) {
     // A settings failure AFTER the entry landed leaves a STANDING registration on disk that never
@@ -194,12 +244,12 @@ export const writeMcp = ({ cwd, dryRun = true } = {}, deps = {}) => {
       // The ONE write the preflight deliberately does not do: creating `.claude/` is a mutation, so
       // it belongs on the apply lane only — a preview that made a directory would not be a preview.
       assertCreatableDirSafe(join(root, CLAUDE_DIR_REL), deps, { stop, noun: SETTINGS_REL });
-      writeContainedFileAtomic(root, registration.settings.abs, plan.settingsBody, deps, { stop, label: SETTINGS_REL });
+      writeTarget(root, registration.settings, plan.settingsBody, deps, stop);
     } catch (err) {
       // Reaching here always leaves a STANDING registration on disk — either this run wrote the
       // entry (`writeMcpJson`) or the preflight found it already current (`matches`), and those two
       // are exhaustive, so the note is unconditional rather than guarded by a branch nothing can
-      // take. A differing entry never reaches the writer at all; it STOPs in the preflight.
+      // take. Without --replace, a differing entry STOPs in the preflight.
       throw Object.assign(err, { message: `${err.message}\n${HIDDEN_MODE_LINE}` });
     }
   }
@@ -221,7 +271,9 @@ const indented = (text) => text.trimEnd().split(LF).map((line) => `    ${line}`)
 
 const mcpJsonLine = (result) => {
   if (!result.plan.writeMcpJson) return `  - ${MCP_JSON_REL}: already current`;
-  const verb = result.dryRun ? 'would add' : 'added';
+  const verb = result.registration.mcpJson.differs
+    ? (result.dryRun ? 'would replace' : 'replaced')
+    : (result.dryRun ? 'would add' : 'added');
   return `  - ${MCP_JSON_REL}: ${verb} the "${SERVER_NAME}" stdio entry`;
 };
 
@@ -264,24 +316,29 @@ export const formatResult = (result) => {
       : 'agent-workflow MCP registration — APPLY',
     mcpJsonLine(result),
     settingsLine(result),
+    ...(result.registration.mcpJson.differs ? [
+      '  the entry standing in .mcp.json now:',
+      indented(JSON.stringify(result.registration.mcpJson.existing, null, JSON_INDENT)),
+    ] : []),
     '  the entry this registration declares (re-serialized here; the same structured value goes into the file):',
     indented(JSON.stringify(result.registration.entry, null, JSON_INDENT)),
     POSTURE_LINE,
     HIDDEN_MODE_LINE,
   ];
-  if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root)}`);
+  if (result.dryRun) lines.push(`  to apply: ${applyMcpCommand(result.root, result.registration.mcpJson.differs)}`);
   return lines.join(LF);
 };
 
 // ── CLI ────────────────────────────────────────────────────────────────────────────────
 
 export const parseArgs = (argv) => {
-  const opts = { dryRunFlag: false, apply: false, cwd: undefined, help: false };
+  const opts = { dryRunFlag: false, apply: false, replace: false, cwd: undefined, help: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--help' || arg === '-h') opts.help = true;
     else if (arg === '--dry-run') opts.dryRunFlag = true;
     else if (arg === '--apply') opts.apply = true;
+    else if (arg === '--replace') opts.replace = true;
     else if (arg === '--cwd') {
       i += 1;
       // An EMPTY (or whitespace) value passes both guards above, and `resolve('')` silently means the
@@ -296,7 +353,7 @@ export const parseArgs = (argv) => {
     }
   }
   if (opts.dryRunFlag && opts.apply) throw fail(EXIT_USAGE, '--dry-run and --apply cannot be used together');
-  return { help: opts.help, dryRun: !opts.apply, cwd: opts.cwd };
+  return { help: opts.help, dryRun: !opts.apply, replace: opts.replace, cwd: opts.cwd };
 };
 
 export const main = (argv = process.argv.slice(2), deps = {}) => {
@@ -308,10 +365,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(USAGE);
       return EXIT_OK;
     }
-    log(formatResult(writeMcp({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun }, deps)));
+    log(formatResult(writeMcp({ cwd: args.cwd ?? deps.cwd ?? process.cwd(), dryRun: args.dryRun, replace: args.replace }, deps)));
     return EXIT_OK;
   } catch (err) {
-    errlog(err?.message ?? String(err));
+    const message = err?.message ?? String(err);
+    errlog(err?.code && err.name !== 'McpError' && !message.includes(err.code) ? `${err.code}: ${message}` : message);
     if (err?.exitCode === EXIT_USAGE) errlog(USAGE);
     return err?.exitCode ?? EXIT_PRECONDITION;
   }

package/tools/recommendations.mjs

@@ -19,9 +19,9 @@
 // below) and VERDICT-FIRST (D1): every non-optimal state opens with ONE composed verdict line.
 // Registry strings are frozen tool DATA, fact-true, one line under the shape cap (D2); posture/
 // risk prose lives in the mode doc at the consent moment (D3). A probe failure is a stated
-// skipped-item line — never a crash, never a fabricated item. The kit never seeds
-// sandbox.network.allowedDomains / filesystem.allowWrite (HAND-APPLY territory; bridge council
-// 2026-07-11, both backends concur); the sandbox-lane item's convergence is a NEUTRAL
+// skipped-item line — never a crash, never a fabricated item. sandbox.filesystem.allowWrite stays
+// HAND-APPLY territory; sandbox.network.allowedDomains is seeded only by the consented
+// `velocity-profile --bridge-tier` (AD-172); the sandbox-lane item's convergence is a NEUTRAL
 // fingerprint-bound acknowledgement recorded by the consent-gated ack writer into the family-owned
 // docs/ai/acks.json (AD-055 relocated it off the host settings schema), never a security key (D4).
 //
@@ -48,7 +48,8 @@ import {
   SETTINGS_LOCAL_FILE,
 } from './velocity-profile.mjs';
 import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-config.mjs';
-import { deriveDoctorPlan } from './autonomy-doctor.mjs';
+import { deriveDoctorPlan, TRUSTED_DIRS } from './autonomy-doctor.mjs';
+import { laneOf, routeLine } from './write-lanes.mjs';
 import { detectBackends, findOnPath } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
@@ -60,7 +61,6 @@ import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKit
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 // The typed channel's READ-ONLY leaf only — never tools/mcp.mjs, which reaches the write core.
 import {
-  MCP_JSON_REL,
   SERVER_NAME as MCP_SERVER_NAME,
   STATE as MCP_STATE,
   readRegistration,
@@ -79,7 +79,7 @@ import { CHECKER_CLAIM, INITIAL_ADOPTION_REASON, SOURCE_SIZE_GATE_ID, classifySo
 import { resolveDeclaredDir, dirCovers, isResolvableDeclaredEntry } from './declared-paths.mjs';
 import { resolveGitHooksPath } from './commit-guard.mjs';
 import { loadConfig } from './orchestration-config.mjs';
-import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.mjs';
+import { bundledSandboxRecipe } from './bridge-sandbox-recipe.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
 import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
@@ -103,7 +103,7 @@ import {
 import { ADOPTION, STORE_DIR_REL as SPEC_STORE_DIR_REL, SPEC_ADOPTION_LANE, declineFingerprint, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
 import { ENSURE_OPS } from './ensure-vocabulary.mjs';
 import { composeProfileGapScreen } from './profile-gap-screen.mjs';
-import { NO_APPLY_LINE, SKILL_PINS, claudeDirOf, connectLine, keySet, placeOf, printable, skillLine, skillState, skillTargets } from './jev-facts.mjs';
+import { NO_APPLY_LINE, SKILL_PINS, claudeDirOf, keySet, placeOf, printable, skillLine, skillState, skillTargets } from './jev-facts.mjs';
 
 // The upgrade ensure that seeds the spec store — the not-adopted item's apply; pinned to the vocabulary.
 const SPEC_LAYER_ENSURE = ENSURE_OPS.includes('specs') ? 'specs' : null;
@@ -117,7 +117,7 @@ export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
 const q = shellQuoteArg;
-const ENFORCEMENT_ABSENT_CODE = 'ENOENT';
+const ABSENT_CODE = 'ENOENT';
 const ENFORCEMENT_KIT_ROOT = resolve(HERE, '..');
 const ENFORCEMENT_BUNDLE_ROOT = join(ENFORCEMENT_KIT_ROOT, 'references', 'scripts');
 const ENFORCEMENT_WHAT = 'the enforcement scripts are not deployed beside docs/ai (no Node evidence) \u2014 the offer copies them and installs the pre-commit hook';
@@ -155,6 +155,7 @@ export const SEVERITIES = Object.freeze({
   'autonomy-policy': SEVERITY_OPTIONAL,
   'autonomy-render': SEVERITY_ATTENTION,
   'sandbox-provision': SEVERITY_OPTIONAL,
+  'sandbox-provision.installable': SEVERITY_OPTIONAL,
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gates-inert': SEVERITY_ATTENTION,
@@ -185,12 +186,7 @@ export const SEVERITIES = Object.freeze({
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
   'state-block': SEVERITY_OPTIONAL,
-  // The typed channel. The base arm is an ordinary offer; `.masked` stays an offer too (nothing is
-  // broken — the kit simply cannot write through a device node, so the remedy is handed over);
-  // `.differing` reports a CONFIGURED declaration that would launch something else, which is the
-  // one state here a maintainer must actually look at.
   'mcp-channel': SEVERITY_OPTIONAL,
-  'mcp-channel.masked': SEVERITY_OPTIONAL,
   'mcp-channel.differing': SEVERITY_ATTENTION,
   agents: SEVERITY_OPTIONAL,
   // The `agents` row above is an OFFER to place vehicles. This one reports a config that ALREADY
@@ -252,7 +248,7 @@ export const composeVerdict = ({ attention, optional, skipped }) => {
 export const WHATS = Object.freeze({
   'velocity-core': 'routine read-only commands still prompt — {n} audited read-only allowlist entr(ies) not seeded',
   'kit-tools-tier': "the kit's own read-only tools still prompt — {n} kit-tools tier entr(ies) not seeded",
-  'bridge-tier': 'council review runs prompt per bridge invocation — {n} bridge-wrappers tier entr(ies) not seeded (placed bridges only, code mode only)',
+  'bridge-tier': 'bridge-wrappers tier incomplete — {n} entr(ies) missing (allow rules, sandbox exclusions or declared hosts of placed bridges)',
   'autonomy-policy': 'no {path} — the computed defaults apply implicitly (red-lines ask/deny; every activity floors at prompt)',
   'autonomy-render': 'the declared autonomy policy is not rendered into .claude/settings.json — drift: {drift}',
   'sandbox-provision': 'the OS sandbox is unavailable: {reason}',
@@ -276,7 +272,6 @@ export const WHATS = Object.freeze({
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
   'state-block': 'nothing checks the closing state block — a turn that ends on «nothing needed from you», or on a promise it never started, passes unseen',
   'mcp-channel': "the kit's read-only MCP server is not registered here — path questions and literal searches stay shell strings",
-  'mcp-channel.masked': '{rel} is a {className} here (a sandbox device mask is the usual cause), so the entry to merge is printed instead',
   'mcp-channel.differing': 'an "{server}" MCP entry is already declared here and DIFFERS from the registration this kit copy would write',
   agents: '{n} bundled subagent vehicle(s) not placed (Claude Code) — {ro} read-only, {ex} the full-tool executor; the apply PREVIEWS first',
   'executor-vehicle': '{n} slot(s) configured subagent but the executor vehicle is {state}{reason} — every such slot runs solo until it is usable',
@@ -415,7 +410,7 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'executor-vehicle', mode: 'agents', advisorKey: 'executor-vehicle' },
   // Exempt, not un-audited. `acceptEdits` auto-applies Edit/Write and auto-runs mkdir/touch/mv/cp:
   // a TRUST-POSTURE change. The kit never nudges a user toward weakening their approval posture (the
-  // same doctrine that keeps sandbox network/filesystem allowances HAND-APPLY); velocity presents the
+  // same doctrine that keeps sandbox filesystem allowances HAND-APPLY); velocity presents the
   // full honest posture at its own consent moment, where the user is already deciding.
   {
     id: 'accept-edits',
@@ -465,8 +460,8 @@ const probeVelocityItems = ({ root, deps, add, skip }) => {
     skip('kit-tools-tier', err);
   }
   try {
-    const bt = planVelocityProfile(preflight, { bridgeTier: true, findWrapper: deps.findWrapper });
-    const delta = bt.bridgeToAdd.length + bt.excludedToAdd.length;
+    const bt = planVelocityProfile(preflight, { bridgeTier: true, findWrapper: deps.findWrapper, bundleRoot: deps.bundleRoot, readdir: deps.readdir, readFile: deps.readFile });
+    const delta = bt.bridgeToAdd.length + bt.excludedToAdd.length + bt.hostsToAdd.length;
     if (delta > 0) {
       add('bridge-tier', fillTemplate(WHATS['bridge-tier'], { n: delta }), applyLine(' --bridge-tier'));
     }
@@ -507,12 +502,18 @@ const probeSandboxProvision = ({ root, deps, add, skip }) => {
   try {
     const p = probeSandboxAvailability(deps);
     if (p.available) return;
-    const plan = deriveDoctorPlan({ probeResult: p, env: deps.env ?? process.env, isExec: deps.isExecutable ?? isExecutableFile });
-    const variant = plan.tuple ? 'sandbox-provision.installable' : 'sandbox-provision';
-    const reason = truncatedTo(oneLineOf(p.reason), templateBudget(WHATS[variant]) - (plan.tuple ? String(plan.tuple).length : 0));
+    const isExec = deps.isExecutable ?? isExecutableFile;
+    const plan = deriveDoctorPlan({ probeResult: p, env: deps.env ?? process.env, isExec });
+    const installable = plan.tuple !== null && plan.untrusted.length === 0 && !plan.envMissing
+      && ((deps.euid ?? (() => process.geteuid?.()))() === 0 || TRUSTED_DIRS.some((dir) => isExec(join(dir, 'sudo'))));
+    const variant = installable ? 'sandbox-provision.installable' : 'sandbox-provision';
+    const reason = truncatedTo(oneLineOf(p.reason), templateBudget(WHATS[variant]) - (installable ? plan.tuple.length : 0));
     // The doctor reads process.cwd() (deployment-gated) and takes no --cwd flag — the one-liner
     // pins the target project via a cd prefix (Segment B).
-    add('sandbox-provision', fillTemplate(WHATS[variant], { reason, tuple: plan.tuple }), `cd ${q(root)} && node ${q(toolPath('autonomy-doctor.mjs'))}`);
+    add('sandbox-provision', fillTemplate(WHATS[variant], { reason, tuple: plan.tuple }),
+      `cd ${q(root)} && node ${q(toolPath('autonomy-doctor.mjs'))}`, variant,
+      installable ? null : 'on native Windows Claude Code runs no sandbox: this item takes no effect there',
+    );
   } catch (err) {
     skip('sandbox-provision', err);
   }
@@ -884,6 +885,7 @@ const probeCommitGuard = ({ root, deps, add, skip }) => {
     if (hooksPath === null) return; // not a git tree — nothing to hook
     const hook = (() => {
       try {
+        if (readsAbsent(deps, join(hooksPath, 'pre-commit'))) return null;
         return String(read(join(hooksPath, 'pre-commit'), 'utf8'));
       } catch {
         return null;
@@ -904,7 +906,7 @@ const readEnforcementNode = (path, lstat) => {
   try {
     return lstat(path);
   } catch (err) {
-    if (err?.code === ENFORCEMENT_ABSENT_CODE) return null;
+    if (err?.code === ABSENT_CODE) return null;
     throw new Error(`${path}: ${err?.code ?? err?.message ?? err}`);
   }
 };
@@ -954,7 +956,7 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
     // is silently dark; surface it as attention with a place-first recovery (council R2-M2).
     const placeRecovery = () =>
       add('read-lane', fillTemplate(WHATS['read-lane.missing'], {}), `node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`, 'read-lane.missing');
-    if (!sg.filePlaced) {
+    if (!sg.filePlaced || readsAbsent(deps, join(root, GATE_HOOK_REL))) {
       placeRecovery();
       return;
     }
@@ -1099,9 +1101,9 @@ const probeExecutorVehicle = ({ root, deps, add, skip }) => {
       }),
       // The writer places a missing vehicle and re-derives a placed executor whose bytes differ from the derived body (an invalid
       // frontmatter or read-only tools included), so those states need no precondition; every precondition above is a refusal the apply would meet.
-      `${preconditions.length ? `HAND-APPLY: ${preconditions.join('; ')}, then run: ` : ''}node ${q(toolPath('cheap-agents.mjs'))} --apply --cwd ${q(root)}`,
+      `node ${q(toolPath('cheap-agents.mjs'))} --apply --cwd ${q(root)}`,
       'executor-vehicle',
-      `hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
+      `${preconditions.length ? `precondition: ${preconditions.join('; ')}; ` : ''}hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
     );
   } catch (err) {
     skip('executor-vehicle', err);
@@ -1157,37 +1159,6 @@ const probeMasksItem = ({ root, deps, add, skip }) => {
 // knob is retired in the wrappers (recognized, arms nothing) and an oversized code review is now a
 // chunked feed with a per-part delivery proof, so there is nothing left to offer.
 
-// 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.
-const bundledSandboxRecipe = (placedWrappers, deps) => {
-  const readFile = deps.readFile ?? readFileSync;
-  const readDir = deps.readdir ?? readdirSync;
-  const bundleRoot = deps.bundleRoot ?? DEFAULT_BUNDLE_ROOT;
-  const hosts = [];
-  const dirEntries = [];
-  for (const dir of readDir(bundleRoot)) {
-    // An unreadable/unparsable bundled manifest must NOT thin the recipe silently — a partial
-    // recipe rendered as complete is worse than no item. The throw reaches the probe's catch and
-    // becomes a stated skip.
-    let manifest;
-    try {
-      manifest = JSON.parse(readFile(join(bundleRoot, dir, 'capability.json'), 'utf8'));
-    } catch (err) {
-      // ENOTDIR = the entry is a stray regular file (.DS_Store, a README), not a bridge bundle.
-      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);
-    }
-    if (Array.isArray(manifest.writableDirs)) dirEntries.push(...manifest.writableDirs);
-  }
-  return { hosts, dirEntries };
-};
-
 // D6 resolution, mirroring the wrappers' byte-semantics (`${VAR:-default}` + the exact case-arms:
 // `~` / `~/…` / `/…` ride as-given; EVERY other form — including `~user/…`, which the wrappers
 // never resolve as a home path — anchors like a relative path). The advisor anchors to the TARGET
@@ -1265,7 +1236,17 @@ const isStateBlockGuardWired = (data) => {
 // itself (a hook that is not there belongs to the place offers, never to a refresh arm); a symlink,
 // a directory and an unreadable target all THROW into the probe's stated-skip lane.
 const HOOK_CURRENCY = Object.freeze({ CURRENT: 'current', STALE: 'stale', ABSENT: 'absent' });
+const readsAbsent = (deps, path) => {
+  try {
+    (deps.lstat ?? lstatSync)(path);
+    return false;
+  } catch (err) {
+    return err?.code === ABSENT_CODE;
+  }
+};
+
 const readPlacedHookCurrency = (root, deps) => {
+  if (readsAbsent(deps, join(root, GATE_HOOK_REL))) return HOOK_CURRENCY.ABSENT;
   const read = deps.readRegularFileNoFollow ?? readRegularFileNoFollow;
   const placed = read(join(root, GATE_HOOK_REL));
   if (placed.outcome === 'absent') return HOOK_CURRENCY.ABSENT;
@@ -1322,7 +1303,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement', 'profile-gap', 'jev-connect', 'jev-skill']);
+export const RISK_NOTED_KEYS = Object.freeze(['bridge-tier', 'sandbox-lane', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement', 'profile-gap', 'jev-connect', 'jev-skill']);
 
 // The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
 // zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
@@ -1362,9 +1343,11 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
     const sandbox = settings.data?.sandbox;
     const excluded = Array.isArray(sandbox?.excludedCommands) ? sandbox.excludedCommands : [];
     const probePlaced = deps.findWrapper ?? ((cmd) => findOnPath(cmd, deps).state === 'present');
-    // Wired = the FULL two-surface tier proof (excludedCommands + the code-mode allow rule, either
-    // scope) — surfacing the recipe while the tier is half-configured would front-run the
-    // bridge-tier item (codex terminal). Byte-form from the tier's own constants.
+    // Wired = the two-surface proof the tier wrote before AD-172 (the wrapper in the PROJECT
+    // excludedCommands + its code-mode allow rule, either scope) — surfacing the recipe before those
+    // exist would front-run the bridge-tier item (codex terminal). The hosts surface (AD-172) is
+    // deliberately not required: the recipe also carries the writable dirs no tier seeds, so it may
+    // render beside a bridge-tier item offering the hosts re-run. Byte-form from the tier's own constants.
     const allowRules = [
       ...(Array.isArray(settings.data?.permissions?.allow) ? settings.data.permissions.allow : []),
       ...(Array.isArray(localSettings.data?.permissions?.allow) ? localSettings.data.permissions.allow : []),
@@ -1372,7 +1355,7 @@ const probeSandboxLane = ({ root, deps, add, skip }) => {
     const wired = BRIDGE_REVIEW_WRAPPERS.filter(
       (w) => excluded.includes(w) && probePlaced(w) && allowRules.includes(`Bash(${w} ${BRIDGE_REVIEW_MODE}:*)`),
     );
-    if (wired.length === 0) return; // the tier is not (fully) wired — the bridge-tier item covers first
+    if (wired.length === 0) return; // the tier's rules and exclusions are not wired — the bridge-tier item covers first
     const { hosts, dirEntries } = bundledSandboxRecipe(wired, deps);
     const env = deps.getenv ?? process.env;
     const home = deps.home ?? homedir();
@@ -1550,9 +1533,6 @@ export const probeAdrStore = ({ root, deps, add, skip }) => {
 
 // The typed-channel item. It asks the READ-ONLY registration leaf and nothing else — importing the
 // writer would pull the atomic-write core into the advisor's graph (read-graph-purity.test.mjs).
-// The rendered apply is the mode's FLAGLESS preview on purpose: registering an MCP server means the
-// client will RUN that command, so the entry is read before it is declared and the `--apply` stays
-// the maintainer's separate step.
 const probeMcpChannel = ({ root, deps, add, skip }) => {
   try {
     const registration = readRegistration(root, deps);
@@ -1567,49 +1547,16 @@ const probeMcpChannel = ({ root, deps, add, skip }) => {
     // settings half can end the probe. A differing entry is fully observable, and an unreadable
     // settings file says nothing about it — returning on the settings mask first hid it.
     assertReadable(registration.mcpJson);
-    const settingsUsable = registration.settings.state !== MCP_STATE.MASKED
-      && registration.settings.state !== MCP_STATE.FOREIGN
-      && registration.settings.state !== MCP_STATE.UNREADABLE
-      && registration.settings.state !== MCP_STATE.MALFORMED;
     if (registration.mcpJson.differs) {
-      // The remedy is the maintainer's edit either way; the "then run" tail is dropped where that
-      // command could not succeed, so the item never hands over a line that exits 1.
-      const tail = settingsUsable ? `, then run ${preview}` : '';
       add(
         'mcp-channel',
         fillTemplate(WHATS['mcp-channel.differing'], { server: MCP_SERVER_NAME }),
-        `HAND-APPLY: edit ${q(join(root, MCP_JSON_REL))} → remove or rename the "${MCP_SERVER_NAME}" entry${tail}`,
+        preview,
         'mcp-channel.differing',
       );
       return;
     }
     assertReadable(registration.settings);
-    // The HAND-APPLY arm renders the MODE's own preview, so it may fire only where that command can
-    // actually run — and the writer refuses a masked settings.json outright (it can neither write it
-    // nor merge into what it cannot read). A masked settings half is therefore a stated SKIP: the
-    // completeness this item decides on is unknowable, and offering a command that exits 1 is worse
-    // than saying nothing.
-    if (registration.settings.state === MCP_STATE.MASKED) {
-      skip('mcp-channel', new Error(`${registration.settings.rel} is a ${registration.settings.className} here (a sandbox device mask is the usual cause) — the registration cannot be judged or written from in here; verify it outside the sandbox`));
-      return;
-    }
-    if (registration.mcpJson.state === MCP_STATE.MASKED) {
-      // The kit cannot write through the mask either, so the remedy is HAND-APPLY. But when the
-      // settings half is already complete, the registration was almost certainly made from outside
-      // the sandbox: what cannot be observed becomes a stated SKIP (optimality withheld), never the
-      // same offer again on every single upgrade.
-      if (registration.settings.complete) {
-        skip('mcp-channel', new Error(`${registration.mcpJson.rel} is a ${registration.mcpJson.className} here (a sandbox device mask is the usual cause) and the settings half is already complete — verify the entry outside the sandbox`));
-        return;
-      }
-      add(
-        'mcp-channel',
-        fillTemplate(WHATS['mcp-channel.masked'], { rel: registration.mcpJson.rel, className: registration.mcpJson.className }),
-        `HAND-APPLY: ${preview}`,
-        'mcp-channel.masked',
-      );
-      return;
-    }
     if (registration.registered) return;
     add('mcp-channel', fillTemplate(WHATS['mcp-channel'], {}), preview);
   } catch (err) {
@@ -1618,16 +1565,16 @@ const probeMcpChannel = ({ root, deps, add, skip }) => {
 };
 
 // The Jev offer (contract: kit/jev-guide, part jev-offer). The key is judged first, through the facts leaf's one rule over
-// the injected environment; the apply is the connect command the USER runs in a terminal of their own (HAND-APPLY), never a guide.
+// the injected environment.
 export const probeJevConnect = ({ root, deps, add, skip }) => {
   try {
     const env = deps.getenv ?? {};
-    if (keySet(env)) return;
+    if (deps.keySet === true || keySet(env)) return;
     if (readAckValue(root, deps, ACKS_JEV_CONNECT_KEY) === JEV_CONNECT_DECLINE) return;
     const host = deps.jevHost ?? {};
     const place = placeOf({ env, platform: host.platform, hostname: host.hostname, container: host.container });
     const decline = `node ${q(toolPath('ack-write.mjs'))} --lane jev-connect --fingerprint ${JEV_CONNECT_DECLINE} --cwd ${q(root)}`;
-    add('jev-connect', WHATS['jev-connect'], `HAND-APPLY: ${connectLine(HERE, host.platform)}`, 'jev-connect',
+    add('jev-connect', WHATS['jev-connect'], routeLine('jev-connect'), 'jev-connect',
       `${place ? `run the apply in ${place}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
   } catch (err) {
     skip('jev-connect', err);
@@ -1639,7 +1586,7 @@ export const probeJevConnect = ({ root, deps, add, skip }) => {
 export const probeJevSkill = ({ root, deps, add, skip }) => {
   try {
     const env = deps.getenv ?? {};
-    if (!keySet(env)) return;
+    if (deps.keySet !== true && !keySet(env)) return;
     const host = deps.jevHost ?? {};
     if (typeof host.home !== 'string' || host.home === '') return;
     const pins = deps.jevPins ?? SKILL_PINS;
@@ -1739,14 +1686,29 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
       skip(key, new Error(`item shape violation — ${problems.join('; ')}`));
       return false;
     }
-    items.push({ key, variant, severity: SEVERITIES[variant], what, benefit: BENEFITS[key], apply, detail });
+    items.push({ key, variant, severity: SEVERITIES[variant], lane: laneOf(variant), what, benefit: BENEFITS[key], apply: routeLine(variant) ?? apply, detail });
     return true;
   };
   // The per-run scratch a probe uses to tell a LATER probe what it actually did. Written by exactly
   // one pair today (the marker-stale ⟷ read-lane.stale precedence) and read in the frozen PROBES
   // order, so the reader can never run first.
   const shared = {};
-  for (const probe of deps.probes ?? PROBES) probe({ root, deps, add, skip, shared });
+  const contentDeps = Object.create(Object.getPrototypeOf(deps), {
+    ...Object.getOwnPropertyDescriptors(deps),
+    lstat: {
+      enumerable: true,
+      value: (path, ...args) => {
+        const stat = (deps.lstat ?? deps.lstatSync ?? lstatSync)(path, ...args);
+        if (stat.isCharacterDevice?.() || stat.isBlockDevice?.()) {
+          throw Object.assign(new Error(`${ABSENT_CODE}: ${path}`), { code: ABSENT_CODE });
+        }
+        return stat;
+      },
+    },
+  });
+  for (const probe of deps.probes ?? PROBES) {
+    probe({ root, deps: probe === probeMasksItem ? deps : contentDeps, add, skip, shared });
+  }
   return { root, items, skips };
 };
 
@@ -1772,6 +1734,7 @@ export const formatRecommendations = ({ items, skips }) => {
     ordered.forEach((item, i) => {
       lines.push(`${i + 1}. ${SEVERITY_LABELS[item.severity] ?? SEVERITY_LABELS[SEVERITY_OPTIONAL]}: ${item.what}`);
       lines.push(`   benefit: ${item.benefit}`);
+      lines.push(`   lane: ${item.lane}`);
       if (item.detail) lines.push(`   recipe: ${item.detail}`);
       lines.push(`   apply: ${item.apply}`);
     });
@@ -1797,15 +1760,15 @@ section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a pro
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;
 the doctor item pins via a cd prefix; the ONE exception is the set-autonomy item — a
 conversational skill invocation labeled "run IN the target project") and preserve each writer's
-own consent semantics; the kit never seeds sandbox network/filesystem allowances (HAND-APPLY
-territory), and the sandbox-lane convergence is a neutral fingerprint acknowledgement recorded by
+own consent semantics; sandbox filesystem allowances stay HAND-APPLY territory, the placed bridges' declared hosts reach sandbox.network.allowedDomains only through the
+consented velocity-profile --bridge-tier, and the sandbox-lane convergence is a neutral fingerprint acknowledgement recorded by
 the consent-gated ack writer into docs/ai/acks.json (never a security key).
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;
 
 // The host facts of the key and skill offers: the platform, the hostname (a throw reads as none), /.dockerenv a regular file, the home.
-const hostFacts = () => ({ platform: process.platform, hostname: (() => { try { return hostname(); } catch { return ''; } })(),
+export const hostFacts = () => ({ platform: process.platform, hostname: (() => { try { return hostname(); } catch { return ''; } })(),
   container: (() => { try { return statSync('/.dockerenv').isFile(); } catch { return false; } })(),
   home: (() => { try { return homedir(); } catch { return ''; } })() });