@sabaiway/agent-workflow-kit 14.32.0 → 14.34.0

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

@@ -13,7 +13,7 @@ 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_HARNESS, VARIANT_LANES, consoleArgv, isEnvDependent, isProtectedPath, laneOf, writesOf } from './write-lanes.mjs';
+import { LANE_HARNESS, VARIANT_LANES, consoleArgv, isEnvDependent, isProtectedPath, isRejudged, laneOf, 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: ';
@@ -216,18 +216,21 @@ 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 {
-        const { lines, refused } = context.checkApply(item.variant, facts, {});
+        const { lines, refused, digest } = context.checkApply(item.variant, facts, {});
         for (const line of lines) context.print(line);
         if (refused.length > 0) throw new Error(refused.map(({ key }) => key).join(', '));
+        checkDigest = digest;
       } catch (error) {
         context.print(`not applied: ${item.variant} — the danger check refused: ${error.message}`);
         continue;
       }
     }
-    batch.push({ ...item, applyArgv: consoleArgv(item.variant, facts).apply, writes: writesOf(item.variant, facts) });
+    batch.push({ ...item, checkFacts: facts, checkDigest, 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)) {
@@ -254,11 +257,24 @@ const takeRecord = (context, queue) => {
   }
 };
 
+// A rejudged item applies only while its check, run again now, answers the digest its preview showed; else the reason.
+const rejudgeFailure = (context, item) => {
+  try {
+    const { refused, digest } = context.checkApply(item.variant, item.checkFacts, {});
+    if (refused.length > 0) return `it refuses ${refused.map(({ key }) => key).join(', ')}`;
+    return digest === item.checkDigest ? null : 'its digest moved';
+  } catch (error) {
+    return String(error?.message || error);
+  }
+};
+
 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 previewed = await previewQueue(context, queue);
+  if (previewed.length === 0) return { code: 0, successes: 0, variants: [] };
+  // Rejudged items go first: an earlier writer of the batch (one creating .claude/) would move their check.
+  const batch = [...previewed.filter(({ variant }) => isRejudged(variant)), ...previewed.filter(({ variant }) => !isRejudged(variant))];
   const before = new Map(record);
   const outcome = { code: 0, successes: 0, variants: batch.map((item) => item.variant) };
   context.print(RUN_NONE);
@@ -271,6 +287,15 @@ const runPass = async (context, queue) => {
       outcome.code = 1;
       break;
     }
+    const failure = isRejudged(item.variant) ? rejudgeFailure(context, item) : null;
+    if (failure !== null) {
+      context.print(`not applied: ${item.variant} — its danger check no longer answers the previewed result: ${failure}`);
+      for (const later of batch.slice(index + 1)) {
+        context.print(`not applied: ${later.variant} — an earlier item's danger check no longer answers the previewed result`);
+      }
+      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')));