@sabaiway/agent-workflow-kit 14.33.0 → 14.35.0

package/tools/mcp.mjs

@@ -22,21 +22,21 @@
 //   • the preflight is READ-ONLY: an absent `.claude/` is a NAMED state, and the dir is created on
 //     `--apply` only (assertCreatableDirSafe mkdirs, so it may not run in a preview);
 //   • a MASKED target (an OS sandbox injects a character device where `.mcp.json` would be — this
-//     repo is exactly that case) is not a failure: the kit hands over both paste-ready fragments,
-//     writes nothing, and exits 0. Where it cannot write, it says precisely what it would have.
+//     repo is exactly that case) is not a failure: the kit writes nothing, exits 0 and names the
+//     advisor's mcp-channel item, whose check line re-judges outside the sandbox;
 //   • never `settings.local.json`; never commits.
 //
 // The read half lives in mcp-registration.mjs, which the advisor and `uninstall` use — so what is
 // there and what would be written are computed by one module, never by two that can disagree.
 //
-// Exit codes: 0 done / dry-run (incl. the hand-apply masked state); 1 precondition STOP; 2 usage.
+// Exit codes: 0 done / dry-run (incl. the masked state); 1 precondition STOP; 2 usage.
 // Dependency-free beyond the kit's own exports, Node >= 22. No side effects on import.
 
 import {
   lstatSync, openSync, closeSync, fstatSync, writeFileSync, ftruncateSync, fsyncSync,
   renameSync, constants,
 } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { assertCreatableDirSafe, writeContainedFileAtomic } from './atomic-write.mjs';
 import { isDirectRun } from './direct-run.mjs';
@@ -46,7 +46,6 @@ import {
   CLAUDE_DIR_REL,
   ENABLED_KEY,
   MCP_JSON_REL,
-  SERVERS_KEY,
   SERVER_NAME,
   SETTINGS_REL,
   STATE,
@@ -54,9 +53,9 @@ import {
   mergeMcpJson,
   mergeSettings,
   readRegistration,
-  renderFragments,
 } from './mcp-registration.mjs';
 import { shellQuoteArg } from './review-state.mjs';
+import { applySlot } from './write-lanes.mjs';
 
 const q = shellQuoteArg;
 
@@ -83,7 +82,8 @@ Default is --dry-run (a preview that prints the exact entry and writes nothing).
 
 Without --replace, an existing "${SERVER_NAME}" entry that STRUCTURALLY DIFFERS is refused unwritten (key
 order is ignored). Where ${MCP_JSON_REL} is a device node, FIFO or socket — an OS sandbox
-mask is the usual cause — the entry to merge is printed and nothing is written.
+mask is the usual cause — nothing is written, and the report names the advisor's mcp-channel
+item, which applies the registration by the consent route.
 Never writes settings.local.json; never commits.`;
 
 export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
@@ -105,9 +105,9 @@ const lstatNoFollow = (path, lstat = lstatSync) => {
 // A target we could not read or parse is never overwritten: a merge over a file whose current
 // content is unknown is a clobber wearing a merge's name.
 //
-// `maskedAllowed` is TRUE for `.mcp.json` alone. That file has a sanctioned handoff — the kit hands
-// over the entry for a human to merge from outside the sandbox — and `settings.json` has none, so a
-// mask there is an ordinary refusal rather than a second, unplanned success path.
+// `maskedAllowed` is TRUE for `.mcp.json` alone. That file has a sanctioned route — the advisor's
+// mcp-channel item, whose check line re-judges outside the sandbox — and `settings.json` has none, so
+// a mask there is an ordinary refusal rather than a second, unplanned success path.
 const assertTargetUsable = (target, { maskedAllowed = false } = {}) => {
   if (target.state === STATE.MASKED) {
     if (maskedAllowed) return;
@@ -168,7 +168,7 @@ export const preflightMcp = ({ cwd, replace = false }, deps = {}) => {
 };
 
 // The plan is pure over the registration: what is missing, and the exact body each file would get.
-// Both bodies are built even when nothing is written — they ARE the preview and the hand-apply text.
+// Both bodies are built even when nothing is written — they ARE the preview.
 export const planMcp = (registration) => ({
   writeMcpJson: !registration.mcpJson.matches,
   writeSettings: !registration.settings.complete,
@@ -225,9 +225,8 @@ const writeTarget = (root, target, body, deps, stop) => {
 
 export const writeMcp = ({ cwd, dryRun = true, replace = false } = {}, deps = {}) => {
   const preflight = preflightMcp({ cwd: cwd ?? deps.cwd ?? process.cwd(), replace }, deps);
-  const base = { ...preflight, dryRun, wrote: false };
-  if (preflight.masked) return { ...base, fragments: renderFragments(preflight.registration) };
-  if (dryRun) return base;
+  const base = { ...preflight, dryRun, replace, wrote: false };
+  if (preflight.masked || dryRun) return base;
 
   const { root, registration, plan } = preflight;
   const stop = (message) => makeMcpError(MCP_SYMLINK, message);
@@ -286,19 +285,19 @@ const settingsLine = (result) => {
   return `  - ${SETTINGS_REL}: ${dryRun ? 'would set' : 'set'} ${parts.join(' · ')}`;
 };
 
-// The hand-apply text. The two halves are worded differently because the kit KNOWS different things
-// about them: the settings body is a real merge over content it read, while the `.mcp.json` half is
-// the entry ALONE — behind the mask this mode cannot see what that file already declares, and a
-// whole-file body pasted as instructed would delete every server it could not see.
+// The masked report names the item that applies the registration by the consent route: its check
+// line, run once more outside the sandbox, reads the real file this mode cannot see through the mask.
+// A run under --replace routes through the differing arm, whose check and apply carry the replace.
 const maskedReport = (result) => {
   const target = result.registration.mcpJson;
+  const variant = result.replace ? 'mcp-channel.differing' : 'mcp-channel';
+  const { check, apply } = applySlot(variant, { toolsDir: dirname(MCP_TOOL), root: result.root });
   return [
     // The CLASS is what was observed; the sandbox mask is the usual CAUSE but is not established here.
-    `agent-workflow MCP registration — HAND-APPLY: ${MCP_JSON_REL} is a ${target.className} (an OS sandbox device mask is the usual cause), so nothing was written.`,
-    `  merge this entry into ${MCP_JSON_REL} under "${SERVERS_KEY}", and keep every other server it already declares (this mode cannot read them through the mask):`,
-    indented(`"${SERVER_NAME}": ${result.fragments.mcpEntry.trimEnd()}`),
-    `  merge into ${SETTINGS_REL} (that file was observable — and read where present — so this body already carries what is in it):`,
-    indented(result.fragments.settings),
+    `agent-workflow MCP registration — nothing was written: ${MCP_JSON_REL} is a ${target.className} (an OS sandbox device mask is the usual cause).`,
+    "  the advisor's mcp-channel item applies the registration by the consent route — its check line runs once more outside the sandbox and the apply line runs on the yes given on that result:",
+    `  check: ${check}`,
+    `  apply: ${apply}`,
     POSTURE_LINE,
     HIDDEN_MODE_LINE,
   ].join(LF);

package/tools/recommendations.mjs

@@ -55,7 +55,7 @@ import { surveyFamily, surveyGateHook, surveyAdrLayoutStrict } from './family-re
 import { probeSandboxMasks, needsMasksApply, patternToRel } from './sandbox-masks.mjs';
 import { shellQuoteArg } from './review-state.mjs';
 import { isFinalCapableDeclaration } from './run-gates.mjs';
-import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, GATES_REL, LCOV_PRODUCER_KEY } from './gates-declaration.mjs';
+import { loadDeclaration, canonicalCheckerGates, coverageProducerPrecedes, isKitOwnedCheckerGate, LCOV_PRODUCER_KEY } from './gates-declaration.mjs';
 import { readRegularFileNoFollow } from './fs-read-nofollow.mjs';
 // The typed channel's READ-ONLY leaf only — never tools/mcp.mjs, which reaches the write core.
 import {
@@ -75,16 +75,19 @@ import { CHECKER_CLAIM, INITIAL_ADOPTION_REASON, SOURCE_SIZE_GATE_ID, classifySo
 // The declared-path resolution + segment containment this item's convergence lane shares with the
 // autonomy render's allowWrite degrade — ONE leaf, so the two answers cannot drift.
 import { resolveDeclaredDir, dirCovers, isResolvableDeclaredEntry } from './declared-paths.mjs';
-import { resolveGitHooksPath } from './commit-guard.mjs';
+import { readPreCommitState } from './git-hooks.mjs';
+export { resolveGitHooksPath, readPreCommitState, canonicalGuardLineRe, INSTALLER_MARKER_RE } from './git-hooks.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { homeRelative } from './bridge-state-dirs.mjs';
 import { sandboxEnabled, HOST_HONORS_QUALIFIER } from './bridge-wiring.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.mjs';
-import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
+import { preflightCheapAgents, writeCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
+import { ATTRIBUTION_KEY, LEGACY_ATTRIBUTION_KEY, attributionHidesText, effectiveAttribution, readAttributionChoice, wrongTypedKey } from './attribution.mjs';
+import { planGlobalRemoval } from './hide-footprint.mjs';
 import { NODE_EVIDENCE, NODE_EVIDENCE_SCRIPTS, probeNodeEvidence } from './node-evidence.mjs';
 // The vehicle READINESS comes from the read-only half — the same survey `recipes` and `status` read.
-import { surveyExecutorVehicle, readExecutorPosture, executorTemplate, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
+import { surveyExecutorVehicle, readExecutorPosture, executorBodyDiffers, executorTemplate, readStamp, readFsDeps, WORKFLOW_STAMP, EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
 // The ack store's path, keys, lane registry, fingerprint and guarded reader live in their own leaf
 // (contract: kit/ack-store) — `status` reads the same store, and a second copy is what drifts.
 import {
@@ -116,6 +119,8 @@ export { ACKS_FILE, ACKS_LANE_KEY, ACKS_WORKTREES_DIR_KEY, ACKS_COVERAGE_DOMAIN_
 const HERE = dirname(fileURLToPath(import.meta.url));
 const toolPath = (rel) => join(HERE, rel);
 const q = shellQuoteArg;
+// A user variant's own step, as the lane leaf words it: the rendered apply of every user item.
+const userStepOf = (variant, root) => applySlot(variant, { toolsDir: HERE, root }).apply;
 const ABSENT_CODE = 'ENOENT';
 const ENFORCEMENT_KIT_ROOT = resolve(HERE, '..');
 const ENFORCEMENT_BUNDLE_ROOT = join(ENFORCEMENT_KIT_ROOT, 'references', 'scripts');
@@ -160,6 +165,7 @@ export const SEVERITIES = Object.freeze({
   'review-recipe': SEVERITY_ATTENTION,
   'gates-declaration': SEVERITY_OPTIONAL,
   'gates-inert': SEVERITY_ATTENTION,
+  'gates-inert.unfillable': SEVERITY_ATTENTION,
   'gates-inert.no-verification': SEVERITY_ATTENTION,
   // Both third outcomes are attention, and both therefore block the flow-optimal line MECHANICALLY:
   // an added item makes the verdict non-null. One reports a pair that is dead on a tree the closed
@@ -194,6 +200,12 @@ export const SEVERITIES = Object.freeze({
   // names the subagent carrier over a vehicle that cannot carry it — a configured declaration that
   // is broken, which is what attention means.
   'executor-vehicle': SEVERITY_ATTENTION,
+  // A hand edit of the placed executor is not a broken declaration — the vehicle still carries — so
+  // re-deriving it is an offer.
+  'executor-vehicle.differing': SEVERITY_OPTIONAL,
+  // The AGENTS.md block is a configured choice the harness does not honour.
+  attribution: SEVERITY_ATTENTION,
+  'footprint-global': SEVERITY_OPTIONAL,
   'family-freshness': SEVERITY_ATTENTION,
   'adr-store-migration': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
@@ -246,6 +258,7 @@ export const composeVerdict = ({ attention, optional, skipped }) => {
 // banned tokens), never a fixture-coverage gamble. A pure-placeholder template marks a WHAT whose
 // content is fully dynamic (capped at composition by truncation-with-count) — except `profile-gap`, whose
 // WHAT is never truncated: the leaf's suite pins every composed WHAT under the cap.
+const GATES_INERT_WHAT = 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov';
 export const WHATS = Object.freeze({
   'velocity-core': 'routine read-only commands still prompt — {n} audited read-only allowlist entr(ies) not seeded',
   'velocity-core.rule': 'auto mode refuses a harness apply, so work cannot stay in auto mode — the apply ask rule is not seeded',
@@ -258,7 +271,8 @@ export const WHATS = Object.freeze({
   'sandbox-provision.installable': 'the OS sandbox is unavailable: {reason} — installable via the doctor (consent tuple {tuple})',
   'review-recipe': '{degraded}',
   'gates-declaration': 'no declared gate matrix (docs/ai/gates.json absent or empty) — gates prompt one by one; the apply PREVIEWS its --apply line, writes nothing',
-  'gates-inert': 'the declared coverage checker ({id}) has no producer before it — it certifies nothing this run, or reads a stale lcov',
+  'gates-inert': GATES_INERT_WHAT,
+  'gates-inert.unfillable': GATES_INERT_WHAT,
   'gates-inert.no-verification': "all {n} declared gate(s) are the kit's own checkers — the matrix runs no project-verification command",
   'gates-inert.producer-unrecognized': 'the coverage checker ({id}) has NO producer declared and none offerable, on a tree the changed-line domain barely reaches',
   'gates-inert.coverage-domain-narrow': 'certification covers the assessable minority only — {ext} dominate(s) the tracked tree, and the changed-line domain excludes them',
@@ -278,6 +292,9 @@ export const WHATS = Object.freeze({
   'mcp-channel.differing': 'an "{server}" MCP entry is already declared here and DIFFERS from the registration this kit copy would write',
   agents: '{n} bundled subagent vehicle(s) not placed (Claude Code) — {ro} read-only, {ex} the full-tool executor; the apply PREVIEWS first',
   'executor-vehicle': '{n} slot(s) configured subagent but the executor vehicle is {state}{reason} — every such slot runs solo until it is usable',
+  'executor-vehicle.differing': 'the placed executor vehicle differs from the body derived from docs/ai/vehicles.json — a hand edit stands until it is re-derived',
+  attribution: 'AGENTS.md says attribution off but .claude/settings.json does not hide the harness trailer and PR text',
+  'footprint-global': 'legacy kit ignore line(s) sit in {file} — they ignore kit paths in every repository here',
   'family-freshness': '{parts}',
   'adr-store-migration': 'still on the retired 3-tier ADR layout — {shape}',
   'sandbox-masks': '{n} sandbox mask(s) clutter git status — the managed exclude block is absent or stale',
@@ -343,6 +360,8 @@ export const BENEFITS = Object.freeze({
   'mcp-channel': 'velocity — path facts and literal searches arrive as typed tool calls whose arguments are JSON fields, never a shell string',
   agents: 'cost and quiet — cheap-model mechanical work, no shell on a read-only vehicle (no prompt flood); the executor carries slices you verify',
   'executor-vehicle': 'carrier readiness — a slot you configured subagent dispatches the subagent it names instead of silently running solo',
+  attribution: 'attribution — the harness adds no Co-Authored-By trailer, PR text or session link, as your AGENTS.md block requires',
+  'footprint-global': 'hygiene — the legacy machine-global excludes stop ignoring kit paths in every other repository on this host',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'adr-store-migration': 'durability — every decision becomes its own file with a generated navigator, instead of one hand-rotated pile',
   'sandbox-masks': 'zero clutter — a mask git ignores through the block leaves git status; a mount-only one leaves git add -A and the review fingerprint too',
@@ -352,6 +371,10 @@ export const BENEFITS = Object.freeze({
   'jev-connect': 'decisions — a typed choice with a confidence in under a second for your code and the agent\'s scripts, once for every project here',
   'jev-skill': 'the TypeSafe skill for Claude Code, Codex and Antigravity CLI, one pinned verified copy per agent root, from one command you run',
 });
+// The one arm whose gain differs from its base item's (BENEFITS stays keyed by item key).
+export const VARIANT_BENEFITS = Object.freeze({
+  'executor-vehicle.differing': 'carrier fidelity — the placed executor runs the model and effort docs/ai/vehicles.json names, not a hand edit',
+});
 
 // ── the CLOSED opt-in capability registry (OPT-IN-SHIPS-INVISIBLE) ──────────────────────────────
 // 3.14.0 shipped a capability with every surface an AGENT reads and NO advisor entry, so `upgrade`
@@ -388,6 +411,8 @@ export const OPT_IN_CAPABILITIES = Object.freeze([
   { id: 'read-lane', mode: 'hook', advisorKey: 'read-lane' },
   { id: 'commit-guard', mode: 'commit-guard', advisorKey: 'commit-guard' },
   { id: 'enforcement', mode: 'bootstrap', advisorKey: 'enforcement' },
+  { id: 'attribution', mode: 'bootstrap', advisorKey: 'attribution' },
+  { id: 'footprint-global', mode: 'bootstrap', advisorKey: 'footprint-global' },
   { id: 'state-block', mode: 'state-block-guard', advisorKey: 'state-block' },
   { id: 'sandbox-masks', mode: 'sandbox-masks', advisorKey: 'sandbox-masks' },
   { id: 'mcp-channel', mode: 'mcp', advisorKey: 'mcp-channel' },
@@ -568,7 +593,8 @@ const probeReviewRecipe = ({ root, deps, add, skip }) => {
       }
     }
     if (degraded.length > 0) {
-      add('review-recipe', fillTemplate(WHATS['review-recipe'], { degraded: capList(degraded, templateBudget(WHATS['review-recipe'])) }), '/agent-workflow-kit backends');
+      add('review-recipe', fillTemplate(WHATS['review-recipe'], { degraded: capList(degraded, templateBudget(WHATS['review-recipe'])) }),
+        userStepOf('review-recipe', root));
     }
   } catch (err) {
     skip('review-recipe', err);
@@ -631,8 +657,8 @@ const probeGates = ({ root, deps, add, skip, shared }) => {
 // gate is not a kit checker. Cause A's apply follows what the FILL can actually do, which the
 // D-8 placement rule changed: when the checker is the declaration's LAST gate and the project's own
 // scripts yield an offerable producer, the fill now PLACES that producer before the checker, so the
-// remedy is the ordinary consent-gated preview. HAND-APPLY remains exactly where no offerable
-// producer exists, or where the checker is not last — there the edit really is the maintainer's,
+// remedy is the ordinary consent-gated preview. Where no offerable producer exists, or the checker
+// is not last, the arm is the user item `gates-inert.unfillable` — the edit is the project's own,
 // because the fill never reorders entries it did not write.
 //
 // An ABSENT or EMPTY declaration belongs to the gates-declaration item; a malformed one throws out
@@ -745,8 +771,9 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
           add(
             'gates-inert',
             fillTemplate(WHATS['gates-inert.producer-unrecognized'], { id }),
-            `HAND-APPLY: mark the gate that actually writes the lcov with "lcovProducer": true in ${GATES_REL} (references/modes/gates.md names the key), or drop ${id} — and note the fill offers only terminating-class script NAMES, so a recognized body under another name (a "ci" script running node --test) is declared by hand, not marked`,
+            userStepOf('gates-inert.producer-unrecognized', root),
             'gates-inert.producer-unrecognized',
+            `${id} has no producer declared and none offerable — the fill offers only terminating-class script names, so a recognized body under another name (a "ci" script running node --test) is declared as its own gate entry, never marked`,
           );
           return;
         }
@@ -768,13 +795,12 @@ export const probeGatesInert = ({ root, deps, add, skip }) => {
         : colliding !== undefined
           ? `a producer IS offerable here, but its id "${colliding.id}" is already declared, so the fill refuses it as a collision — rename that gate, or repoint it at the producer form`
           : `no offerable producer exists here, and the fill never reorders entries it did not write`;
-      add(
-        'gates-inert',
-        fillTemplate(WHATS['gates-inert'], { id }),
-        checkerIsLast && producer
-          ? fillPreviewFor(root, [producer.id])
-          : `HAND-APPLY: declare or MOVE a suite gate carrying the coverage reporters BEFORE ${id} in ${GATES_REL} (references/modes/gates.md names the exact form), or drop ${id} — ${blocked}`,
-      );
+      if (checkerIsLast && producer) {
+        add('gates-inert', fillTemplate(WHATS['gates-inert'], { id }), fillPreviewFor(root, [producer.id]));
+        return;
+      }
+      add('gates-inert', fillTemplate(WHATS['gates-inert.unfillable'], { id }), userStepOf('gates-inert.unfillable', root),
+        'gates-inert.unfillable', blocked);
       return;
     }
     // The source-size checker is one of the kit's OWN checkers, and it is deliberately NOT
@@ -867,15 +893,11 @@ const probeSourceSize = ({ root, deps, add, skip }) => {
     }
     // The id SQUATTER — the id says the practice is declared, the cmd is not this checker under any
     // reading. `--adopt` here mints the record and is then refused by the fill on the id collision:
-    // correct against a squatter, and useless as a RENDERED remedy, so this arm names the two hand
-    // edits that actually resolve it instead.
+    // correct against a squatter, and useless as a RENDERED remedy, so this arm is a user item whose
+    // step names the edits that actually resolve it.
     if (gates.some((gate) => gate.id === SOURCE_SIZE_GATE_ID)) {
-      add(
-        'source-size',
-        fillTemplate(WHATS['source-size.id-squatter'], {}),
-        `HAND-APPLY: in ${GATES_REL}, either rename the "${SOURCE_SIZE_GATE_ID}" gate to an id of its own, or repoint its cmd at node ${q(tool)} --check — then re-run recommendations`,
-        'source-size.id-squatter',
-      );
+      add('source-size', fillTemplate(WHATS['source-size.id-squatter'], {}), userStepOf('source-size.id-squatter', root),
+        'source-size.id-squatter');
       return;
     }
     add('source-size', fillTemplate(WHATS['source-size'], {}), adoptLine);
@@ -890,27 +912,11 @@ const probeSourceSize = ({ root, deps, add, skip }) => {
 // 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;
-const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// Convergence needs the EXACT canonical armed line the installer writes — full-line anchored on
-// 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) };
+// The advisor asks git under its own process env; only the commit-guard apply passes the installer's.
+const readHookState = (root, deps) => {
+  const hook = readPreCommitState(root, { ...deps, env: undefined });
+  if (hook.state === 'unreadable') throw new Error(`${hook.path} is unreadable (${hook.code}) — the pre-commit hook cannot be judged`);
+  return hook;
 };
 const formsApply = (variant, root) => consoleArgv(variant, { toolsDir: HERE, root }).apply.map(q).join(' ');
 const probeCommitGuard = ({ root, deps, add, skip }) => {
@@ -931,7 +937,7 @@ const probeCommitGuard = ({ root, deps, add, skip }) => {
       skip('commit-guard', new Error(enforcementAdmits(root, deps) ? COMMIT_GUARD_INSTALLER_VIA_ITEM : COMMIT_GUARD_INSTALLER_OWN_STEP));
       return;
     }
-    const { state, armed } = readPreCommitState(root, deps);
+    const { state, armed } = readHookState(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));
@@ -977,7 +983,7 @@ const enforcementOffer = (root, deps) => {
     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);
+  if (readHookState(root, deps).state === 'unmanaged') throw new Error(ENFORCEMENT_UNMANAGED_HOOK);
   return true;
 };
 
@@ -1125,16 +1131,31 @@ const writerBlock = (root, deps) => {
   }
 };
 
+const HIDDEN_AGENTS_FOLLOW_UP = (root) => `hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`;
+
 const probeExecutorVehicle = ({ root, deps, add, skip }) => {
+  if (renderBrokenExecutor({ root, deps, add, skip })) return;
+  try {
+    if (!executorBodyDiffers(root, deps)) return;
+    const plan = writeCheapAgents({ cwd: root, dryRun: true }, deps);
+    if (!plan.stampOk) throw new Error(`run /agent-workflow-kit upgrade first (deployment stamp ${plan.stamp ?? 'none'}, expected ${EXPECTED_WORKFLOW_VERSION})`);
+    add('executor-vehicle', WHATS['executor-vehicle.differing'], formsApply('executor-vehicle.differing', root),
+      'executor-vehicle.differing', HIDDEN_AGENTS_FOLLOW_UP(root));
+  } catch (err) {
+    skip('executor-vehicle', err);
+  }
+};
+
+const renderBrokenExecutor = ({ root, deps, add, skip }) => {
   try {
     // The VALIDATED reader, as probeReviewRecipe uses it: a schema-invalid config is a stated skip,
     // never an item computed over a shape nothing accepted.
     const { config } = loadConfig(root, deps.readFile ?? readFileSync, deps.lstat ?? lstatSync);
     const configured = Object.entries(ACTIVITIES).flatMap(([activity, def]) =>
       Object.keys(def.slots).filter((slot) => config?.[activity]?.[slot] === 'subagent'));
-    if (configured.length === 0) return;
+    if (configured.length === 0) return false;
     const survey = (deps.surveyVehicle ?? surveyExecutorVehicle)(root, deps);
-    if (!VEHICLE_BROKEN_STATES.includes(survey.state)) return;
+    if (!VEHICLE_BROKEN_STATES.includes(survey.state)) return false;
     const reason = safeLine(survey.reason ?? '');
     const { posture, reason: settingsReason } = readExecutorPosture(root, deps);
     const stamp = readStamp(join(root, WORKFLOW_STAMP), readFsDeps(deps));
@@ -1158,10 +1179,12 @@ const probeExecutorVehicle = ({ root, deps, add, skip }) => {
       // frontmatter or read-only tools included), so those states need no precondition; every precondition above is a refusal the apply would meet.
       `node ${q(toolPath('cheap-agents.mjs'))} --apply --cwd ${q(root)}`,
       'executor-vehicle',
-      `${preconditions.length ? `precondition: ${preconditions.join('; ')}; ` : ''}hidden-mode deployments only: after the apply, run node ${q(toolPath('hide-footprint.mjs'))} --dir ${q(root)} --reconcile so the placed .claude/agents/ stays invisible to git status`,
+      `${preconditions.length ? `precondition: ${preconditions.join('; ')}; ` : ''}${HIDDEN_AGENTS_FOLLOW_UP(root)}`,
     );
+    return true;
   } catch (err) {
     skip('executor-vehicle', err);
+    return true;
   }
 };
 
@@ -1314,7 +1337,7 @@ const readReadLaneToggle = (root, deps) => {
 // D3: the risk-marked keys — every key here has a per-item posture note in the mode doc, surfaced
 // at the consent moment; the static contract test asserts EXACT bidirectional coverage
 // (risk-marked keys == mode-doc note keys — a dropped note goes red, not silent).
-export const RISK_NOTED_KEYS = Object.freeze(['bridge-tier', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement', 'profile-gap', 'jev-connect', 'jev-skill']);
+export const RISK_NOTED_KEYS = Object.freeze(['bridge-tier', 'read-lane', 'worktrees-dir', 'adr-store-migration', 'gates-inert', 'source-size', 'gate-hook', 'mcp-channel', 'spec-adoption', 'enforcement', 'profile-gap', 'jev-connect', 'jev-skill', 'attribution', 'footprint-global']);
 
 // The feature-spec layer's adoption state (contract: kit/spec-adoption). The canon lets a plan cite
 // zero governing specs while a project adopts the layer, and nothing ever said whether adoption had
@@ -1322,6 +1345,8 @@ export const RISK_NOTED_KEYS = Object.freeze(['bridge-tier', 'read-lane', 'workt
 // spec-check's own census; a recorded decline (the `spec-adoption` ack lane) is the fact that
 // silences the item, and an unreadable store is a stated skip so the flow-optimal line never renders
 // over it. The not-adopted apply is the spec-layer ensure; the decline preview rides the recipe line.
+// The one opening of every offer's decline alternative: a chat write the agent runs on the user's decline.
+export const DECLINE_ALTERNATIVE = 'decline alternative (asked apart, before the confirmation; on your decline the agent records it instead of the apply, never after it): ';
 export const probeSpecAdoption = ({ root, deps, add, skip }) => {
   try {
     const survey = surveySpecAdoption(root, deps);
@@ -1337,7 +1362,7 @@ export const probeSpecAdoption = ({ root, deps, add, skip }) => {
         fillTemplate(WHATS['spec-adoption'], {}),
         `node ${q(toolPath('ensure-configs.mjs'))} --reconcile --only ${SPEC_LAYER_ENSURE} --cwd ${q(root)}`,
         'spec-adoption',
-        `HAND-APPLY alternative (instead of the apply, never after it): decline the layer by recording it — ${decline}`,
+        `${DECLINE_ALTERNATIVE}${decline}`,
       );
       return;
     }
@@ -1457,13 +1482,12 @@ export const probeAdrStore = ({ root, deps, add, skip }) => {
   try {
     const shape = ADR_LAYOUT_SHAPES[surveyAdrLayoutStrict(root, deps)];
     if (!shape) return; // migrated, or no ADR substrate at all — nothing to offer
-    // HAND-APPLY, not the standard lane: the consent flow executes the apply slot against the
-    // confirmation given BEFORE the preview, and this crossing requires informed consent AFTER its
-    // dry-run. A runnable one-liner here would auto-run a tree-mutating migration on stale consent.
+    // The apply is the bare dry run: consent takes two steps, as profile-gap's does — the first yes
+    // runs it and the plan is relayed, the same line with --apply runs only on a second yes over it.
     add(
       'adr-store-migration',
       fillTemplate(WHATS['adr-store-migration'], { shape }),
-      `HAND-APPLY: node ${q(toolPath('migrate-adr-store.mjs'))} --dry-run --cwd ${q(root)} — then re-run with --apply ONLY after showing the plan and getting fresh consent`,
+      `node ${q(toolPath('migrate-adr-store.mjs'))} --dry-run --cwd ${q(root)}`,
     );
   } catch (err) {
     skip('adr-store-migration', err);
@@ -1514,7 +1538,7 @@ export const probeJevConnect = ({ root, deps, add, skip }) => {
     const place = placeOf({ env, platform: host.platform, hostname: host.hostname, container: host.container });
     const decline = `node ${q(toolPath('ack-write.mjs'))} --lane jev-connect --fingerprint ${JEV_CONNECT_DECLINE} --cwd ${q(root)}`;
     add('jev-connect', WHATS['jev-connect'], applySlot('jev-connect', { toolsDir: HERE }).apply, 'jev-connect',
-      `${place ? `run the apply in ${place}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
+      `${place ? `run the apply in ${place}; ` : ''}${DECLINE_ALTERNATIVE}${decline}`);
   } catch (err) {
     skip('jev-connect', err);
   }
@@ -1548,7 +1572,7 @@ export const probeJevSkill = ({ root, deps, add, skip }) => {
       .map(({ path, reason }) => `left untouched: ${printable(path)} — ${printable(reason)}; `).join('');
     const record = `node ${q(toolPath('ack-write.mjs'))} --lane jev-skill --fingerprint ${decline} --cwd ${q(root)}`;
     add('jev-skill', what, line, behind.length ? 'jev-skill.earlier' : 'jev-skill',
-      `${place ? `run the apply in ${place}; ` : ''}${untouched}${note ? `${note}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${record}`);
+      `${place ? `run the apply in ${place}; ` : ''}${untouched}${note ? `${note}; ` : ''}${DECLINE_ALTERNATIVE}${record}`);
   } catch (err) {
     skip('jev-skill', err);
   }
@@ -1564,9 +1588,48 @@ export const probeProfileGaps = ({ root, deps, add, skip }) => {
   }
 };
 
+// The attribution item by its table (spec init-project, part in-session-writes): a choice of off the
+// effective settings do not honour; the writer's preflight runs before it renders, so no rendered check always exits 3.
+const probeAttribution = ({ root, deps, add, skip }) => {
+  try {
+    if (readAttributionChoice(root, deps) !== 'off') return;
+    const project = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root }).data;
+    const local = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root }).data;
+    const effective = effectiveAttribution(project, local);
+    if (attributionHidesText(effective)) return;
+    preflightVelocityProfile({ cwd: root }, deps);
+    for (const [file, data] of [[SETTINGS_FILE, project], [SETTINGS_LOCAL_FILE, local]]) {
+      const wrong = wrongTypedKey(data);
+      if (wrong) throw new Error(`${file}: ${wrong} — the attribution item cannot judge it`);
+    }
+    const setsText = (value) => value !== null && typeof value === 'object' && ['commit', 'pr'].some((key) => Object.hasOwn(value, key));
+    const localKey = Object.hasOwn(local ?? {}, ATTRIBUTION_KEY) && !attributionHidesText({ [ATTRIBUTION_KEY]: local[ATTRIBUTION_KEY] }) ? ATTRIBUTION_KEY
+      : local?.[LEGACY_ATTRIBUTION_KEY] === true && !setsText(effective[ATTRIBUTION_KEY]) ? LEGACY_ATTRIBUTION_KEY : null;
+    if (localKey) throw new Error(`${SETTINGS_LOCAL_FILE} sets ${localKey} so the harness adds its text — a local-scope override is your own edit`);
+    add('attribution', WHATS.attribution, formsApply('attribution', root));
+  } catch (err) {
+    skip('attribution', err);
+  }
+};
+
+// The leftover machine-global block: the one plan the hide reports and the --remove-global mode removes,
+// asked of git under the home the advisor was given.
+const probeFootprintGlobal = ({ root, deps, add, skip }) => {
+  try {
+    const home = deps.home ?? deps.jevHost?.home ?? homedir();
+    const plan = (deps.planGlobalRemoval ?? planGlobalRemoval)({ env: { ...process.env, HOME: home }, home }, root, { home });
+    if (plan === null) return;
+    const file = truncatedTo(plan.source, templateBudget(WHATS['footprint-global']));
+    add('footprint-global', fillTemplate(WHATS['footprint-global'], { file }), formsApply('footprint-global', root));
+  } catch (err) {
+    skip('footprint-global', err);
+  }
+};
+
 // ── assembly (frozen presentation order) ─────────────────────────────────────────────────────────
 const PROBES = Object.freeze([
   probeVelocityItems,
+  probeAttribution,
   probeAutonomyItems,
   probeSandboxProvision,
   probeReviewRecipe,
@@ -1582,6 +1645,7 @@ const PROBES = Object.freeze([
   probeFamilyFreshness,
   probeAdrStore,
   probeMasksItem,
+  probeFootprintGlobal,
   probeWorktreesDir,
   probeMcpChannel,
   probeSpecAdoption,
@@ -1604,10 +1668,9 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // which item fired, and only this field says which ARM of it did — so a consumer (the pre-publish
   // smoke asserting a specific false-green never returns) can assert the exact outcome instead of
   // pattern-matching prose that is free to be reworded.
-  // `detail` (optional) is an extra rendered `recipe:` line — factual context that is TOO LONG for
-  // the capped WHAT and does NOT belong in the pure-command apply (the bridge-tier missing-entries
-  // line; the worktrees-dir ack fallback; the
-  // agents hidden-mode reconcile follow-up). Single-line like apply; absent for every other item.
+  // `detail` (optional) is an extra rendered `recipe:` line — an item's own facts or its alternative,
+  // TOO LONG for the capped WHAT and outside the pure-command apply (such as the bridge-tier
+  // missing-entries line or the worktrees-dir ack fallback). Single-line like apply; absent otherwise.
   // Returns whether the item really RENDERED. One probe's disposition depends on another's having
   // spoken (the marker-stale ⟷ read-lane.stale precedence), and "the conditions still look right"
   // is not the same fact as "an item exists" — the shape backstop can refuse, and a condition read
@@ -1629,7 +1692,7 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
       home: deps.jevHost?.home ?? deps.home ?? '',
       platform: deps.jevHost?.platform ?? deps.platform,
     });
-    items.push({ key, variant, severity: SEVERITIES[variant], lane: laneOf(variant), what, benefit: BENEFITS[key],
+    items.push({ key, variant, severity: SEVERITIES[variant], lane: laneOf(variant), what, benefit: VARIANT_BENEFITS[variant] ?? BENEFITS[key],
       check: slot?.check ?? null, apply: slot?.apply ?? apply, detail });
     return true;
   };
@@ -1697,9 +1760,9 @@ Usage:
 
 Computes the deterministic Recommendations section every kit upgrade ends with — VERDICT-FIRST:
 one composed verdict line opens every non-optimal render, then per item {severity · what is
-sub-optimal · the benefit in one plain line · the lane · an optional \`recipe:\` line (the bridge-tier
-missing-entries line, the worktrees-dir ack fallback, or the agents hidden-mode reconcile
-follow-up) · the harness check line · the exact consent-gated apply one-liner}. --cwd is
+sub-optimal · the benefit in one plain line · the lane · an optional \`recipe:\` line (an item's own
+facts or its alternative, such as the bridge-tier missing-entries line or
+the worktrees-dir ack fallback) · the harness check line · the exact consent-gated apply one-liner}. --cwd is
 REQUIRED (the target project is explicit, never inferred from the shell's current directory). The
 section renders present-even-when-empty ("${RECOMMENDATIONS_EMPTY_LINE}"); a probe failure is a
 stated skipped-item line. Apply lines are cwd-independent (absolute tool paths, a pinned --cwd;
@@ -1710,8 +1773,8 @@ allow rules, <wrapper> * exclusions (codex-exec * where an execute slot delegate
 sandbox.network.allowedDomains and state dirs in sandbox.filesystem.allowWrite. Where the host
 honors the settings sandbox keys, an excluded wrapper runs outside the sandbox, every sandboxed
 command of the project can reach each host, and every sandboxed command can write each state dir;
-plan/diff review modes and delegated execution keep their prompt. Items marked HAND-APPLY stay
-the user's own step.
+plan/diff review modes and delegated execution keep their prompt.
+A user item stays the user's own step.
 
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;

package/tools/upgrade-runlist.mjs

@@ -40,7 +40,7 @@ export const UPGRADE_RUNLIST = Object.freeze([
       'note-refreshed',
       'refreshed',
       'regenerated',
-      're-derived',
+      'pending',
       'already-current',
       'customized-preserved',
       'malformed-preserved',