@sabaiway/agent-workflow-kit 14.33.0 → 14.35.0

package/tools/cheap-agents-read.mjs

@@ -135,6 +135,18 @@ export const executorTemplate = (posture, deps = {}) => {
   return { name: EXECUTOR_VEHICLE, content: deriveExecutorBody(bundled.content, posture), rederive: true };
 };
 
+// The executor ensure's cell 6: a regular placed executor whose bytes differ from the body derived from
+// the settings; the placed file's read failure throws.
+export const executorBodyDiffers = (projectDir, deps = {}) => {
+  const fs = readFsDeps(deps);
+  const abs = join(projectDir, EXECUTOR_VEHICLE_REL);
+  const stat = lstatNoFollow(abs, fs);
+  if (stat === null || stat.isSymbolicLink() || !stat.isFile()) return false;
+  const { posture } = readExecutorPosture(projectDir, deps);
+  if (posture === null) return false;
+  return fs.readFile(abs, UTF8) !== executorTemplate(posture, deps).content;
+};
+
 const READ_ONLY_TOOLS = new Set(['Read', 'Grep', 'Glob']);
 
 // The YAML subset a vehicle's frontmatter is read with: a bare scalar, a single- or double-quoted

package/tools/commands.mjs

@@ -194,7 +194,7 @@ const CATALOG = [
     invocation: invocationOf('mcp'),
     group: 'Configure',
     kind: GUARDED,
-    oneLine: 'Register the kit’s read-only MCP server in this project, so path questions and literal searches run as typed tool calls instead of shell command strings — previews the exact entry it would declare, writes only on your yes, and where a sandbox hides the file it hands you the text to paste instead.',
+    oneLine: 'Register the kit’s read-only MCP server in this project, so path questions and literal searches run as typed tool calls instead of shell command strings — previews the exact entry it would declare, writes only on your yes, and where a sandbox hides the file it writes nothing and names the advisor’s mcp-channel item, which applies it by the consent route.',
   },
   {
     key: 'recipes',

package/tools/commit-guard.mjs

@@ -41,9 +41,7 @@
 // boundary). Read-only; dependency-free; Node >= 22. No side effects on import.
 
 import { readFileSync, lstatSync } from 'node:fs';
-import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { isDirectRun } from './direct-run.mjs';
 import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
@@ -54,25 +52,14 @@ import {
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 import { computeFlowDecision } from './flow-check.mjs';
-import { GIT_MAX_BUFFER, resolveGitLocation } from './git-env.mjs';
+import { resolveGitLocation } from './git-env.mjs';
 import { escapeForDisplay } from './repo-lex.mjs';
 
 const usageFail = (message) => Object.assign(new Error(`[agent-workflow-kit] ${message}`), { exitCode: 2 });
 const sha = (text) => createHash('sha256').update(text).digest('hex');
 
-const gitLine = (args, cwd) => {
-  const r = spawnSync('git', args, { cwd, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
-  if (r.error || r.status !== 0) return null;
-  return r.stdout.toString('utf8').replace(/\r?\n$/, '');
-};
-
-// resolveGitHooksPath(projectDir) → the ABSOLUTE hooks dir git itself reports (a linked worktree
-// answers with ITS OWN hooks path — never a hardcoded `.git/hooks`), or null outside a git tree.
-// The one home consumers (the recommendations guard-install probe) read instead of re-deriving it.
-export const resolveGitHooksPath = (projectDir) => {
-  const line = gitLine(['rev-parse', '--git-path', 'hooks'], projectDir);
-  return line == null ? null : resolve(projectDir, line);
-};
+// The hooks-path question and the pre-commit reader live in git-hooks.mjs, their writer's home.
+export { resolveGitHooksPath, readPreCommitState, canonicalGuardLineRe, INSTALLER_MARKER_RE } from './git-hooks.mjs';
 
 // How many offending paths the index-lag refusal names before it states a remainder count: enough
 // to act on, bounded so a wide lag cannot bury a pre-commit hook's output.

package/tools/ensure-configs.mjs

@@ -5,7 +5,7 @@
 //   gates          docs/ai/gates.json          seed-if-missing (an existing declaration is authored content)
 //   autonomy       docs/ai/autonomy.json       seed-if-missing (same)
 //   vehicles       docs/ai/vehicles.json       seed-if-missing (same)
-//   executor       .claude/agents/executor.md  re-derived from docs/ai/vehicles.json when its bytes differ; absent stays absent
+//   executor       .claude/agents/executor.md  judged against docs/ai/vehicles.json, never written: a differing body is pending
 //   scripts        scripts/<ADR enforcement>   seed-if-missing, ADR-layout detect FIRST
 //   specs          scripts/<spec layer>        reader + checker pairs seeded when absent, refreshed only on
 //                  + docs/ai/specs/index.md    a shipped prior body, an edited one replaced only on the
@@ -80,16 +80,16 @@ Usage:
   --help, -h    this help
 
 Every SEED is CREATE-ONLY: an existing file is preserved byte-for-byte, never clobbered and never
-refreshed in place. Four ops refresh instead: the orchestration onboarding note, only while it still
+refreshed in place. Three ops refresh instead: the orchestration onboarding note, only while it still
 matches a canonical the kit shipped (your own wording is preserved verbatim); the spec-layer reader
 and checker pairs, only while a file's bytes are a body a release shipped (an edited file is
 preserved, the writes that depend on it — the spec store root included — are withheld behind it,
-and ONE printed replace line replaces every edited file only on the user's yes); the placed executor
-vehicle (.claude/agents/executor.md), re-derived from docs/ai/vehicles.json
-whenever its bytes differ from the derived body (a hand edit is replaced, never preserved; an absent
-file is never placed here); and the navigator index — a GENERATED artifact, regenerated
+and ONE printed replace line replaces every edited file only on the user's yes); and the navigator index — a GENERATED artifact, regenerated
 whenever it is missing or stale; where a module the project's hook loads is not the bundled one,
 the project's own checker judges the navigator and a write it rejects is put back byte for byte.
+The executor ensure writes nothing: a placed .claude/agents/executor.md whose bytes differ from the
+body derived from docs/ai/vehicles.json is pending — the advisor's executor-vehicle.differing item
+changes it on your yes; an absent file is never placed here.
 The enforcement-script ensure detects an older ADR-store layout FIRST and instructs the opt-in
 migration instead of seeding.
 

package/tools/ensure-executor.mjs

@@ -1,9 +1,9 @@
 // ensure-executor.mjs — the EIGHTH upgrade ensure, fifth in the fixed order right after `vehicles`:
-// the placed executor vehicle (.claude/agents/executor.md) re-derived from docs/ai/vehicles.json.
-// The agents writer PLACES the vehicle on consent; this ensure never does — it only keeps a placed
-// body equal to the one derived from the settings, and a hand edit is replaced, never preserved.
+// the placed executor vehicle (.claude/agents/executor.md) judged against the body derived from
+// docs/ai/vehicles.json. It never writes: the agents writer PLACES the vehicle on consent, and a placed
+// body that differs is reported `pending` — the advisor's executor-vehicle.differing item re-derives it.
 //
-// The state table, in the order the cells are proven (the write is the LAST step):
+// The state table, in the order the cells are proven:
 // | cell | .claude, .claude/agents | placed path | docs/ai/vehicles.json | answer | read before answering |
 // |------|-------------------------|-------------|-----------------------|--------|-----------------------|
 // | 0 | a symlink or not a directory | any | any | failed / wrong-node-kind | nothing |
@@ -12,30 +12,27 @@
 // | 3 | directories | regular file | unreadable (malformed, read or lstat error) | failed / vehicle-settings-unreadable | the settings only |
 // | 4 | directories | regular file | present or absent | failed / bundle-unreadable when the bundled template cannot be read | settings, bundle |
 // | 5 | directories | regular file, bytes equal to the derived body | present or absent | already-current | settings, bundle, placed file |
-// | 6 | directories | regular file, bytes differ | present or absent | dry-run would-re-derive; apply re-derived, or failed / write-refused | settings, bundle, placed file |
+// | 6 | directories | regular file, bytes differ (executorBodyDiffers) | present or absent | pending, on the dry run and the run alike | settings, bundle, placed file |
 // | 7 | an lstat of `.claude`, `.claude/agents` or the placed path throwing other than ENOENT, or the read of the placed file throwing | | | NOT caught: the error propagates to the CLI's catch-all (`unexpected-error`) | |
 //
 // Dependency-free, Node >= 22. Every fs primitive is injectable (deps.*). No side effects on import.
 
-import { readFileSync, lstatSync } from 'node:fs';
+import { lstatSync } from 'node:fs';
 import { join } from 'node:path';
-import { writeContainedFileAtomic } from './atomic-write.mjs';
-import { composeFailure, composeOutcome, probeSeedTarget, tmpNote } from './ensure-ops.mjs';
-import { assertDirSafe, AGENTS_DIR, CLAUDE_DIR, CHEAP_AGENTS_SYMLINK, EXECUTOR_VEHICLE_REL, executorTemplate, readExecutorPosture } from './cheap-agents-read.mjs';
+import { composeFailure, composeOutcome, probeSeedTarget } from './ensure-ops.mjs';
+import { assertDirSafe, AGENTS_DIR, CLAUDE_DIR, CHEAP_AGENTS_SYMLINK, EXECUTOR_VEHICLE_REL, executorBodyDiffers, executorTemplate, readExecutorPosture } from './cheap-agents-read.mjs';
 import { VEHICLES_REL } from './vehicle-settings.mjs';
 
 export const EXECUTOR_OP = 'executor';
 
 const BUNDLE_DIR = ['references', 'agents'];
-const ENCODING = 'utf8';
 
 const ok = (token, lines) => composeOutcome(EXECUTOR_OP, token, lines, false);
 const loud = (cause, ...lines) => composeFailure(EXECUTOR_OP, cause, ...lines);
 const causeOf = (err) => String((err && err.message) || err);
 
-export const ensureExecutor = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
+export const ensureExecutor = ({ cwd, kitRoot, deps = {} }) => {
   const lstat = deps.lstat ?? lstatSync;
-  const read = deps.readFile ?? readFileSync;
 
   try {
     assertDirSafe(join(cwd, CLAUDE_DIR), CLAUDE_DIR, { lstat });
@@ -59,29 +56,15 @@ export const ensureExecutor = ({ cwd, kitRoot, dryRun = false, deps = {} }) => {
     return loud('vehicle-settings-unreadable', `${EXECUTOR_VEHICLE_REL}: ${reason} — nothing written; fix ${VEHICLES_REL} by hand, then re-run`);
   }
 
-  let body;
+  const bundleDeps = { ...deps, bundleDir: join(kitRoot, ...BUNDLE_DIR) };
   try {
-    body = executorTemplate(posture, { ...deps, bundleDir: join(kitRoot, ...BUNDLE_DIR) }).content;
+    executorTemplate(posture, bundleDeps);
   } catch (err) {
     return loud('bundle-unreadable', `${EXECUTOR_VEHICLE_REL}: the bundled executor template could not be read, so nothing was written — reinstall the kit. ${causeOf(err)}`);
   }
 
-  const existing = read(target, ENCODING);
-  if (existing === body) {
+  if (!executorBodyDiffers(cwd, bundleDeps)) {
     return ok('already-current', [`${EXECUTOR_VEHICLE_REL}: the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}, source ${posture.source}) — nothing written`]);
   }
-  if (dryRun) {
-    return ok('would-re-derive', [`${EXECUTOR_VEHICLE_REL}: differs from the body derived from ${VEHICLES_REL} — would be rewritten (a hand edit is replaced, never preserved)`]);
-  }
-
-  let result;
-  try {
-    result = writeContainedFileAtomic(cwd, target, body, deps, { label: EXECUTOR_VEHICLE_REL });
-  } catch (err) {
-    return loud('write-refused', `${EXECUTOR_VEHICLE_REL}: ${causeOf(err)}`);
-  }
-  return ok('re-derived', [
-    `${EXECUTOR_VEHICLE_REL}: rewritten to the body derived from ${VEHICLES_REL} (model=${posture.model}, effort=${posture.effort}) — a hand edit was replaced; set the model in ${VEHICLES_REL}`,
-    ...tmpNote(EXECUTOR_VEHICLE_REL, result.tmpLeftBehind),
-  ]);
+  return ok('pending', [`${EXECUTOR_VEHICLE_REL}: differs from the body derived from ${VEHICLES_REL} — nothing written; the advisor's executor-vehicle.differing item re-derives it on your yes`]);
 };

package/tools/ensure-vocabulary.mjs

@@ -18,9 +18,8 @@ export const ENSURE_OPS = Object.freeze(['orchestration', 'gates', 'autonomy', '
 // ensure's pair refresh (reader or checker) — a deployed script on a body a release shipped,
 // rewritten to the bundled one; a custom body is rewritten only by the replace run the user's yes
 // starts (--replace-custom), never by a plain run.
-// `re-derived` is the executor ensure rewriting a placed executor whose bytes differ from the body derived from docs/ai/vehicles.json.
-export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated', 're-derived']);
-export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate', 'would-re-derive']);
+export const WRITE_TOKENS = Object.freeze(['seeded', 'note-refreshed', 'refreshed', 'regenerated']);
+export const DRY_RUN_TOKENS = Object.freeze(['would-seed', 'would-refresh-note', 'would-refresh', 'would-regenerate']);
 
 // The CLOSED outcome vocabulary. Closed at RUNTIME, not by convention: composing an outcome with a
 // token outside this list throws, so an op cannot quietly invent a word the mode doc has never heard
@@ -33,6 +32,7 @@ export const ENSURE_TOKENS = Object.freeze([
   'already-current',
   'already-present',
   'not-placed',
+  'pending',
   'customized-preserved',
   'malformed-preserved',
   'skipped-no-node-evidence',
@@ -80,7 +80,7 @@ export const RELAYED_ENSURE_TOKENS = Object.freeze([
   'note-refreshed',
   'refreshed',
   'regenerated',
-  're-derived',
+  'pending',
   'already-current',
   'customized-preserved',
   'malformed-preserved',

package/tools/git-hooks.mjs

@@ -2,7 +2,8 @@
 // git-hooks.mjs — the thin writer of the two git-hook items (`enforcement`, `commit-guard`): it copies
 // the bundled scripts create-only and spawns the project's own scripts/install-git-hooks.mjs, which
 // decides the hook at the write. The leaf decides nothing about the hook: the danger check binds the
-// copies and the installer bytes this dry run answers, never git's hooks dir.
+// copies and the installer bytes this dry run answers, never git's hooks dir. It is also the home of the
+// one pre-commit reader, which the commit-guard apply runs after the installer to verify the arm.
 import { lstatSync, readFileSync, readdirSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
@@ -11,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { writeProjectFileCreateOnly } from './atomic-write.mjs';
 import { NODE_EVIDENCE_SCRIPTS } from './node-evidence.mjs';
 import { shellQuoteArg } from './repo-lex.mjs';
+import { GIT_MAX_BUFFER } from './git-env.mjs';
 import { isDirectRun } from './direct-run.mjs';
 
 const TOOLS = dirname(fileURLToPath(import.meta.url));
@@ -39,6 +41,34 @@ const nodeAt = (path, lstat) => {
 const isPlainDir = (node) => node !== null && node.isDirectory() && !node.isSymbolicLink();
 const isFile = (node) => node !== null && node.isFile() && !node.isSymbolicLink();
 
+// The absolute hooks dir git itself reports (a linked worktree's own, core.hooksPath), or null outside a git tree.
+export const resolveGitHooksPath = (projectDir, env = process.env) => {
+  const result = spawnSync('git', ['rev-parse', '--git-path', 'hooks'], { cwd: projectDir, env, maxBuffer: GIT_MAX_BUFFER, windowsHide: true });
+  if (result.error || result.status !== 0) return null;
+  return resolve(projectDir, result.stdout.toString('utf8').replace(/\r?\n$/, ''));
+};
+
+export const INSTALLER_MARKER_RE = /:install-git-hooks\.mjs$/m;
+const escapeRe = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// Armed means the exact line the installer writes on the kit's own guard path; a commented or lookalike line is not.
+export const canonicalGuardLineRe = (toolsDir = TOOLS) => new RegExp(`^node "${escapeRe(join(toolsDir, 'commit-guard.mjs'))}" --check$`, 'm');
+
+// The one reader of git's pre-commit: whose hook it is, and whether the canonical guard line arms it.
+export const readPreCommitState = (root, deps = {}) => {
+  const hooksPath = (deps.gitHooksPath ?? resolveGitHooksPath)(root, deps.env);
+  if (hooksPath === null) return { state: 'no-hooks-dir', armed: false };
+  const path = join(hooksPath, 'pre-commit');
+  let hook;
+  try {
+    (deps.lstat ?? lstatSync)(path);
+    hook = String((deps.readFile ?? readFileSync)(path, 'utf8'));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return { state: 'absent', armed: false };
+    return { state: 'unreadable', code: error?.code ?? String(error?.message ?? error), path, armed: false };
+  }
+  return { state: INSTALLER_MARKER_RE.test(hook) ? 'managed' : 'unmanaged', armed: canonicalGuardLineRe(deps.toolsDir).test(hook) };
+};
+
 // The dry run: what the apply copies and the installer it runs, with the bytes of each.
 export const planGitHooks = ({ root, variant, toolsDir = TOOLS, lstat = lstatSync, readFile = readFileSync }) => {
   const scripts = join(root, SCRIPTS_REL);
@@ -115,7 +145,7 @@ const rollBack = (plan, created, io) => {
 
 export const applyGitHooks = (plan, io = {}) => {
   const resolved = { lstat: lstatSync, unlink: unlinkSync, rmdir: rmdirSync, readdir: readdirSync, env: process.env,
-    log: console.log, error: console.error, writeFile: writeProjectFileCreateOnly,
+    log: console.log, error: console.error, writeFile: writeProjectFileCreateOnly, toolsDir: TOOLS,
     spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
   const created = [];
   const leftovers = [];
@@ -145,7 +175,15 @@ export const applyGitHooks = (plan, io = {}) => {
   const child = resolved.spawn(plan.runs.argv, { cwd: plan.root, env: resolved.env, stdio: 'inherit' });
   if (child.status !== 0) return fail([`installer exited ${child.status ?? child.signal ?? child.error?.code}`]);
   for (const path of leftovers) resolved.error(`not removed: ${path}`);
-  return EXIT_OK;
+  if (plan.variant !== 'commit-guard') return EXIT_OK;
+  // An installer older than the arm ignores --commit-guard and still exits 0, so the arm is read back under its env.
+  const hooksDir = resolveGitHooksPath(plan.root, resolved.env);
+  const hook = readPreCommitState(plan.root, { env: resolved.env, toolsDir: resolved.toolsDir, gitHooksPath: () => hooksDir });
+  if (hook.state === 'no-hooks-dir' || hook.armed) return EXIT_OK;
+  const path = join(hooksDir, 'pre-commit');
+  resolved.error(hook.state === 'unreadable' ? `${path} is unreadable (${hook.code}) after the installer exited 0`
+    : `${path} carries no commit-guard line after the installer exited 0 — an installer older than the arm ignores --commit-guard; refreshing ${INSTALLER_REL} from the kit's references/scripts/ copy is your own step`);
+  return EXIT_INCOMPLETE;
 };
 
 export const parseArgs = (argv) => {

package/tools/hide-footprint.mjs

@@ -14,9 +14,9 @@
 // Decisions (plan D1–D16): one managed fence, re-derived wholesale → re-run is byte-identical (zero
 // diff); tracked → ASK; present-but-untracked high-risk (generic names) → ASK; everything else → HIDE;
 // asks are excluded from the block unless opted in via `--include` (an asks-only, traversal/glob-free
-// path). Add-local-first, then DETECT + REPORT the residual legacy global block — removal is the
-// explicit, ASK-gated `--remove-global` (prints a restorable backup), never a default (an arbitrary
-// host's OTHER hidden repo may rely on the same root-anchored global lines). Windows is supported (text
+// path). Add-local-first, then DETECT + REPORT the residual legacy global block — the hide never writes
+// the global file; removal is the `--remove-global` mode alone, the advisor's footprint-global item
+// (prints a restorable backup; another of the host's hidden repos may rely on the same lines). Windows is supported (text
 // edit; forward-slash patterns; CRLF preserved via EOL detection). Dependency-free, Node >= 22.
 
 import {
@@ -90,10 +90,13 @@ const canonicalize = (pattern) => {
 // canonicalize alone misses glob children, so the consented line would be dropped → a silent un-hide.
 const recognizeHideRule = (pattern) => canonicalize(pattern) ?? (matchesKnownGlob(pattern) ? normalizeSlashes(pattern) : null);
 
-// Slash-tolerant membership in the HISTORICAL global set.
-const historicalMatch = (pattern) => {
+// The historical lines any repository's own ignore may carry: a removal plan needs one kit-specific line besides them.
+const GENERIC_GLOBAL_PATHS = new Set(['/AGENTS.md', '/CLAUDE.md', '/docs/ai/', '/docs/plans/', '/.claude/skills/']);
+
+// Slash-tolerant membership in a global path set (the HISTORICAL one by default).
+const historicalMatch = (pattern, set = HISTORICAL_GLOBAL_PATHS) => {
   const p = normalizeSlashes(pattern);
-  return HISTORICAL_GLOBAL_PATHS.has(p) || HISTORICAL_GLOBAL_PATHS.has(`${p}/`) || (p.endsWith('/') && HISTORICAL_GLOBAL_PATHS.has(p.slice(0, -1)));
+  return set.has(p) || set.has(`${p}/`) || (p.endsWith('/') && set.has(p.slice(0, -1)));
 };
 
 // ── EOL + line model ────────────────────────────────────────────────────────────
@@ -144,8 +147,8 @@ const defaultGit = (args, { cwd, env }) => {
 const runGit = (deps, dir, args) => (deps.git ?? defaultGit)(args, { cwd: dir, env: deps.env ?? process.env });
 
 const fsOf = (deps = {}) => ({
-  readFile: deps.readFile ?? ((p) => readFileSync(p, 'utf8')),
-  writeFile: deps.writeFile ?? ((p, c) => writeFileSync(p, c, 'utf8')),
+  readFile: deps.readFile ?? ((p, encoding = 'utf8') => readFileSync(p, encoding)),
+  writeFile: deps.writeFile ?? ((p, c, encoding = 'utf8') => writeFileSync(p, c, encoding)),
   stat: deps.stat ?? statSync,
   readdir: deps.readdir ?? readdirSync,
 });
@@ -362,45 +365,60 @@ const globalExcludesPath = (deps, dir, home) => {
   if (r.status === 1) return null; // unset = NORMAL "nothing to migrate" (not a STOP)
   if (r.status !== 0) throw stop(`git config --get core.excludesFile failed (exit ${r.status}): ${r.stderr.trim()}`);
   const p = r.stdout.trim();
-  return p ? expandTilde(p, home) : null;
+  return p ? resolve(dir, expandTilde(p, home)) : null;
 };
 
-// Detect + REPORT a residual legacy global block; remove ONLY contiguous recognized runs (header +
-// historical paths) and ONLY when removeGlobal — printing the removed lines as a restorable backup.
-export const migrateFromGlobal = (deps, dir, { home, removeGlobal, dryRun }) => {
-  const fsx = fsOf(deps);
-  const gp = globalExcludesPath(deps, dir, home);
-  if (!gp) return { found: false, source: null, removedLines: [], action: 'none' };
-  let content;
+// The pure core over the global file read as latin1: each recognised legacy line goes with its own
+// terminator and every other byte stays; null without one kit-specific line among them.
+export const globalRemovalOf = (text) => {
+  const parts = text.split(/(\r\n|\n|\r)/);
+  const removedLines = [];
+  let after = '';
+  let specific = false;
+  for (let i = 0; i < parts.length; i += 2) {
+    const t = parts[i].trim();
+    const pattern = lineToPattern(parts[i]);
+    const marker = isLegacyGlobalHeader(t) || isAd013Comment(t);
+    if (marker || (pattern && historicalMatch(pattern))) {
+      removedLines.push(parts[i]);
+      specific ||= marker || !historicalMatch(pattern, GENERIC_GLOBAL_PATHS);
+    } else after += parts[i] + (parts[i + 1] ?? '');
+  }
+  return specific ? { removedLines, after } : null;
+};
+
+// The one answer the hide's kept line, the advisor's probe, the danger check and --remove-global read.
+export const planGlobalRemoval = (deps, root, { home }) => {
+  const source = globalExcludesPath(deps, root, home);
+  if (!source) return null;
+  let before;
   try {
-    content = fsx.readFile(gp);
+    before = fsOf(deps).readFile(source, 'latin1');
   } catch (err) {
-    if (err && err.code === 'ENOENT') return { found: false, source: gp, removedLines: [], action: 'none' };
-    throw stop(`cannot read global excludes ${gp} (${err.code ?? 'fs error'})`);
+    if (err && err.code === 'ENOENT') return null;
+    throw stop(`cannot read global excludes ${source} (${err.code ?? 'fs error'})`);
   }
-  const eol = detectEol(content);
-  const lines = splitLines(content);
-  const recognized = (raw) => {
-    const t = raw.trim();
-    if (isLegacyGlobalHeader(t) || isAd013Comment(t)) return true;
-    const pat = lineToPattern(raw);
-    return pat ? historicalMatch(pat) : false;
-  };
-  const kept = [];
-  const removed = [];
-  let i = 0;
-  while (i < lines.length) {
-    if (recognized(lines[i])) {
-      while (i < lines.length && recognized(lines[i])) { removed.push(lines[i]); i += 1; }
-    } else {
-      kept.push(lines[i]);
-      i += 1;
-    }
+  const removal = globalRemovalOf(before);
+  return removal && { source, before, ...removal };
+};
+
+// Detect + REPORT a residual legacy global block; the hide never writes the global file.
+export const migrateFromGlobal = (deps, dir, { home }) => {
+  const plan = planGlobalRemoval(deps, dir, { home });
+  if (!plan) return { found: false, source: null, removedLines: [], action: 'none' };
+  return { found: true, source: plan.source, removedLines: plan.removedLines, action: 'kept' };
+};
+
+// The --remove-global mode: no exclude file read, no local block written; a refused write is the lane's STOP.
+const removeGlobal = (opts, deps) => {
+  const plan = planGlobalRemoval(deps, resolve(opts.dir ?? process.cwd()), { home: deps.home ?? os.homedir() });
+  if (!plan || opts.dryRun) return { plan, action: plan ? 'would-remove' : 'none' };
+  try {
+    fsOf(deps).writeFile(plan.source, plan.after, 'latin1');
+  } catch (err) {
+    throw stop(`cannot write the global excludes ${plan.source} (${err?.code ?? err?.message ?? err}) — the block stays`);
   }
-  if (removed.length === 0) return { found: false, source: gp, removedLines: [], action: 'none' };
-  if (!removeGlobal) return { found: true, source: gp, removedLines: removed, action: 'kept' };
-  if (!dryRun) fsx.writeFile(gp, joinLines(kept, eol));
-  return { found: true, source: gp, removedLines: removed, action: 'removed', backup: removed.join('\n') };
+  return { plan, action: 'removed' };
 };
 
 // ── --include validation (D4 — only an asks[] path; no traversal/glob) ───────────
@@ -452,9 +470,9 @@ export const hideFootprint = (opts = {}, deps = {}) => {
   const fenceBodyLines = fence.state === 'ok' ? lines.slice(fence.startIdx + 1, fence.endIdx) : [];
   const after = fence.state === 'ok' ? lines.slice(fence.endIdx + 1) : [];
 
-  // ── unhide (D12): drop our fence; report/remove the residual global block ──────
+  // ── unhide (D12): drop our fence; report the residual global block ──────
   if (opts.unhide) {
-    const global = migrateFromGlobal(deps, dir, { home, removeGlobal: opts.removeGlobal, dryRun });
+    const global = migrateFromGlobal(deps, dir, { home });
     const newLines = [...before, ...after];
     const newContent = joinLines(newLines, eol);
     const changed = newContent !== content;
@@ -520,8 +538,8 @@ export const hideFootprint = (opts = {}, deps = {}) => {
     throw stop(`hide verification failed — these were written but are not hidden by the project-local exclude: ${notHidden.map((v) => v.path).join(', ')}`);
   }
 
-  // ── then detect/report (or remove) the residual legacy global block (D6) ───────
-  const global = migrateFromGlobal(deps, dir, { home, removeGlobal: opts.removeGlobal, dryRun });
+  // ── then detect + report the residual legacy global block (D6) ─────────────────
+  const global = migrateFromGlobal(deps, dir, { home });
 
   const action = !changed ? 'noop' : fence.state === 'ok' ? 'updated' : 'created';
   return {
@@ -545,29 +563,29 @@ export const hideFootprint = (opts = {}, deps = {}) => {
 
 // ── CLI ───────────────────────────────────────────────────────────────────────────
 
-const USAGE = `usage: hide-footprint [--dir <project>] [--reconcile] [--include=<path>]... [--keep-global | --remove-global] [--unhide] [--dry-run] [--help]
+const USAGE = `usage: hide-footprint [--dir <project>] [--reconcile] [--include=<path>]... [--unhide] [--dry-run] [--help]
+       hide-footprint --remove-global [--dir <project>] [--dry-run]
 
   --dir <project>     the target project (default: cwd)
   --reconcile         upgrade mode — infer visibility first; write zero bytes when VISIBLE, ASK when AMBIGUOUS
   --include=<path>    opt a surfaced ASK path into the hidden set (only an asks[] path; no glob/traversal)
-  --keep-global       keep + report the residual legacy machine-global block (DEFAULT)
-  --remove-global     remove the recognized legacy machine-global block (prints a restorable backup)
-  --unhide            remove the project-local managed block (residual global only with --remove-global)
+  --remove-global     its own mode: remove the recognized legacy machine-global block (prints a restorable backup)
+  --unhide            remove the project-local managed block
   --dry-run           print the plan; change nothing
   --help, -h          this help
 
-Writes ONE managed block in the PROJECT-LOCAL .git/info/exclude (never the machine-global excludes).
+Writes ONE managed block in the PROJECT-LOCAL .git/info/exclude; a residual legacy machine-global block is
+kept and reported, and only --remove-global (the advisor's footprint-global item) removes it.
 Tracked files are never silently un-tracked — the tool prints the \`git rm --cached\` it will not run.`;
 
 const parseArgs = (argv) => {
-  const out = { dir: undefined, reconcile: false, include: [], removeGlobal: false, keepGlobal: false, unhide: false, dryRun: false, help: false, bad: null };
+  const out = { dir: undefined, reconcile: false, include: [], removeGlobal: false, unhide: false, dryRun: false, help: false, bad: null };
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--help' || a === '-h') out.help = true;
     else if (a === '--dry-run') out.dryRun = true;
     else if (a === '--reconcile') out.reconcile = true;
     else if (a === '--unhide') out.unhide = true;
-    else if (a === '--keep-global') out.keepGlobal = true;
     else if (a === '--remove-global') out.removeGlobal = true;
     else if (a === '--dir') {
       const next = argv[i + 1];
@@ -580,15 +598,22 @@ const parseArgs = (argv) => {
       else { out.include.push(next); i += 1; }
     } else out.bad = `unknown argument: ${a}`;
   }
-  if (out.keepGlobal && out.removeGlobal) out.bad = '--keep-global and --remove-global are mutually exclusive';
+  if (out.removeGlobal && !out.bad && (out.reconcile || out.unhide || out.include.length)) out.bad = '--remove-global is its own mode — it cannot be combined with --reconcile, --unhide or --include';
   return out;
 };
 
 const fmtGlobal = (g) => {
-  if (!g || g.action === 'none' || g.action === 'skipped') return [];
-  if (g.action === 'kept') return [`  • residual legacy machine-global block in ${g.source} (${g.removedLines.filter((l) => l.trim() && !l.trim().startsWith('#')).length} path line(s)) — KEPT + reported; pass --remove-global to remove (with a printed backup)`];
-  if (g.action === 'removed') return [`  • removed the legacy machine-global block from ${g.source} (backup of ${g.removedLines.length} line(s) printed below)`, ...g.removedLines.map((l) => `      | ${l}`)];
-  return [];
+  if (!g || g.action !== 'kept') return [];
+  return [`  • residual legacy machine-global block in ${g.source} (${g.removedLines.filter((l) => l.trim() && !l.trim().startsWith('#')).length} path line(s)) — KEPT + reported; the advisor's footprint-global item removes it (with a printed backup)`];
+};
+
+const formatRemoval = ({ plan, action }, dryRun) => {
+  const lines = [dryRun ? 'hide-footprint — DRY RUN (no changes)' : 'hide-footprint'];
+  if (action === 'none') return [...lines, '  • no legacy machine-global block to remove'].join('\n');
+  const n = plan.removedLines.length;
+  lines.push(action === 'removed' ? `  • removed the legacy machine-global block from ${plan.source} (backup of ${n} line(s) printed below)`
+    : `  • would remove the legacy machine-global block from ${plan.source} (${n} line(s)):`);
+  return [...lines, ...plan.removedLines.map((l) => `      | ${l}`)].join('\n');
 };
 
 export const formatReport = (r, dryRun) => {
@@ -624,10 +649,11 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
   if (args.help) { log(USAGE); return 0; }
   if (args.bad) { errlog(args.bad); errlog(USAGE); return 2; }
   try {
-    const result = hideFootprint(
-      { dir: args.dir, dryRun: args.dryRun, reconcile: args.reconcile, include: args.include, removeGlobal: args.removeGlobal, unhide: args.unhide },
-      deps,
-    );
+    if (args.removeGlobal) {
+      log(formatRemoval(removeGlobal({ dir: args.dir, dryRun: args.dryRun }, deps), args.dryRun));
+      return 0;
+    }
+    const result = hideFootprint({ dir: args.dir, dryRun: args.dryRun, reconcile: args.reconcile, include: args.include, unhide: args.unhide }, deps);
     log(formatReport(result, args.dryRun));
     return 0;
   } catch (err) {

package/tools/init-project.mjs

@@ -216,7 +216,7 @@ const previewQueue = async (context, queue) => {
     }
     context.print(result.stdout);
     const tuple = result.stdout.match(/--apply\s+(\S+)/)?.[1];
-    const facts = { ...context.facts, tuple };
+    const facts = { ...context.facts, env: context.spawnEnv, tuple };
     let checkDigest = null;
     if (laneOf(item.variant) === LANE_HARNESS) {
       try {

package/tools/mcp-registration.mjs

@@ -311,7 +311,7 @@ const classifyDir = (abs, io) => {
   return { state: STATE.FOREIGN, className: describeNonRegular(st) };
 };
 
-// ── the merges (ONE definition, shared by the writer's bodies and the paste-ready fragments) ──
+// ── the merges (ONE definition, shared by the writer's bodies) ──
 // Merge-don't-clobber in both: every foreign server, key and allow rule is carried over untouched,
 // and our own entry/rules are added idempotently.
 
@@ -335,19 +335,6 @@ export const mergeSettings = (registration) => {
 
 export const formatJson = (data, eol) => `${JSON.stringify(data, null, JSON_INDENT).replaceAll(LF, eol)}${eol}`;
 
-// The two hand-apply bodies — the whole output of the MASKED arm.
-//
-// They are deliberately DIFFERENT shapes, because what the kit knows about each file differs. The
-// settings file was OBSERVABLE — and read where present — so its body is a real merge: it already
-// carries every foreign key it had. The masked `.mcp.json` was not observable at all, so a
-// whole-file body would name only our server and, pasted as
-// instructed, would delete every foreign server the mask hid. `mcpEntry` is therefore the ENTRY
-// ALONE, to be merged under `mcpServers` by a human who can see what is actually in that file.
-export const renderFragments = (registration) => ({
-  mcpEntry: formatJson(registration.entry, registration.mcpJson.eol),
-  settings: formatJson(mergeSettings(registration), registration.settings.eol),
-});
-
 // A LIBRARY module the mode doc names by path — so someone can try to run it. A no-op on import;
 // on a direct run it points at the command that acts on what this module only reports.
 refuseDirectRun(import.meta.url);