@sabaiway/agent-workflow-kit 14.26.0 → 14.28.0

package/tools/ack-write.mjs

@@ -3,13 +3,13 @@
 // (docs/ai/acks.json, AD-055 Part I). An upgrade Recommendations item whose state can only be
 // ANSWERED renders THIS tool's PREVIEW one-liner; the preview prints the exact `--apply` command;
 // the agent runs `--apply` only after the mode doc's §3 informed-consent confirmation. It records a
-// NEUTRAL fingerprint acknowledgement — never a security key; the kit never writes sandbox
-// filesystem allowances, and allowedDomains only through velocity-profile --bridge-tier.
+// NEUTRAL fingerprint acknowledgement — never a security key; the bridge sandbox keys are written
+// by velocity-profile --bridge-tier alone.
 //
-// The wording is per-LANE or genuinely neutral, never "recipe": the sandbox lane acknowledges a
-// session-sandbox recipe, but the coverage-domain lane acknowledges a census FACT and the
-// source-size-copy lane a set of declared tool claims. One lane's noun stated over all of them was
-// simply false about the others.
+// The wording is per-LANE or neutral, never "recipe": each lane's fingerprint stands for a different
+// thing — the coverage-domain lane a census FACT, the source-size-copy lane declared tool claims.
+// The default lane's advisor item is retired; the lane is kept so a value already on disk keeps its
+// meaning (seen).
 //
 // Family writer discipline (velocity / orchestration-write / gate-hook), verbatim:
 //   • preview-then-mutate — `--dry-run` is the DEFAULT and writes nothing; `--apply` writes;
@@ -45,8 +45,8 @@ const JSON_INDENT = 2;
 // minted over a recipe or over a canonical fact string) — a fail-closed guard so the store never
 // records a malformed or injected value.
 export const FINGERPRINT_PATTERN = /^[0-9a-f]{16}$/u;
-// The lane this writer records when none is named — the original single-lane contract, so every
-// pre-existing sandbox-lane invocation and its rendered one-liner stay byte-identical.
+// The default lane is the original single-lane contract: without --lane, an invocation records what
+// it always did. Its advisor item is retired; the lane is kept.
 export const DEFAULT_ACK_LANE = 'sandbox-lane';
 
 export const ACK_WRITE_STOP = 'ACK_WRITE_STOP';
@@ -155,9 +155,9 @@ const USAGE = `usage: ack-write --fingerprint <16-hex> [--lane <${Object.keys(AC
 
 Records a NEUTRAL acknowledgement into ${ACKS_FILE} (the family-owned ack store — no host settings
 validator guards it). --lane names which advisor item is being acknowledged (default
-"${DEFAULT_ACK_LANE}") and what the fingerprint stands for — a session-sandbox recipe, a worktrees
-probe dir, a tracked-tree census fact, a set of declared tool claims; each lane owns one top-level
-key. Default is --dry-run (a preview; writes
+"${DEFAULT_ACK_LANE}") and what the fingerprint stands for — a worktrees probe dir, a tracked-tree
+census fact, a set of declared tool claims; each lane owns one top-level key. The default lane's
+advisor item is retired (a recorded value keeps its meaning). Default is --dry-run (a preview; writes
 nothing) and prints the exact --apply command. --apply merges that ONE key into ${ACKS_FILE},
 preserving every existing key. Refuses an absent docs/ai deployment; never a security key; never
 commits.`;

package/tools/apply-danger-check.mjs

@@ -6,12 +6,14 @@ import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
-  BRIDGE_REVIEW_WRAPPERS, CLAUDE_DIR, KIT_GROUNDING_TOOL, RENDER_OWNED_REDLINE_RULES,
+  CLAUDE_DIR, RENDER_OWNED_REDLINE_RULES,
   SAFE_DEFAULT_MODES, SETTINGS_FILE, SETTINGS_LOCAL_FILE, UNIVERSAL_READONLY_ALLOWLIST,
-  deriveBridgeTierAllowlist, deriveKitToolsAllowlist, mergeAutonomySettings,
+  deriveKitToolsAllowlist, detectAtRoot, mergeAutonomySettings,
   writeAutonomyProfile, writeVelocityProfile,
 } from './velocity-profile.mjs';
-import { bundledSandboxRecipe } from './bridge-sandbox-recipe.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';
@@ -140,11 +142,12 @@ export const judgeChange = ({ variant, files, scope }) => {
 };
 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) => {
+export const scopeOf = (variant, facts, deps = {}) => {
   const allowed = {};
   const set = (key, values) => {
     allowed[key] = (value) => values.some((entry) => equal(entry, value));
@@ -153,12 +156,13 @@ export const scopeOf = (variant, facts) => {
     const allow = [...UNIVERSAL_READONLY_ALLOWLIST];
     if (variant === 'kit-tools-tier') allow.push(...deriveKitToolsAllowlist({ projectDir: facts.root }));
     if (variant === 'bridge-tier') {
-      const deps = writerFacts(facts, {});
-      const placed = BRIDGE_REVIEW_WRAPPERS.filter(deps.findWrapper);
-      allow.push(...deriveBridgeTierAllowlist({ findWrapper: deps.findWrapper,
-        groundingAbsPath: join(facts.toolsDir, '..', KIT_GROUNDING_TOOL) }).allow);
-      set('sandbox.excludedCommands', placed);
-      set('sandbox.network.allowedDomains', bundledSandboxRecipe(placed, deps).hosts);
+      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') {
@@ -189,7 +193,7 @@ export const scopeOf = (variant, facts) => {
   return {
     admits: ({ path, key, change, value }) => {
       const correctFile = key.startsWith(`${SERVERS_KEY}.`) ? path === MCP_JSON_REL : path === SETTINGS_FILE;
-      const gains = key === 'hooks.PreToolUse' || key === ENABLED_KEY || key === CREDENTIALS;
+      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)
@@ -220,7 +224,7 @@ export const plannedChange = (variant, facts, deps = {}) => {
       const plan = writeVelocityProfile({ cwd: facts.root, dryRun: true,
         kitTools: variant === 'kit-tools-tier', bridgeTier: variant === 'bridge-tier' }, writerDeps);
       const before = plan.projectSettings.data ?? {};
-      const after = structuredClone(before);
+      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) {
@@ -229,6 +233,7 @@ export const plannedChange = (variant, facts, deps = {}) => {
         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);
@@ -272,7 +277,7 @@ export const plannedChange = (variant, facts, deps = {}) => {
 
 export const checkApply = (variant, facts, deps = {}) => {
   const plan = plannedChange(variant, facts, deps);
-  const scope = scopeOf(variant, facts);
+  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;
@@ -344,7 +349,7 @@ export const main = (argv, io = {}) => {
     platform: resolved.platform, claudeDir: args['claude-dir'] };
   let result;
   try {
-    result = checkApply(args.variant, facts);
+    result = checkApply(args.variant, facts, { detect: resolved.detect });
   } catch (error) {
     for (const line of error.lines ?? [error.message]) resolved.log(line);
     return 3;

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 flagless advisory's call in velocity-profile.mjs) 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 };
 };

package/tools/bridge-state-dirs.mjs

@@ -0,0 +1,94 @@
+// bridge-state-dirs.mjs — the one leaf that turns the bundled bridges' declared writable state dirs
+// (`writableDirs`) into `sandbox.filesystem.allowWrite` entries (contract: bridges/velocity-profile).
+// The bridge tier writes them, the advisor counts them, the danger check admits them, the autonomy
+// preview names them: one resolution, one home-relative spelling, one merge, so the four cannot drift.
+//
+// A LEAF: imports declared-paths.mjs and node:path only. No side effects on import. Dependency-free,
+// Node >= 22.
+
+import { dirname, relative, resolve } from 'node:path';
+import { dirCovers, isResolvableDeclaredEntry, resolveDeclaredDir } from './declared-paths.mjs';
+
+// 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). Anchored to the TARGET PROJECT ROOT,
+// matching what a wrapper invoked from the project root resolves.
+export const resolveWritableDir = (entry, { env, root }) => {
+  const value = entry.env == null ? '' : (env[entry.env] ?? '');
+  if (value === '') return entry.default;
+  if (value === '~' || value.startsWith('~/') || value.startsWith('/')) return value;
+  return resolve(root, value);
+};
+
+// The HOME-SYMBOLIC spelling: tilde forms stay symbolic, an absolute dir under the home (by path
+// segment, never a string prefix) folds back to `~/…`, anything outside the home stays absolute.
+export const homeRelative = (dir, home) => {
+  if (dir === '~') return '~';
+  if (dir.startsWith('~/')) return `~/${dir.slice(2)}`;
+  const homeAbs = resolve(home);
+  const abs = resolve(dir);
+  if (abs === homeAbs) return '~';
+  return dirCovers(homeAbs, abs) ? `~/${relative(homeAbs, abs)}` : abs;
+};
+
+const ancestorsOf = (dir) => {
+  const out = [];
+  for (let at = dirname(dir); at !== dir; dir = at, at = dirname(at)) out.push(at);
+  return out;
+};
+
+// A grant on `/`, on the home, or on an ancestor of the home or of the root would hand every
+// sandboxed command the user's whole tree — never a bridge's state dir. The override that produced
+// it is named, so the user knows which variable to fix.
+const dangerOf = (abs, { home, root }) => {
+  const homeAbs = resolve(home);
+  if (abs === '/') return 'the filesystem root';
+  if (abs === homeAbs) return 'the home directory';
+  if (ancestorsOf(homeAbs).includes(abs)) return 'an ancestor of the home directory';
+  if (ancestorsOf(resolve(root)).includes(abs)) return 'an ancestor of the project root';
+  return null;
+};
+
+export const stateDirsOf = (dirEntries, { env, root, home }) => {
+  const dirs = [];
+  for (const entry of dirEntries) {
+    const raw = resolveWritableDir(entry, { env, root });
+    const danger = dangerOf(resolveDeclaredDir(raw, { home, root }), { home, root });
+    if (danger !== null) {
+      const source = entry.env == null ? 'its declared default' : entry.env;
+      throw new Error(`writable state dir "${raw}" from ${source} resolves to ${danger} — refusing to grant it; point ${source} at the bridge's own state dir`);
+    }
+    const rendered = homeRelative(raw, home);
+    if (!dirs.includes(rendered)) dirs.push(rendered);
+  }
+  return dirs;
+};
+
+// The dirs no existing allowWrite entry covers (resolved both sides, containment by path segment).
+export const missingStateDirs = (dirs, allowWrite, { home, root }) => {
+  const existing = (Array.isArray(allowWrite) ? allowWrite : [])
+    .filter(isResolvableDeclaredEntry)
+    .map((entry) => resolveDeclaredDir(entry, { home, root }));
+  return dirs.filter((dir) => {
+    const abs = resolveDeclaredDir(dir, { home, root });
+    return !existing.some((container) => dirCovers(container, abs));
+  });
+};
+
+// The ONE writer of `sandbox.filesystem.allowWrite`: the other sandbox and filesystem sub-keys stay
+// where they are, each dir not already present appends once. Pure: returns a new object, and with
+// nothing to add returns the input unchanged (no sandbox key is created for nothing).
+export const mergeAllowWrite = (settings, dirs) => {
+  const base = settings ?? {};
+  const existing = Array.isArray(base.sandbox?.filesystem?.allowWrite) ? base.sandbox.filesystem.allowWrite : [];
+  const toAppend = [];
+  for (const dir of dirs) if (!existing.includes(dir) && !toAppend.includes(dir)) toAppend.push(dir);
+  if (toAppend.length === 0) return base;
+  return {
+    ...base,
+    sandbox: {
+      ...base.sandbox,
+      filesystem: { ...base.sandbox?.filesystem, allowWrite: [...existing, ...toAppend] },
+    },
+  };
+};

package/tools/bridge-wiring.mjs

@@ -0,0 +1,196 @@
+// bridge-wiring.mjs — the leaf that judges the project sandbox's coverage of ready bridges.
+// Contract: bridges/velocity-profile, part bridge-wiring. Dependency-free, Node >= 22.
+// No side effects on import.
+
+import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { bundledSandboxRecipe, usedBridges } from './bridge-sandbox-recipe.mjs';
+import { missingStateDirs, stateDirsOf } from './bridge-state-dirs.mjs';
+import { loadConfig } from './orchestration-config.mjs';
+import { BACKEND_PRIORITY } from './carriers.mjs';
+import { READY } from './detect-backends.mjs';
+
+export const HOST_HONORS_QUALIFIER = 'where the host honors the settings sandbox keys';
+export const WIRED = 'wired';
+export const UNWIRED = 'not wired';
+export const UNCHECKED = 'unchecked';
+export const WIRING_ROUTE = 'wire it on the chat yes of /agent-workflow-kit upgrade';
+export const WIRING_ROUTE_UNUSED = 'no slot uses it for review — once one does, the chat yes of /agent-workflow-kit upgrade wires it';
+export const SANDBOX_ENABLED_CONDITION = `enabled in the project settings — ready means wired ${HOST_HONORS_QUALIFIER}`;
+export const SANDBOX_NOT_ENABLED_CONDITION = 'not enabled in the project settings — ready means installed';
+
+const PROJECT_FILE = 'settings.json';
+const LOCAL_FILE = 'settings.local.json';
+const SETTINGS_DIR = '.claude';
+const UTF8 = 'utf8';
+const ABSENT = 'ENOENT';
+const NOT_REGULAR = 'not a regular file';
+const REVIEW = 'review';
+const COVERED = 'covered';
+const NOT_COVERED = 'not covered';
+const ENABLED = 'enabled';
+const SANDBOX = 'sandbox';
+const SURFACE_KEYS = Object.freeze(['excludedCommands', 'hosts', 'dirs']);
+
+const isPlainObject = (value) => value !== null && typeof value === 'object'
+  && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+
+const assertObject = (value, key) => {
+  if (!isPlainObject(value)) throw new Error(`${key} must be a plain JSON object`);
+  return value;
+};
+
+const sandboxOf = (data, file) => {
+  if (data === undefined) return undefined;
+  assertObject(data, file);
+  if (!Object.hasOwn(data, SANDBOX)) return undefined;
+  return assertObject(data.sandbox, `${file}: sandbox`);
+};
+
+export const sandboxEnabled = (projectData, localData) => {
+  const project = sandboxOf(projectData, PROJECT_FILE);
+  const local = sandboxOf(localData, LOCAL_FILE);
+  const useLocal = local !== undefined && Object.hasOwn(local, ENABLED);
+  const judged = useLocal ? local : project;
+  const file = useLocal ? LOCAL_FILE : PROJECT_FILE;
+  if (judged === undefined || !Object.hasOwn(judged, ENABLED)) return false;
+  if (typeof judged.enabled !== 'boolean') throw new Error(`${file}: enabled must be a boolean`);
+  return judged.enabled === true;
+};
+
+const readObjectKey = (object, key) => {
+  if (!Object.hasOwn(object, key)) return {};
+  return assertObject(object[key], key);
+};
+
+const readArrayKey = (object, key) => {
+  if (!Object.hasOwn(object, key)) return [];
+  if (!Array.isArray(object[key])) throw new Error(`${key} must be an array`);
+  return object[key];
+};
+
+export const sandboxSurfaceDelta = (recipe, sandbox, { home, root }) => {
+  const base = sandbox === undefined ? {} : assertObject(sandbox, SANDBOX);
+  const exclusions = readArrayKey(base, 'excludedCommands');
+  const network = readObjectKey(base, 'network');
+  const filesystem = readObjectKey(base, 'filesystem');
+  const hosts = readArrayKey(network, 'allowedDomains');
+  const allowWrite = readArrayKey(filesystem, 'allowWrite');
+  if (allowWrite.some((entry) => typeof entry !== 'string' || entry.trim().length === 0)) {
+    throw new Error('allowWrite entries must be non-blank strings');
+  }
+  return {
+    excludedCommands: recipe.excludedCommands.filter((entry) => !exclusions.includes(entry)),
+    hosts: recipe.hosts.filter((entry) => !hosts.includes(entry)),
+    dirs: missingStateDirs(recipe.dirs, allowWrite, { home, root }),
+  };
+};
+
+const emptyDelta = () => ({ excludedCommands: [], hosts: [], dirs: [] });
+const countDelta = (delta) => SURFACE_KEYS.reduce((total, key) => total + delta[key].length, 0);
+const unionDeltas = (deltas) => Object.fromEntries(SURFACE_KEYS.map((key) => [
+  key, [...new Set(deltas.flatMap((delta) => delta[key]))],
+]));
+
+// One non-blocking descriptor for the type check and the read: a FIFO swapped in at the path never blocks.
+const readRegular = (path) => {
+  const descriptor = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    if (!fstatSync(descriptor).isFile()) throw new Error(NOT_REGULAR);
+    return readFileSync(descriptor, UTF8);
+  } finally {
+    closeSync(descriptor);
+  }
+};
+
+const readSettings = (root, file) => {
+  const path = join(root, SETTINGS_DIR, file);
+  const raw = (() => {
+    try {
+      return readRegular(path);
+    } catch (error) {
+      if (error?.code === ABSENT) return undefined;
+      throw new Error(`${file}: ${error?.message ?? error}`);
+    }
+  })();
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${file}: ${error?.message ?? error}`);
+  }
+};
+
+const baseEntry = (bridge) => ({
+  bridge,
+  roles: [],
+  used: false,
+  state: WIRED,
+  review: COVERED,
+  missing: emptyDelta(),
+  count: 0,
+  reason: null,
+  route: null,
+  reviewRoute: null,
+});
+
+const judgeBridge = (bridge, used, sandbox, context, deps) => {
+  const roles = used.find((entry) => entry.bridge === bridge)?.roles ?? [];
+  const judgedRoles = roles.length === 0 ? [REVIEW] : roles;
+  const deltas = new Map([...new Set([...judgedRoles, REVIEW])].map((role) => {
+    const recipe = bundledSandboxRecipe([{ bridge, roles: [role] }], deps);
+    if (recipe.excludedCommands.length === 0) {
+      throw new Error(`bundled manifest ${join(bridge, 'capability.json')} missing or lacking roles.${role}.cmd`);
+    }
+    const dirs = stateDirsOf(recipe.dirEntries, context);
+    return [role, sandboxSurfaceDelta({ ...recipe, dirs }, sandbox, context)];
+  }));
+  const missing = unionDeltas(judgedRoles.map((role) => deltas.get(role)));
+  const count = countDelta(missing);
+  const isUsed = roles.length !== 0;
+  const reviewMissing = countDelta(deltas.get(REVIEW)) !== 0;
+  return {
+    ...baseEntry(bridge),
+    roles,
+    used: isUsed,
+    state: count === 0 ? WIRED : UNWIRED,
+    review: reviewMissing ? NOT_COVERED : COVERED,
+    missing,
+    count,
+    route: count === 0 ? null : (isUsed ? WIRING_ROUTE : WIRING_ROUTE_UNUSED),
+    reviewRoute: reviewMissing ? (roles.includes(REVIEW) ? WIRING_ROUTE : WIRING_ROUTE_UNUSED) : null,
+  };
+};
+
+export const composeBridgeWiring = ({ root, readiness }, deps = {}) => {
+  const ready = BACKEND_PRIORITY.filter((bridge) => readiness.some((row) => row.name === bridge && row.readiness === READY));
+  try {
+    const project = readSettings(root, PROJECT_FILE);
+    const local = readSettings(root, LOCAL_FILE);
+    if (!sandboxEnabled(project, local)) {
+      return {
+        enabled: false,
+        reason: null,
+        condition: SANDBOX_NOT_ENABLED_CONDITION,
+        bridges: ready.map(baseEntry),
+      };
+    }
+    if (deps.preflight) deps.preflight();
+    const config = (deps.loadConfig ?? loadConfig)(root).config;
+    const used = usedBridges(config, readiness);
+    const context = { root, env: deps.env ?? process.env, home: deps.home ?? homedir() };
+    const bridges = ready.map((bridge) => judgeBridge(bridge, used, project?.sandbox, context, deps));
+    return { enabled: true, reason: null, condition: SANDBOX_ENABLED_CONDITION, bridges };
+  } catch (error) {
+    const reason = String(error?.message ?? error).replace(/[\r\n]+/g, ' ');
+    return {
+      enabled: null,
+      reason,
+      condition: `${UNCHECKED} — ${reason}`,
+      bridges: ready.map((bridge) => ({
+        ...baseEntry(bridge), state: UNCHECKED, review: UNCHECKED, reason,
+      })),
+    };
+  }
+};

package/tools/manifest/schema.md

@@ -100,19 +100,21 @@ drift-guarded set-equal to this block by the bridge `bin/*.test.mjs` suites (hel
 `networkHosts` declares the hosts the backend CLI is **observed** to contact (synthetic examples:
 `*.api.backend.example`, `accounts.backend.example`; the real observed lists live in each bridge's
 `capability.json`) — the **single source** of the hosts `velocity-profile --bridge-tier` seeds
-into the project's `sandbox.network.allowedDomains` for every placed bridge, and of a hand-applied
-session sandbox allowlist. Rules:
+into the project's `sandbox.network.allowedDomains` for every used bridge. Rules:
 
 - Each entry is a bare dotted hostname or a `*.family` wildcard — never a scheme/path/port.
-  Entries must be unique. A malformed list **fails** `--strict` (the entries are pasted verbatim
-  into allowlist lines by the Recommendations advisor).
-- **The `--bridge-tier` seed is the primary lane** (AD-172): beside the wrappers' exclusion it
-  merges the placed bridges' hosts into the project's `sandbox.network.allowedDomains`, so a
-  settings-native harness that drops the exclusion still admits them; that pre-allow widens egress
-  for **every** sandboxed command, which the tier's consent states. The **hand-apply** fallback
-  stays for a harness-managed sandbox that ignores the settings keys.
+  Entries must be unique. A malformed list **fails** `--strict` (the tier writes the entries into
+  `sandbox.network.allowedDomains` and the Recommendations advisor renders them on its
+  `bridge-tier` item's `recipe:` line).
+- **The `--bridge-tier` seed is the primary lane** (AD-172): for every used bridge it merges
+  hosts into the project's `sandbox.network.allowedDomains` beside the wrapper's `<wrapper> *`
+  exclusion (`codex-exec *` for the execution wrapper). A settings-native harness that drops the
+  exclusion still admits them; that pre-allow widens egress
+  for **every** sandboxed command, which the tier's consent states. A harness-managed sandbox
+  that ignores the settings keys keeps the harness's own controls — its scoped rules, a session
+  allowance, its consent at the point of action — and the kit writes no shape for it.
 - Observed-minimal, honestly incomplete: a blocked host names itself at run time — extend the
-  hand-applied list by hand; the manifest list records what was actually observed.
+  manifest list where it was observed; the list records what was actually observed.
 
 ## Writable dirs (REC-UX-REWORK, D6)
 
@@ -123,8 +125,8 @@ declared path is only the **default under no override**. Rules:
 
 - Each entry: `env` is `null` or an **UPPER_SNAKE_CASE env-var name**; `default` is a
   **`~/`-anchored or absolute POSIX path** — no globs, no trailing slash, no `..` traversal.
-  Defaults must be unique. A malformed list **fails** `--strict` (the resolved dir is rendered
-  into a hand-applied recipe line by the Recommendations advisor).
+  Defaults must be unique. A malformed list **fails** `--strict` (the resolved dir is written into
+  `sandbox.filesystem.allowWrite` and rendered on the Recommendations advisor's one-line `recipe:` line).
 - **Resolution is the advisor's, at run time, mirroring the wrapper's byte-semantics:** a
   NON-EMPTY env value wins (an EMPTY env value ≡ unset — the `${VAR:-default}` form); the
   wrapper's exact case-arms apply — `~`, `~/…` and absolute forms ride as-given, EVERY other
@@ -132,9 +134,10 @@ declared path is only the **default under no override**. Rules:
   relative path. The advisor anchors those to the **target project root** (its pinned `--cwd`),
   matching what a wrapper invoked from the project root resolves — the documented dispatch form
   (the wrapper itself anchors to its invocation `$PWD`); else the `default` applies.
-- Unlike `networkHosts`, this is a **documentation source** only: the kit never seeds
-  `sandbox.filesystem.allowWrite` or any other filesystem allowance — the entries feed the
-  sandbox-lane discoverability item (session/host sandbox config is hand-applied territory).
+- **The `--bridge-tier` seeds every used bridge's state dirs**, home-relative under the home
+  (absolute outside it), into `sandbox.filesystem.allowWrite` beside the wrapper's `<wrapper> *`
+  exclusion (`codex-exec *` for the execution wrapper) — the advisor's `bridge-tier` item counts
+  and names each missing dir.
 
 ## Mode catalog (BRIDGE-MODES-CATALOG)