@sabaiway/agent-workflow-kit 14.30.0 → 14.32.0

package/tools/git-hooks.mjs

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+// 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.
+import { lstatSync, readFileSync, readdirSync, rmdirSync, statSync, unlinkSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { dirname, join, resolve } from 'node:path';
+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 { isDirectRun } from './direct-run.mjs';
+
+const TOOLS = dirname(fileURLToPath(import.meta.url));
+export const SCRIPTS_REL = 'scripts';
+export const INSTALLER_REL = 'scripts/install-git-hooks.mjs';
+const bundleDir = (toolsDir) => join(toolsDir, '..', 'references', 'scripts');
+export const BUNDLED_SCRIPT_NAMES = Object.freeze(readdirSync(bundleDir(TOOLS)).filter((name) => name.endsWith('.mjs')).sort());
+
+const EXIT_OK = 0;
+const EXIT_INCOMPLETE = 1;
+const EXIT_USAGE = 2;
+const EXIT_REFUSED = 3;
+const USAGE = 'usage: git-hooks (--enforcement | --commit-guard) [--cwd <root>] [--apply]';
+const sha = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const usageError = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+const refusal = (message) => Object.assign(new Error(message), { exitCode: EXIT_REFUSED });
+
+const nodeAt = (path, lstat) => {
+  try {
+    return lstat(path);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+};
+const isPlainDir = (node) => node !== null && node.isDirectory() && !node.isSymbolicLink();
+const isFile = (node) => node !== null && node.isFile() && !node.isSymbolicLink();
+
+// 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);
+  const scriptsNode = nodeAt(scripts, lstat);
+  if (scriptsNode !== null && !isPlainDir(scriptsNode)) throw refusal(`${scripts} is not a plain directory`);
+  const kinds = new Map();
+  const names = variant === 'enforcement' ? BUNDLED_SCRIPT_NAMES : [INSTALLER_REL.slice(SCRIPTS_REL.length + 1)];
+  for (const name of scriptsNode === null ? [] : names) {
+    const path = join(scripts, name);
+    const node = nodeAt(path, lstat);
+    if (node !== null && !isFile(node)) throw refusal(`${path} is not a regular file`);
+    kinds.set(name, node === null ? 'absent' : 'file');
+  }
+  const installer = join(root, INSTALLER_REL);
+  const deployed = NODE_EVIDENCE_SCRIPTS.some((name) => kinds.get(name) === 'file');
+  const copies = variant === 'enforcement' && !deployed ? BUNDLED_SCRIPT_NAMES.map((name) => {
+    if (kinds.get(name) === 'file') return { name, path: join(scripts, name), action: 'kept' };
+    return { name, path: join(scripts, name), action: 'created', bytes: readFile(join(bundleDir(toolsDir), name)) };
+  }) : [];
+  const placed = copies.find(({ path, action }) => path === installer && action === 'created');
+  if (!placed && !isFile(nodeAt(installer, lstat))) throw refusal(`${installer} is absent — nothing here places the hook installer`);
+  const guard = variant === 'commit-guard' ? ['--commit-guard', join(toolsDir, 'commit-guard.mjs')] : [];
+  return {
+    root,
+    variant,
+    scriptsCreated: scriptsNode === null,
+    copies,
+    runs: { argv: ['node', installer, ...guard], shown: ['node', INSTALLER_REL, ...guard], bytes: placed ? placed.bytes : readFile(installer) },
+  };
+};
+
+export const formatPlan = (plan) => [
+  ...plan.copies.map(({ name, action, bytes }) => `copy: ${SCRIPTS_REL}/${name} ${action}${action === 'created' ? ` sha256:${sha(bytes)}` : ''}`),
+  `runs: ${plan.runs.shown.map(shellQuoteArg).join(' ')} sha256:${sha(plan.runs.bytes)}`,
+];
+
+// Removes exactly the files this run created, then scripts/ when this run created it and it is empty;
+// every path it cannot remove is answered for the caller to name.
+const rollBack = (plan, created, io) => {
+  const scripts = join(plan.root, SCRIPTS_REL);
+  const left = [];
+  const dirNow = () => nodeAt(scripts, io.lstat);
+  for (const path of created) {
+    const dir = dirNow();
+    const node = nodeAt(path, io.lstat);
+    if (!isPlainDir(dir) || dir.ino !== created.dirIno || !isFile(node)) {
+      left.push(path);
+      continue;
+    }
+    try {
+      io.unlink(path);
+    } catch {
+      left.push(path);
+    }
+  }
+  if (plan.scriptsCreated && created.dirIno !== undefined) {
+    const dir = dirNow();
+    let empty = false;
+    try {
+      empty = isPlainDir(dir) && dir.ino === created.dirIno && io.readdir(scripts).length === 0;
+    } catch {
+      empty = false;
+    }
+    if (empty) {
+      try {
+        io.rmdir(scripts);
+      } catch {
+        left.push(scripts);
+      }
+    } else if (!isPlainDir(dir) || dir.ino !== created.dirIno) left.push(scripts);
+  }
+  return left;
+};
+
+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,
+    spawn: (argv, options) => spawnSync(argv[0], argv.slice(1), options), ...io };
+  const created = [];
+  const leftovers = [];
+  const fail = (lines) => {
+    for (const line of lines) resolved.error(line);
+    for (const path of [...rollBack(plan, created, resolved), ...leftovers]) resolved.error(`not removed: ${path}`);
+    return EXIT_INCOMPLETE;
+  };
+  const scripts = join(plan.root, SCRIPTS_REL);
+  const noteDir = () => {
+    const dir = nodeAt(scripts, resolved.lstat);
+    if (created.dirIno === undefined && isPlainDir(dir)) created.dirIno = dir.ino;
+  };
+  for (const copy of plan.copies.filter(({ action }) => action === 'created')) {
+    let result;
+    try {
+      result = resolved.writeFile(plan.root, `${SCRIPTS_REL}/${copy.name}`, copy.bytes);
+    } catch (error) {
+      noteDir();
+      return fail([error?.message ?? String(error)]);
+    }
+    noteDir();
+    if (result.tmpLeftBehind) leftovers.push(result.tmpLeftBehind);
+    if (!result.created) return fail([`${copy.path} appeared after the check — the file found there stands`]);
+    created.push(copy.path);
+  }
+  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;
+};
+
+export const parseArgs = (argv) => {
+  if (argv.length === 1 && ['--help', '-h'].includes(argv[0])) return { help: true };
+  const args = { apply: false, cwd: undefined, variants: [] };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--apply') args.apply = true;
+    else if (flag === '--enforcement' || flag === '--commit-guard') args.variants.push(flag.slice(2));
+    else if (flag === '--cwd') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('-')) throw usageError('--cwd takes a value');
+      args.cwd = value;
+      index += 1;
+    } else throw usageError(`unknown argument: ${flag}`);
+  }
+  if (args.variants.length !== 1) throw usageError('pass exactly one of --enforcement and --commit-guard');
+  return { help: false, apply: args.apply, cwd: args.cwd, variant: args.variants[0] };
+};
+
+export const main = (argv, io = {}) => {
+  const resolved = { log: console.log, error: console.error, cwd: process.cwd(), toolsDir: TOOLS, ...io };
+  let args;
+  try {
+    args = parseArgs(argv);
+    if (args.help) {
+      resolved.log(USAGE);
+      return EXIT_OK;
+    }
+    args.root = resolve(resolved.cwd, args.cwd ?? '.');
+    if (!statSync(args.root, { throwIfNoEntry: false })?.isDirectory()) throw usageError(`--cwd is not a directory: ${args.root}`);
+  } catch (error) {
+    resolved.error(error.message);
+    resolved.error(USAGE);
+    return EXIT_USAGE;
+  }
+  let plan;
+  try {
+    plan = planGitHooks({ root: args.root, variant: args.variant, toolsDir: resolved.toolsDir });
+  } catch (error) {
+    resolved.error(error.message);
+    return EXIT_REFUSED;
+  }
+  if (!args.apply) {
+    for (const line of formatPlan(plan)) resolved.log(line);
+    return EXIT_OK;
+  }
+  return applyGitHooks(plan, resolved);
+};
+
+if (isDirectRun(import.meta.url)) process.exitCode = main(process.argv.slice(2));

package/tools/recommendations.mjs

@@ -46,7 +46,8 @@ import {
 } from './velocity-profile.mjs';
 import { loadAutonomy, isSparseSeedConfig, AUTONOMY_REL } from './autonomy-config.mjs';
 import { deriveDoctorPlan, TRUSTED_DIRS } from './autonomy-doctor.mjs';
-import { laneOf, applySlot } from './write-lanes.mjs';
+import { laneOf, applySlot, consoleArgv } from './write-lanes.mjs';
+import { STATE_BLOCK_HOOK_COMMAND, STATE_BLOCK_HOOK_RUNTIME, isStopHookWired } from './state-block-hook.mjs';
 import { detectBackends } from './detect-backends.mjs';
 import { isDirectRun } from './direct-run.mjs';
 import { ACTIVITIES, resolveActivityRecipe, composeReadiness, safeLine } from './recipes.mjs';
@@ -119,8 +120,10 @@ const ABSENT_CODE = 'ENOENT';
 const ENFORCEMENT_KIT_ROOT = resolve(HERE, '..');
 const ENFORCEMENT_BUNDLE_ROOT = join(ENFORCEMENT_KIT_ROOT, 'references', 'scripts');
 const ENFORCEMENT_WHAT = 'the enforcement scripts are not deployed beside docs/ai (no Node evidence) \u2014 the offer copies them and installs the pre-commit hook';
-const ENFORCEMENT_APPLY_TEMPLATE = 'HAND-APPLY: mkdir -p {root}/scripts && cp {kit}/references/scripts/*.mjs {root}/scripts/ && node {root}/scripts/install-git-hooks.mjs';
-const COMMIT_GUARD_INSTALLER_REMEDY = 'the hook installer (scripts/install-git-hooks.mjs) is not deployed \u2014 deploy the enforcement scripts (bootstrap steps 8\u20139) and install the hook, then re-run';
+const ENFORCEMENT_UNMANAGED_HOOK = 'an UNMANAGED pre-commit hook exists \u2014 the installer never overwrites it, so the kit places no script here; with that hook moved aside (your own step) the enforcement item is offered';
+const COMMIT_GUARD_INSTALLER_VIA_ITEM = 'the hook installer (scripts/install-git-hooks.mjs) is not deployed \u2014 apply the enforcement item first, then re-run';
+const COMMIT_GUARD_INSTALLER_OWN_STEP = 'the hook installer (scripts/install-git-hooks.mjs) is not deployed here \u2014 deploying the enforcement scripts into this project is your own step, then re-run';
+const COMMIT_GUARD_UNMANAGED_HOOK = 'an UNMANAGED pre-commit hook exists \u2014 the installer never overwrites it; adding the guard line to it is your own step';
 // ── the section contract tokens (doc-parity-bound in upgrade.md + the mode doc) ────────────────
 export const RECOMMENDATIONS_SECTION_HEADER = '## Recommendations (agent-workflow)';
 export const RECOMMENDATIONS_EMPTY_LINE = 'no recommendations — flow optimal.';
@@ -599,16 +602,15 @@ const probeGates = ({ root, deps, add, skip, shared }) => {
     // ABSENT is not this arm either: a hook that is not placed belongs to the place offers above and
     // in the read-lane item, whose recovery actually places one.
     if (readPlacedHookCurrency(root, deps) !== HOOK_CURRENCY.STALE) return;
-    // The writer's OWN stale recovery, in its exact shape: `gate-hook --apply` never overwrites a
-    // placed diverged hook (it places only an ABSENT target), so remove-then-reseed is the only lane
-    // that converges — and it is maintainer territory, hence HAND-APPLY.
+    // The writer's OWN stale recovery: `gate-hook --apply --reseed` replaces the placed hook with
+    // the bundle in place — the one consented replacement; the slot renders it behind the check.
     // The RESULT is what the read-lane item defers to — not these conditions re-derived there. Both
     // probes read the placed hook independently, so a hook that changes between the two reads would
     // otherwise let each conclude the other owns it and leave a dark lane reported by nobody.
     shared.markerStaleRendered = add(
       'gate-hook',
       fillTemplate(WHATS['gate-hook.marker-stale'], {}),
-      `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+      `node ${q(toolPath('gate-hook.mjs'))} --apply --reseed --cwd ${q(root)}`,
       'gate-hook.marker-stale',
     );
   } catch (err) {
@@ -883,7 +885,7 @@ const probeSourceSize = ({ root, deps, add, skip }) => {
 // The D10 consumer surface: once the declaration is FINAL-capable (the canonical core checks
 // present, the checker LAST — the run-gates helper is the one home of that rule), offer the
 // consented commit-guard install — for a MANAGED guardless pre-commit hook AND for an absent one
-// alike; an UNMANAGED hook is a loud skip (manual merge, never an overwrite offer); a
+// alike; an UNMANAGED hook is a loud skip naming the user's own step (never an overwrite offer); a
 // non-final-capable declaration gets NO offer (an armed guard over a matrix that cannot mint a
 // receipt would block every commit).
 const INSTALLER_MARKER_RE = /:install-git-hooks\.mjs$/m;
@@ -892,6 +894,23 @@ const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 // the kit's OWN resolved guard path. A commented-out line or a lookalike path (fake-commit-guard)
 // must never read as armed (that would suppress the offer and leave commits unguarded).
 const canonicalGuardLineRe = () => new RegExp(`^node "${escapeRe(toolPath('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);
+  if (hooksPath === null) return { state: 'no-hooks-dir', armed: false };
+  const path = join(hooksPath, 'pre-commit');
+  const hook = (() => {
+    try {
+      if (readsAbsent(deps, path)) return null;
+      return String((deps.readFile ?? readFileSync)(path, 'utf8'));
+    } catch {
+      return null;
+    }
+  })();
+  if (hook === null) return { state: 'absent', armed: false };
+  return { state: INSTALLER_MARKER_RE.test(hook) ? 'managed' : 'unmanaged', armed: canonicalGuardLineRe().test(hook) };
+};
+const formsApply = (variant, root) => consoleArgv(variant, { toolsDir: HERE, root }).apply.map(q).join(' ');
 const probeCommitGuard = ({ root, deps, add, skip }) => {
   try {
     const read = deps.readFile ?? readFileSync;
@@ -907,25 +926,16 @@ const probeCommitGuard = ({ root, deps, add, skip }) => {
     if (!isFinalCapableDeclaration(gates, root)) return; // no receipt to guard yet — no offer
     const installer = join(root, 'scripts', 'install-git-hooks.mjs');
     if (!(deps.exists ?? existsSync)(installer)) {
-      skip('commit-guard', new Error(COMMIT_GUARD_INSTALLER_REMEDY));
+      skip('commit-guard', new Error(enforcementAdmits(root, deps) ? COMMIT_GUARD_INSTALLER_VIA_ITEM : COMMIT_GUARD_INSTALLER_OWN_STEP));
       return;
     }
-    const hooksPath = (deps.gitHooksPath ?? resolveGitHooksPath)(root);
-    if (hooksPath === null) return; // not a git tree — nothing to hook
-    const hook = (() => {
-      try {
-        if (readsAbsent(deps, join(hooksPath, 'pre-commit'))) return null;
-        return String(read(join(hooksPath, 'pre-commit'), 'utf8'));
-      } catch {
-        return null;
-      }
-    })();
-    if (hook !== null && canonicalGuardLineRe().test(hook)) return; // armed — converged (managed or not)
-    if (hook !== null && !INSTALLER_MARKER_RE.test(hook)) {
-      skip('commit-guard', new Error('an UNMANAGED pre-commit hook exists — merge the guard line by hand (the installer refuses to overwrite it)'));
+    const { state, armed } = readPreCommitState(root, deps);
+    if (armed || state === 'no-hooks-dir') return; // armed (managed or not), or not a git tree — converged
+    if (state === 'unmanaged') {
+      skip('commit-guard', new Error(COMMIT_GUARD_UNMANAGED_HOOK));
       return;
     }
-    add('commit-guard', fillTemplate(WHATS['commit-guard'], {}), `node ${q(installer)} --commit-guard ${q(toolPath('commit-guard.mjs'))}`);
+    add('commit-guard', fillTemplate(WHATS['commit-guard'], {}), formsApply('commit-guard', root));
   } catch (err) {
     skip('commit-guard', err);
   }
@@ -940,31 +950,46 @@ const readEnforcementNode = (path, lstat) => {
   }
 };
 
+// The enforcement offer's one admission: true when the item renders, false when nothing renders, and
+// a throw names the skip.
+const enforcementOffer = (root, deps) => {
+  const lstat = deps.lstat ?? lstatSync;
+  const docsAi = join(root, 'docs', 'ai');
+  const docsAiNode = readEnforcementNode(docsAi, lstat);
+  if (docsAiNode === null) return false;
+  if (!docsAiNode.isDirectory()) throw new Error(`${docsAi} is not a plain directory`);
+  const evidence = probeNodeEvidence(root, lstat);
+  if (evidence.state === NODE_EVIDENCE.PACKAGE_JSON || evidence.state === NODE_EVIDENCE.DEPLOYED_SCRIPTS) return false;
+  if (evidence.state === NODE_EVIDENCE.UNREADABLE) throw new Error(`${root}: ${evidence.error}`);
+  if (evidence.state !== NODE_EVIDENCE.NONE) throw new Error(`unknown Node-evidence state: ${evidence.state}`);
+  if (evidence.wrongKind.length > 0) throw new Error(join(root, evidence.wrongKind[0]));
+  const readDir = deps.readdir ?? readdirSync;
+  const bundleRoot = deps.scriptsBundleRoot ?? ENFORCEMENT_BUNDLE_ROOT;
+  const bundleBasenames = readDir(bundleRoot).filter((name) => name.endsWith('.mjs')).sort();
+  if (NODE_EVIDENCE_SCRIPTS.some((name) => !bundleBasenames.includes(name))) throw new Error(`${bundleRoot}: a runnable enforcement script is missing`);
+  const scripts = join(root, 'scripts');
+  const scriptsNode = readEnforcementNode(scripts, lstat);
+  if (scriptsNode !== null && !scriptsNode.isDirectory()) throw new Error(`${scripts} is not a plain directory`);
+  for (const basename of scriptsNode === null ? [] : bundleBasenames) {
+    const destination = join(scripts, basename);
+    if (readEnforcementNode(destination, lstat) === null) continue;
+    throw new Error(`${destination} already exists; the enforcement copy would clobber it`);
+  }
+  if (readPreCommitState(root, deps).state === 'unmanaged') throw new Error(ENFORCEMENT_UNMANAGED_HOOK);
+  return true;
+};
+
+export const enforcementAdmits = (root, deps = {}) => {
+  try {
+    return enforcementOffer(root, deps);
+  } catch {
+    return false;
+  }
+};
+
 export const probeEnforcement = ({ root, deps, add, skip }) => {
   try {
-    const lstat = deps.lstat ?? lstatSync;
-    const docsAi = join(root, 'docs', 'ai');
-    const docsAiNode = readEnforcementNode(docsAi, lstat);
-    if (docsAiNode === null) return;
-    if (!docsAiNode.isDirectory()) throw new Error(`${docsAi} is not a plain directory`);
-    const evidence = probeNodeEvidence(root, lstat);
-    if (evidence.state === NODE_EVIDENCE.PACKAGE_JSON || evidence.state === NODE_EVIDENCE.DEPLOYED_SCRIPTS) return;
-    if (evidence.state === NODE_EVIDENCE.UNREADABLE) throw new Error(`${root}: ${evidence.error}`);
-    if (evidence.state !== NODE_EVIDENCE.NONE) throw new Error(`unknown Node-evidence state: ${evidence.state}`);
-    if (evidence.wrongKind.length > 0) throw new Error(join(root, evidence.wrongKind[0]));
-    const readDir = deps.readdir ?? readdirSync;
-    const bundleRoot = deps.scriptsBundleRoot ?? ENFORCEMENT_BUNDLE_ROOT;
-    const bundleBasenames = readDir(bundleRoot).filter((name) => name.endsWith('.mjs')).sort();
-    if (NODE_EVIDENCE_SCRIPTS.some((name) => !bundleBasenames.includes(name))) throw new Error(`${bundleRoot}: a runnable enforcement script is missing`);
-    const scripts = join(root, 'scripts');
-    const scriptsNode = readEnforcementNode(scripts, lstat);
-    if (scriptsNode !== null && !scriptsNode.isDirectory()) throw new Error(`${scripts} is not a plain directory`);
-    for (const basename of scriptsNode === null ? [] : bundleBasenames) {
-      const destination = join(scripts, basename);
-      if (readEnforcementNode(destination, lstat) === null) continue;
-      throw new Error(`${destination} already exists; the enforcement copy would clobber it`);
-    }
-    add('enforcement', ENFORCEMENT_WHAT, fillTemplate(ENFORCEMENT_APPLY_TEMPLATE, { root: q(root), kit: q(ENFORCEMENT_KIT_ROOT) }));
+    if (enforcementOffer(root, deps)) add('enforcement', ENFORCEMENT_WHAT, formsApply('enforcement', root));
   } catch (err) {
     skip('enforcement', err);
   }
@@ -992,20 +1017,20 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
     if (readReadLaneToggle(root, deps)) {
       // The lane is ON: converged IFF the placed hook is byte-current — a stale (pre-1.48) hook never
       // reads lanes.json, so the enabled lane is a silent no-op the user must reseed (council B7). The
-      // rm target is ABSOLUTE (council R2-M3) so running the recovery from any cwd can only delete this
-      // repo's hook.
+      // reseed route pins the ABSOLUTE root (council R2-M3), so running it from any cwd can only
+      // replace this repo's hook.
       const currency = readPlacedHookCurrency(root, deps);
       if (currency === HOOK_CURRENCY.CURRENT) return; // converged
       if (currency === HOOK_CURRENCY.ABSENT) {
         // The survey saw it placed and it is gone by the time we read it. The missing arm is the
-        // honest report of that; a reseed recovery whose `rm` targets nothing is not.
+        // honest report of that; a reseed recovery, which refuses an absent hook, is not.
         placeRecovery();
         return;
       }
       // ONE render per condition — and the item that renders is the one whose CAUSE is true. A hook
       // that postdates the read-lane but predates the marker key reads lanes.json perfectly well, so
       // this arm's "an old hook never reads lanes.json" would be a false diagnosis over it, while the
-      // marker arm's is exact. Both carry the same remove-then-reseed recovery, so deferring costs
+      // marker arm's is exact. Both carry the same reseed recovery, so deferring costs
       // the reader nothing and buys a true sentence. The condition is that the marker arm REALLY
       // rendered — never the conditions it would have used, re-derived here: each probe reads the
       // placed hook itself, so a hook changing between the two reads could otherwise have both defer
@@ -1014,7 +1039,7 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
       add(
         'read-lane',
         fillTemplate(WHATS['read-lane.stale'], {}),
-        `HAND-APPLY: rm ${q(join(root, GATE_HOOK_REL))}, then node ${q(toolPath('gate-hook.mjs'))} --apply --cwd ${q(root)}`,
+        `node ${q(toolPath('gate-hook.mjs'))} --apply --reseed --cwd ${q(root)}`,
         'read-lane.stale',
       );
       return;
@@ -1027,18 +1052,17 @@ const probeReadLane = ({ root, deps, add, skip, shared }) => {
 
 // The state-block-guard offer (AD-075 · OPT-IN-SHIPS-INVISIBLE). This item exists because its absence
 // fired: 3.14.0 shipped the detector with a mode doc, a catalog row and a README row — and no advisor
-// entry — so `upgrade` reported «nothing is broken» to a user who did not have it. There is no writer
-// for this hook, so the apply is a HAND-APPLY pointer at the mode doc, which carries the exact block
-// and the three merge cases.
+// entry — so `upgrade` reported «nothing is broken» to a user who did not have it. Its writer is
+// state-block-hook.mjs; convergence is that leaf's own isStopHookWired over both settings files.
 const probeStateBlockHook = ({ root, deps, add, skip }) => {
   try {
     const project = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root });
     const local = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root });
-    if (isStateBlockGuardWired(project.data) || isStateBlockGuardWired(local.data)) return; // converged
+    if (isStopHookWired(project.data) || isStopHookWired(local.data)) return; // converged
     add(
       'state-block',
       fillTemplate(WHATS['state-block'], {}),
-      `HAND-APPLY: add a Stop hook running ${STATE_BLOCK_HOOK_COMMAND} to ${SETTINGS_FILE} — the exact block and the three merge cases are in references/modes/state-block-guard.md`,
+      `node ${q(toolPath('state-block-hook.mjs'))} --apply --cwd ${q(root)}`,
     );
   } catch (err) {
     skip('state-block', err);
@@ -1215,28 +1239,9 @@ export const READ_LANE_KEY = 'readLane';
 const GATE_HOOK_REL = '.claude/hooks/agent-workflow-gates.mjs';
 const BUNDLED_HOOK_ABS = join(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
 
-// The state-block-guard wiring the advisor looks for. Matched on the RUNTIME FILE NAME inside the
-// command, not on an exact string: the hook has no writer, so every user pastes their own path —
-// a copy under `.claude/hooks/`, a kit-source path, `--require-block` or not. Any Stop entry that
-// runs this runtime counts as wired, which is the honest question ("is it watching?").
-export const STATE_BLOCK_HOOK_RUNTIME = 'state-block-guard.mjs';
-// NO `--require-block` in the offered command. That flag turns on the absent-block report, and this
-// kit does not mandate the three-part closing block — recommending it to every project would hand
-// them a hook that warns after nearly every turn. The mode doc explains when to add it. (Offering the
-// strict flag by default would also contradict the very reason the report was made opt-in.)
-export const STATE_BLOCK_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${STATE_BLOCK_HOOK_RUNTIME}"`;
-const runsStateBlockGuard = (hook) => typeof hook?.command === 'string' && hook.command.includes(STATE_BLOCK_HOOK_RUNTIME);
-// Both entry shapes count. The matcher-group form (an object carrying its own `hooks` array) is what
-// this family ships and what was observed firing; a flat entry is accepted too, because the question
-// this probe answers is "is anything watching?" — and guessing NO for a wiring that works would nag
-// someone who already did the work.
-const isStateBlockGuardWired = (data) => {
-  const entries = data?.hooks?.Stop;
-  if (!Array.isArray(entries)) return false;
-  return entries.some((entry) => (Array.isArray(entry?.hooks)
-    ? entry.hooks.some(runsStateBlockGuard)
-    : runsStateBlockGuard(entry)));
-};
+// The state-block-guard wiring the advisor looks for is the writer leaf's own rule (any Stop entry of
+// either settings file running the runtime); the two constants are re-exported for their readers.
+export { STATE_BLOCK_HOOK_COMMAND, STATE_BLOCK_HOOK_RUNTIME };
 
 // The placed gate hook's currency, as the states a caller must tell APART (D8). Read through the
 // writer-class fail-closed no-follow primitive, never a bare readFile: a byte-compare that FOLLOWS a