@sabaiway/agent-workflow-kit 14.23.0 → 14.25.0

package/references/modes/velocity.md

@@ -50,7 +50,7 @@ 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 — BOTH surfaces: `permissions.allow` prefix rules AND 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). Both 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 kit **never seeds** `sandbox.network.allowedDomains` or `sandbox.filesystem.allowWrite` (bridge council 2026-07-11, both backends concur): a network pre-allow widens egress for EVERY sandboxed command, and a write allowance on CLI state dirs (`~/.codex`, `~/.gemini/…`) would make credential dirs writable to every sandboxed command. 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 kit still never seeds the security keys — those stay hand-apply), 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 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):
 
 - `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`

package/tools/ack-write.mjs

@@ -4,7 +4,7 @@
 // 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
-// network/filesystem allowances.
+// filesystem allowances, and allowedDomains only through velocity-profile --bridge-tier.
 //
 // 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

package/tools/bridge-sandbox-recipe.mjs

@@ -0,0 +1,40 @@
+// 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.
+//
+// Dependency-free, Node >= 22. No side effects on import.
+
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_BUNDLE_ROOT } from './bridge-settings-read.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) => {
+  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 none. The throw reaches the caller: a stated skip
+    // in the advisor, a STOP with zero writes in the bridge tier.
+    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 };
+};

package/tools/init-preflight.mjs

@@ -0,0 +1,92 @@
+import { closeSync, constants, lstatSync, openSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const AGENT_SESSION_MARKERS = Object.freeze([
+  'CLAUDECODE',
+  'CLAUDE_CODE_SESSION_ID',
+  'CLAUDE_CODE_ENTRYPOINT',
+  'SANDBOX_RUNTIME',
+]);
+
+const OWNER_WRITE_BIT = 0o200;
+const PROBE_FLAGS = constants.O_WRONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+const WRITE_REFUSAL_CODES = new Set(['EROFS', 'EPERM', 'EACCES']);
+
+const throwPathError = (path, error) => {
+  throw Object.assign(new Error(`${path}: ${error?.code ?? ''} ${error?.message ?? String(error)}`, {
+    cause: error,
+  }), { code: error?.code });
+};
+
+const readStat = (path, io) => {
+  try {
+    return io.lstat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT' || error?.code === 'ENOTDIR') return null;
+    throwPathError(path, error);
+  }
+};
+
+const openProbe = (path, io) => {
+  try {
+    return { descriptor: io.openSync(path, PROBE_FLAGS), cause: null };
+  } catch (error) {
+    if (WRITE_REFUSAL_CODES.has(error?.code)) {
+      return { cause: `${path}: a write-open answered ${error.code}` };
+    }
+    throwPathError(path, error);
+  }
+};
+
+const probePath = (path, io) => {
+  const stat = readStat(path, io);
+  if (stat === null) return null;
+  if (stat.isCharacterDevice() || stat.isBlockDevice()) {
+    return `${path}: a device-node mask`;
+  }
+  const canProbe = stat.isFile()
+    && (stat.mode & OWNER_WRITE_BIT) !== 0
+    && typeof io.geteuid === 'function'
+    && stat.uid === io.geteuid();
+  if (!canProbe) return null;
+  const opened = openProbe(path, io);
+  if (opened.cause !== null) return opened.cause;
+  try {
+    return null;
+  } finally {
+    try {
+      io.closeSync(opened.descriptor);
+    } catch (error) {
+      throwPathError(path, error);
+    }
+  }
+};
+
+export const preflightInit = ({ root = null, home, env = process.env, io = {} }) => {
+  for (const marker of AGENT_SESSION_MARKERS) {
+    if (typeof env[marker] === 'string' && env[marker].length > 0) {
+      return { ok: false, cause: `marker ${marker} is set` };
+    }
+  }
+  const probes = {
+    lstat: lstatSync,
+    openSync,
+    closeSync,
+    geteuid: process.geteuid,
+    ...io,
+  };
+  const paths = [join(home, '.claude/settings.json')];
+  if (root !== null) {
+    paths.push(
+      join(root, '.claude/settings.json'),
+      join(root, '.claude/settings.local.json'),
+      join(root, '.mcp.json'),
+      join(root, '.git/config'),
+    );
+  }
+  for (const path of paths) {
+    const cause = probePath(path, probes);
+    if (cause !== null) return { ok: false, cause };
+  }
+  return { ok: true, cause: null };
+};

package/tools/init-project.mjs

@@ -0,0 +1,400 @@
+import { closeSync, lstatSync, openSync, readFileSync, readdirSync, readlinkSync, statSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { resolveGitHooksPath } from './commit-guard.mjs';
+import { dirCovers } from './declared-paths.mjs';
+import { isDirectRun } from './direct-run.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
+import { preflightInit } from './init-preflight.mjs';
+import { buildRecommendations, hostFacts } from './recommendations.mjs';
+import { compareSemver } from './semver-lite.mjs';
+import { EXPECTED_WORKFLOW_VERSION } from './velocity-profile.mjs';
+import { LANE_CONSOLE, VARIANT_LANES, consoleArgv, isProtectedPath, laneOf, routeLine, writesOf } from './write-lanes.mjs';
+
+const INSIDE_LINE = 'you are inside an agent; run this in your own terminal';
+const APPLY_PROMPT = 'apply? y/N: ';
+const RUN_NONE = 'y applies every preview above (a sudo install asks once more on its own line); run none of their commands yourself';
+const RESTART_LINE = 'restart the agent from this folder: init changed its configuration';
+const SETTINGS = ['.claude/settings.json', '.claude/settings.local.json', '.mcp.json', '.git/config'];
+const FILE_DIRS = ['.claude/agents', '.claude/hooks'];
+// The record key whose state is the sorted *.json names of its directory, so a created file is a change.
+const JSON_NAMES = '*.json';
+const DANGLING = new Set(['ENOENT', 'ENOTDIR', 'ELOOP']);
+const INSTALL_VARIANT = 'sandbox-provision.installable';
+const DEFAULT_IO = { lstat: lstatSync, stat: statSync, readlink: readlinkSync, readFile: readFileSync, readdir: readdirSync,
+  openSync, closeSync, geteuid: process.geteuid };
+const isYes = (answer) => answer === 'y' || answer === 'Y';
+
+const readStat = (path, io) => {
+  try {
+    return io.lstat(path);
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null;
+    throw error;
+  }
+};
+
+export const findProject = ({ cwd, lstat = lstatSync }) => {
+  const candidates = [];
+  const visit = (root) => {
+    const io = { lstat };
+    if (readStat(join(root, 'docs/ai'), io)?.isDirectory()) {
+      const shape = readStat(join(root, 'docs/ai/.workflow-version'), io) ? 'stamped' : 'pre-versioned';
+      candidates.push({ root, shape });
+    }
+    const parent = dirname(root);
+    if (!readStat(join(root, '.git'), io) && parent !== root) visit(parent);
+  };
+  visit(resolve(cwd));
+  return { candidates };
+};
+
+const readEntries = (dir, io) => readStat(dir, io)?.isDirectory() ? io.readdir(dir).sort() : [];
+const collectPaths = ({ root, home, hooksDir }, io) => {
+  const paths = [join(home, '.claude/settings.json')];
+  if (root === null) return paths;
+  const docs = join(root, 'docs/ai');
+  paths.push(...SETTINGS.map((path) => join(root, path)), join(docs, '.workflow-version'), join(docs, JSON_NAMES));
+  for (const dir of [...FILE_DIRS.map((path) => join(root, path)), hooksDir]) {
+    paths.push(dir, ...readEntries(dir, io).map((name) => join(dir, name)));
+  }
+  paths.push(...readEntries(docs, io).filter((name) => name.endsWith('.json')).map((name) => join(docs, name)));
+  return paths;
+};
+
+const fileState = (path, io) => `file:${Buffer.from(io.readFile(path)).toString('hex')}`;
+const otherState = (stat) => `other:${stat.mode}:${stat.rdev}`;
+const entryState = (path, io) => {
+  const stat = io.lstat(path);
+  if (stat.isDirectory()) return 'directory';
+  if (stat.isSymbolicLink()) return `link:${io.readlink(path)}`;
+  return stat.isFile() ? fileState(path, io) : otherState(stat);
+};
+// A directory reads as its sorted entries with each entry's own state, one level deep, so a changed file in it is a change.
+const statState = (path, stat, io) => {
+  if (stat.isDirectory()) return `directory:${JSON.stringify(io.readdir(path).sort().map((name) => [name, entryState(join(path, name), io)]))}`;
+  return stat.isFile() ? fileState(path, io) : otherState(stat);
+};
+const followedState = (path, io) => {
+  try {
+    return statState(path, io.stat(path), io);
+  } catch (error) {
+    if (DANGLING.has(error.code)) return 'absent';
+    throw error;
+  }
+};
+const readState = (path, io) => {
+  if (basename(path) === JSON_NAMES) {
+    const names = readStat(dirname(path), io)?.isDirectory() ? io.readdir(dirname(path)).filter((name) => name.endsWith('.json')) : null;
+    return names === null ? 'absent' : `names:${JSON.stringify(names.sort())}`;
+  }
+  const stat = readStat(path, io);
+  if (stat === null) return 'absent';
+  if (stat.isSymbolicLink()) return `link:${io.readlink(path)}:${followedState(path, io)}`;
+  return statState(path, stat, io);
+};
+const stateOf = (path, io) => {
+  try {
+    return readState(path, io);
+  } catch (error) {
+    throw new Error(`${path} could not be read: ${error.code ?? error.message}`);
+  }
+};
+const recordPaths = (paths, io) => new Map([...new Set(paths)].map((path) => [path, stateOf(path, io)]));
+const findChanged = (record, io) => [...record].find(([path, state]) => {
+  try {
+    return readState(path, io) !== state;
+  } catch {
+    return true;
+  }
+})?.[0];
+// After an apply a path that cannot be read is recorded as such, so the next comparison stops the batch on it.
+const refreshState = (path, io) => {
+  try {
+    return readState(path, io);
+  } catch (error) {
+    return `unreadable:${error.code ?? error.message}`;
+  }
+};
+const DIRECTORY = 'directory:';
+const entriesOf = (state) => (state === 'absent' ? [] : JSON.parse(state.slice(DIRECTORY.length)));
+// A recorded parent moves only by the written entry, so an entry created or removed beside it still stops the batch.
+const refreshParent = (record, path, io) => {
+  const [parent, name, current] = [dirname(path), basename(path), refreshState(dirname(path), io)];
+  const recorded = record.get(parent);
+  if (!(recorded === 'absent' || recorded.startsWith(DIRECTORY)) || !current.startsWith(DIRECTORY)) return;
+  const merged = [...entriesOf(recorded).filter(([entry]) => entry !== name), ...entriesOf(current).filter(([entry]) => entry === name)];
+  record.set(parent, DIRECTORY + JSON.stringify(merged.sort(([a], [b]) => (a < b ? -1 : 1))));
+};
+const refreshWrites = (record, paths, io) => {
+  for (const path of paths) {
+    record.set(path, refreshState(path, io));
+    if (record.has(dirname(path))) refreshParent(record, path, io);
+    if (readStat(path, io)?.isDirectory()) {
+      for (const watched of record.keys()) {
+        if (watched.startsWith(path + sep)) record.set(watched, refreshState(watched, io));
+      }
+      for (const child of readEntries(path, io).map((name) => join(path, name))) record.set(child, refreshState(child, io));
+    }
+  }
+};
+
+const findMasks = (paths, facts, io, print) => {
+  const masks = new Set();
+  const root = facts.root ?? facts.cwd;
+  for (const path of new Set(paths)) {
+    if (!isProtectedPath(path, { root, home: facts.home, hooksDir: join(root, '.git/hooks') })) continue;
+    const stat = readStat(path, io);
+    if (!stat?.isFile() || stat.size !== 0 || (stat.mode & 0o222) !== 0) continue;
+    masks.add(path);
+    print(`${path}: an empty read-only file — a running agent command's mask (run init again once it ends) or litter a sandbox left (remove it, then run init again)`);
+  }
+  return masks;
+};
+
+const launch = async (context, argv, stdio) => {
+  try {
+    const result = await context.spawn(argv, { cwd: context.facts.root ?? context.cwd, env: context.spawnEnv, stdio });
+    if (!result || typeof result !== 'object') return { status: null, stdout: '', stderr: 'empty answer', valid: false };
+    return {
+      status: result.status ?? null,
+      stdout: String(result.stdout ?? ''),
+      stderr: String(result.stderr ?? result.error?.message ?? result.signal ?? ''),
+      valid: typeof result.status === 'number' && !result.error && !result.signal,
+    };
+  } catch (error) {
+    return { status: null, stdout: '', stderr: String(error.code ?? error.message ?? error), valid: false };
+  }
+};
+
+// Outside a project only the host-scoped variants reach the queue: an apply-only one or one judged over a claude dir.
+const reachesQueue = (variant, facts) => {
+  if (facts.root !== null) return true;
+  const argv = consoleArgv(variant, facts);
+  return Boolean(argv) && (argv.preview === null || argv.preview.includes('--claude-dir'));
+};
+const isMasked = (variant, context) => (writesOf(variant, context.facts) ?? [])
+  .some((write) => [...context.masks].some((mask) => dirCovers(write, mask)));
+
+// context.items keeps the console items of the advisor's latest return, before the queue's filters.
+const getQueue = async (context) => {
+  const { items } = await context.recommend(context.facts.root, { keySet: context.keySet });
+  context.items = items.filter(({ variant }) => laneOf(variant) === LANE_CONSOLE);
+  return context.items.filter(({ variant }) => reachesQueue(variant, context.facts) && !isMasked(variant, context));
+};
+
+const printNotPending = (context) => {
+  const plain = routeLine('velocity-core');
+  const variants = Object.keys(VARIANT_LANES).filter((variant) => laneOf(variant) === LANE_CONSOLE && routeLine(variant)?.length > plain.length);
+  const keys = new Set();
+  for (const variant of variants) {
+    const key = variant.split('.')[0];
+    if (keys.has(key)) continue;
+    keys.add(key);
+    if (!reachesQueue(variant, context.facts) || context.items.some((item) => item.key === key)) continue;
+    const preview = consoleArgv(variant, context.facts)?.preview;
+    const index = preview?.indexOf('--claude-dir') ?? -1;
+    const judged = index < 0 ? '' : ` (judged ${preview[index + 1]})`;
+    context.print(`not pending in this console: ${key}${judged}`);
+  }
+};
+
+const printNote = (context, key) => {
+  const lines = String(context.io.readFile(join(context.facts.toolsDir, '../references/modes/recommendations.md'), 'utf8')).split('\n');
+  const start = lines.findIndex((line) => line.startsWith(`- \`${key}\` — `));
+  if (start < 0) return;
+  const end = lines.findIndex((line, index) => index > start && !line.startsWith(' ') && !line.startsWith('\t'));
+  for (const line of lines.slice(start, end < 0 ? lines.length : end)) context.print(line);
+};
+
+const previewQueue = async (context, queue) => {
+  const batch = [];
+  for (const item of queue) {
+    const argv = consoleArgv(item.variant, context.facts);
+    if (!argv?.preview) continue;
+    context.print(`preview: ${item.variant}`);
+    const result = await launch(context, argv.preview, 'pipe');
+    const success = result.valid && (result.status === 0 || (result.status === 3 && result.stdout.includes('status=missing-binaries')));
+    if (!success) {
+      context.print(`preview refused (exit ${result.status}): ${item.variant}`);
+      if (result.stdout) context.print(result.stdout);
+      if (result.stderr) context.print(result.stderr);
+      continue;
+    }
+    context.print(result.stdout);
+    const tuple = result.stdout.match(/--apply\s+(\S+)/)?.[1];
+    const facts = { ...context.facts, tuple };
+    batch.push({ ...item, applyArgv: consoleArgv(item.variant, facts).apply, writes: writesOf(item.variant, facts) });
+    printNote(context, item.key);
+  }
+  for (const item of queue.filter(({ variant }) => consoleArgv(variant, context.facts) === null)) {
+    context.print(`listed, not applied here: ${item.variant} — ${item.what}`);
+  }
+  return batch;
+};
+
+const isConfiguration = (path, root) => root !== null && (
+  SETTINGS.slice(0, 3).some((rel) => path === join(root, rel))
+  || ['.claude/agents', '.claude/hooks'].some((rel) => path === join(root, rel) || path.startsWith(join(root, rel) + sep))
+);
+
+// The record is the state the first preview reads: taken before any preview, compared before each apply.
+const takeRecord = (context, queue) => {
+  const previewable = queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview);
+  if (previewable.length === 0) return new Map();
+  const paths = [...collectPaths(context.facts, context.io), ...previewable.flatMap(({ variant }) => writesOf(variant, context.facts))];
+  try {
+    return recordPaths(paths, context.io);
+  } catch (error) {
+    for (const item of previewable) context.print(`not applied: ${item.variant} — ${error.message}`);
+    return null;
+  }
+};
+
+const runPass = async (context, queue) => {
+  const record = takeRecord(context, queue);
+  if (record === null) return { code: 1, successes: 0, variants: [] };
+  const batch = await previewQueue(context, queue);
+  if (batch.length === 0) return { code: 0, successes: 0, variants: [] };
+  const before = new Map(record);
+  const outcome = { code: 0, successes: 0, variants: batch.map((item) => item.variant) };
+  context.print(RUN_NONE);
+  if (!isYes(await context.terminal.ask(APPLY_PROMPT))) return outcome;
+  for (const [index, item] of batch.entries()) {
+    if (item.variant === INSTALL_VARIANT && !isYes(await context.terminal.ask('the sandbox install may ask for your sudo password: y runs it, Enter skips: '))) continue;
+    const changed = findChanged(record, context.io);
+    if (changed) {
+      for (const later of batch.slice(index)) context.print(`not applied: ${later.variant} — ${changed} changed outside this batch`);
+      outcome.code = 1;
+      break;
+    }
+    const result = await launch(context, item.applyArgv, ['inherit', 'pipe', 'inherit']);
+    if (result.stdout) context.print(result.stdout);
+    const success = result.valid && (result.status === 0 || (result.status === 5 && result.stdout.includes('install completed')));
+    if (!success) {
+      context.print(`apply failed (exit ${result.status}): ${item.variant}`);
+      if (result.stderr) context.print(result.stderr);
+      for (const later of batch.slice(index + 1)) context.print(`not applied: ${later.variant} — an earlier apply failed`);
+      outcome.code = 1;
+      break;
+    }
+    outcome.successes += 1;
+    refreshWrites(record, item.writes, context.io);
+  }
+  if (outcome.successes > 0) {
+    const afterPaths = [...collectPaths(context.facts, context.io), ...record.keys()];
+    context.restart ||= afterPaths.some((path) => isConfiguration(path, context.facts.root)
+      && refreshState(path, context.io) !== (before.get(path) ?? 'absent'));
+  }
+  return outcome;
+};
+
+const selectRoot = async (context) => {
+  const { candidates } = findProject({ cwd: context.cwd, lstat: context.io.lstat });
+  if (candidates.length === 0) {
+    context.print("no agent-workflow project here — the project items apply when init runs from that project's folder");
+    return { root: null };
+  }
+  if (candidates.length === 1) return candidates[0];
+  candidates.forEach(({ root }, index) => context.print(`  ${index + 1}. ${root}`));
+  const answer = await context.terminal.ask(`which project? 1-${candidates.length}, Enter skips: `);
+  return candidates.find((_, index) => String(index + 1) === answer) ?? null;
+};
+
+const gateStamp = (candidate, context) => {
+  if (candidate.root === null) return null;
+  const stamp = (() => {
+    try {
+      return String(context.io.readFile(join(candidate.root, 'docs/ai/.workflow-version'), 'utf8')).trim();
+    } catch {
+      return null;
+    }
+  })();
+  if (candidate.shape === 'stamped' && stamp === EXPECTED_WORKFLOW_VERSION) return candidate.root;
+  if (compareSemver(stamp, EXPECTED_WORKFLOW_VERSION) === 1) {
+    context.print(`this project's stamp ${stamp} is ahead of this kit's lineage ${EXPECTED_WORKFLOW_VERSION} — update the kit, then init again`);
+  } else {
+    context.print('run /agent-workflow-kit upgrade, then init again');
+  }
+  return null;
+};
+
+export const runInitProject = async (deps) => {
+  const { terminal } = deps;
+  if (terminal.isTTY !== true) {
+    terminal.print("project step skipped: no terminal — run init in a console from the project's folder");
+    return { code: 0 };
+  }
+  const io = { ...DEFAULT_IO, ...deps.io };
+  const print = (line) => terminal.print(line);
+  if (!preflightInit({ ...deps, root: null, io }).ok) {
+    print(INSIDE_LINE);
+    return { code: 0 };
+  }
+  const spawnEnv = { ...deps.env };
+  delete spawnEnv.GIT_DIR;
+  delete spawnEnv.GIT_WORK_TREE;
+  const context = { ...deps, io, print, spawnEnv, masks: new Set(), keySet: false, restart: false };
+  const candidate = await selectRoot(context);
+  if (candidate === null) return { code: 0 };
+  if (!preflightInit({ ...deps, root: candidate.root, io }).ok) {
+    print(INSIDE_LINE);
+    return { code: 0 };
+  }
+  const root = gateStamp(candidate, context);
+  // The hooks dir git itself reports (a linked worktree's or core.hooksPath), as the advisor reads it.
+  const hooksDir = root === null ? null : (deps.gitHooksPath ?? resolveGitHooksPath)(root) ?? join(root, '.git/hooks');
+  context.facts = { toolsDir: deps.toolsDir, root, env: deps.env, home: deps.home, platform: deps.platform, tuple: undefined, hooksDir };
+  context.recommend ??= (root, facts) => buildRecommendations({ cwd: root ?? deps.cwd,
+    deps: { ...io, env: deps.env, getenv: deps.env, home: deps.home, platform: deps.platform,
+      jevHost: { ...hostFacts(), home: deps.home, platform: deps.platform }, ...facts } });
+  const queue = await getQueue(context);
+  const maskPaths = [...collectPaths(context.facts, io), ...queue.flatMap(({ variant }) => writesOf(variant, context.facts) ?? [])];
+  context.masks = findMasks(maskPaths, { ...context.facts, cwd: deps.cwd }, io, print);
+  const state = { queue: queue.filter(({ variant }) => !isMasked(variant, context)) };
+  for (const item of state.queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview === null)) {
+    print(item.what);
+    print(`it writes: ${writesOf(item.variant, context.facts).join(', ')}`);
+    printNote(context, item.key);
+    if (!isYes(await terminal.ask('y runs its command on this terminal, Enter skips: '))) continue;
+    const result = await launch(context, consoleArgv(item.variant, context.facts).apply, 'inherit');
+    if (result.valid && result.status === 0) {
+      context.keySet = true;
+      state.queue = await getQueue(context);
+    }
+  }
+  state.queue = state.queue.filter(({ variant }) => consoleArgv(variant, context.facts)?.preview !== null);
+  printNotPending(context);
+  const first = await runPass(context, state.queue);
+  const outcome = { code: first.code };
+  if (first.code === 0 && first.successes > 0) {
+    const next = (await getQueue(context)).filter(({ variant }) => !first.variants.includes(variant) && consoleArgv(variant, context.facts)?.preview);
+    outcome.code = (await runPass(context, next)).code;
+  }
+  if (context.restart) print(RESTART_LINE);
+  return outcome;
+};
+
+export const main = async (argv = process.argv.slice(2), deps = {}) => {
+  if (argv.length > 0) {
+    (deps.errlog ?? console.error)('Usage: node init-project.mjs');
+    return 2;
+  }
+  const readline = deps.terminal ? null : createInterface({ input: process.stdin, output: process.stdout });
+  const terminal = deps.terminal ?? { isTTY: process.stdin.isTTY === true && process.stdout.isTTY === true,
+    ask: (prompt) => readline.question(prompt), print: (line) => console.log(line) };
+  try {
+    const result = await runInitProject({ cwd: process.cwd(), env: process.env, home: homedir(), platform: process.platform,
+      toolsDir: dirname(fileURLToPath(import.meta.url)), terminal,
+      spawn: (args, options) => spawnSync(process.execPath, args.slice(1), { ...options, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER }),
+      ...deps });
+    return result.code;
+  } finally {
+    readline?.close();
+  }
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = await main();

package/tools/manifest/schema.md

@@ -99,18 +99,18 @@ 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 documentation
-source** for a hand-applied sandbox/network allowlist (session sandbox config, or a hand-pasted
-`sandbox.network.allowedDomains` entry). Rules:
+`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:
 
 - 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 kit never seeds these into settings** (bridge council 2026-07-11, both backends concur):
-  a network pre-allow widens egress for **every** sandboxed command, so running the wrappers
-  **outside** the sandbox (`sandbox.excludedCommands`, the `--bridge-tier` wiring) stays the
-  primary lane; the hosts list exists for the **hand-apply** fallback under a sandbox that does
-  not honour the exclusion (harness-managed, or a settings-native harness that drops it).
+- **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.
 - 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.
 
@@ -132,7 +132,7 @@ 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.
-- Like `networkHosts`, this is a **documentation source**: the kit never seeds
+- 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).
 

package/tools/manifest/validate.mjs

@@ -638,10 +638,10 @@ export const validateManifest = (skillDir) => {
   }
 
   // `networkHosts` (AD-044 Plan 4, consult-locked): the backend CLI's OBSERVED egress host
-  // families — a DOCUMENTATION source for hand-applied sandbox/network allowlists. The kit never
-  // seeds these into settings (exclusion stays primary; a network pre-allow widens egress for
-  // EVERY sandboxed command), but a malformed list FAILS --strict like `settings`: the
-  // Recommendations advisor renders it verbatim, so a bad entry would corrupt a pasted line.
+  // families. `velocity-profile --bridge-tier` seeds them into sandbox.network.allowedDomains for
+  // placed bridges (AD-172; the pre-allow widens egress for EVERY sandboxed command, stated at that
+  // consent), and a malformed list FAILS --strict like `settings`: the tier writes it and the
+  // Recommendations advisor renders it verbatim, so a bad entry would corrupt a seeded line.
   const networkHosts = manifest.networkHosts;
   if (networkHosts != null) {
     if (!Array.isArray(networkHosts) || networkHosts.length === 0) {
@@ -661,7 +661,7 @@ export const validateManifest = (skillDir) => {
 
   // `writableDirs` (REC-UX-REWORK, D6): the backend CLI's writable state-dir declarations —
   // {env, default} entries the Recommendations advisor RESOLVES at run time (a NON-EMPTY env
-  // value wins, else the default) and renders into the sandbox-lane recipe. Like `networkHosts`
+  // value wins, else the default) and renders into the sandbox-lane recipe. Unlike `networkHosts`
   // this is a DOCUMENTATION source (the kit never seeds filesystem allowances), and a malformed
   // list FAILS --strict for the same reason: the resolved dir is rendered into a hand-applied line.
   const writableDirs = manifest.writableDirs;