@sabaiway/agent-workflow-kit 14.32.0 → 14.34.0

package/tools/recommendations.mjs

@@ -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 { loadWorktreesConfig, resolveProbeDir } from './worktrees.mjs';
-import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.mjs';
+import { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.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 {
@@ -194,11 +197,18 @@ 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,
   'sandbox-masks.unfenced-mount': SEVERITY_ATTENTION,
   'worktrees-dir': SEVERITY_OPTIONAL,
+  'worktrees-dir.home': SEVERITY_OPTIONAL,
   // The layer is opt-in, so both arms are OFFERS under the frozen registry (attention is a CONFIGURED
   // declaration that is broken): an absent store offers the seed, a store with no live contract offers
   // the decline. Neither arm can leave the flow-optimal line standing — an offer is still an item.
@@ -277,11 +287,15 @@ 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',
   'sandbox-masks.stale-real': '{n} sandbox mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
   'worktrees-dir': 'write access to the worktrees parent dir {dir} is not confirmed — provision may still stop',
+  'worktrees-dir.home': 'the worktrees parent dir {dir} is the home or holds it — the kit grants no write surface there',
   'spec-adoption': 'feature-spec store absent (docs/ai/specs) — no feature contract can govern a plan here yet; seed the store, or record the decline',
   'profile-gap': '{what}',
   'jev-connect': 'Jev (TypeSafe) is not connected: TYPESAFE_API_KEY is not in the environment the agent\'s commands run in',
@@ -341,6 +355,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',
@@ -350,6 +366,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`
@@ -386,6 +406,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' },
@@ -888,27 +910,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 }) => {
@@ -929,7 +935,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));
@@ -975,7 +981,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;
 };
 
@@ -1123,16 +1129,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));
@@ -1145,7 +1166,7 @@ const probeExecutorVehicle = ({ root, deps, add, skip }) => {
     const blocked = writerBlock(root, deps);
     if (blocked) preconditions.push(`${blocked} — fix that`);
     const room = templateBudget(WHATS['executor-vehicle']) - String(configured.length).length - survey.state.length - 2;
-    add(
+    return add(
       'executor-vehicle',
       fillTemplate(WHATS['executor-vehicle'], {
         n: configured.length,
@@ -1156,10 +1177,11 @@ 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)}`,
     );
   } catch (err) {
     skip('executor-vehicle', err);
+    return false;
   }
 };
 
@@ -1312,7 +1334,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
@@ -1404,46 +1426,31 @@ const declaresWritableDir = (root, probeDir, deps) => {
 // existing ancestor resolve to the same dir and keep the same ack.
 export const worktreesDirFingerprint = (probeDir, home) => recipeFingerprint({ hosts: [], dirs: [probeDir], home });
 
-// The worktrees-dir arming item (parallel feature worktrees): fires when write access to the
-// resolved worktrees parent dir (docs/ai/worktrees.json parentDir, else the repo's own parent) is
-// neither confirmed by a trusted host signal nor declared/acknowledged by the maintainer. Before
-// D7 the host signal was the ONLY convergence lane — injectable from tests but never supplied in
-// production, so the item fired forever even once its own advice had been applied.
+const WORKTREES_ACK_FALLBACK = 'ack fallback, only on your word that this host ignores the settings key, instead of the grant: ';
+
+// The worktrees-dir item, by the table of spec bridges/velocity-profile, part worktrees-grant: the grant
+// names the parent itself; the probe dir (its nearest existing ancestor) serves the convergence alone.
 const probeWorktreesDir = ({ root, deps, add, skip }) => {
   try {
-    const config = loadWorktreesConfig(root, deps);
-    const parent = config.parentDir == null ? dirname(root) : resolve(root, config.parentDir);
-    // the SAME canonical derivation the provision preflight probes (worktrees.mjs) — an absent
-    // configured dir resolves to its nearest existing ancestor, never a false denial
-    const probeDir = resolveProbeDir(parent, deps);
-    // A supplied host signal is runtime truth and OVERRIDES both declaration lanes in EITHER
-    // direction: a trusted yes converges, a trusted no fires however the project is configured.
+    const grantDir = worktreesGrantDir(root, deps);
+    const probeDir = nearestExistingDir(grantDir, deps);
     const hostSignal = deps.canWriteDir?.(probeDir);
     if (hostSignal === true) return;
     const home = deps.home ?? homedir();
+    if (worktreesGrantHoldsHome(grantDir, home, deps)) {
+      const dir = truncatedTo(oneLineOf(grantDir), templateBudget(WHATS['worktrees-dir.home']));
+      add('worktrees-dir', fillTemplate(WHATS['worktrees-dir.home'], { dir }), '', 'worktrees-dir.home');
+      return;
+    }
     const fingerprint = worktreesDirFingerprint(probeDir, home);
     if (hostSignal !== false) {
       if (declaresWritableDir(root, probeDir, deps)) return;
       if (readAckValue(root, deps, ACKS_WORKTREES_DIR_KEY) === fingerprint) return;
     }
-    const dir = truncatedTo(oneLineOf(probeDir), templateBudget(WHATS['worktrees-dir']));
-    const grantAdvice = `add ${JSON.stringify(probeDir)} to sandbox.filesystem.allowWrite in .claude/settings.json on settings-native hosts; on harness-managed hosts grant this dir for the session or use the provision terminal fallback`;
-    // The consent-flow executes only the APPLY slot; a HAND-APPLY line is maintainer territory and
-    // a recipe: detail is informational. So when the ack lane is open, the runnable ack preview IS
-    // the apply (dry-run; it prints the exact --apply the flow then runs) and the grant advice
-    // rides the detail, labeled as the first step. Against a trusted NO the ack could never
-    // converge, so the grant advice is the apply and no ack surfaces.
-    if (hostSignal === false) {
-      add('worktrees-dir', fillTemplate(WHATS['worktrees-dir'], { dir }), `HAND-APPLY: ${grantAdvice}`);
-    } else {
-      add(
-        'worktrees-dir',
-        fillTemplate(WHATS['worktrees-dir'], { dir }),
-        `node ${q(toolPath('ack-write.mjs'))} --lane worktrees-dir --fingerprint ${fingerprint} --cwd ${q(root)}`,
-        'worktrees-dir',
-        `HAND-APPLY FIRST: ${grantAdvice}; THEN this item's apply one-liner previews the dir-bound ack and prints the exact --apply that records it`,
-      );
-    }
+    const dir = truncatedTo(oneLineOf(grantDir), templateBudget(WHATS['worktrees-dir']));
+    const ack = `node ${q(toolPath('ack-write.mjs'))} --lane worktrees-dir --fingerprint ${fingerprint} --cwd ${q(root)}`;
+    add('worktrees-dir', fillTemplate(WHATS['worktrees-dir'], { dir }), ack, 'worktrees-dir',
+      hostSignal === false ? null : `${WORKTREES_ACK_FALLBACK}${ack}`);
   } catch (err) {
     skip('worktrees-dir', err);
   }
@@ -1577,9 +1584,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,
@@ -1595,6 +1641,7 @@ const PROBES = Object.freeze([
   probeFamilyFreshness,
   probeAdrStore,
   probeMasksItem,
+  probeFootprintGlobal,
   probeWorktreesDir,
   probeMcpChannel,
   probeSpecAdoption,
@@ -1619,7 +1666,7 @@ export const buildRecommendations = ({ cwd, deps = {} } = {}) => {
   // 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 hand-apply-first grant advice; the
+  // line; the worktrees-dir ack fallback; the
   // agents hidden-mode reconcile follow-up). Single-line like apply; absent for every other item.
   // 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"
@@ -1642,7 +1689,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;
   };
@@ -1711,7 +1758,7 @@ 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 hand-apply-first grant advice, or the agents hidden-mode reconcile
+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
 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

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',

package/tools/velocity-profile.mjs

@@ -13,8 +13,9 @@ import { SHELL_METACHARACTERS, hasShellMetacharacter, isSeedablePathToken } from
 import { isDirectRun } from './direct-run.mjs';
 import { compareSemver } from './semver-lite.mjs';
 import { BRIDGE_REVIEW_WRAPPERS, BRIDGE_REVIEW_MODE, KIT_GROUNDING_TOOL, usedBridges, bundledSandboxRecipe, exclusionOf } from './bridge-sandbox-recipe.mjs';
-import { stateDirsOf, mergeAllowWrite } from './bridge-state-dirs.mjs';
+import { stateDirsOf, mergeAllowWrite, homeRelative } from './bridge-state-dirs.mjs';
 import { HOST_HONORS_QUALIFIER, sandboxSurfaceDelta } from './bridge-wiring.mjs';
+import { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.mjs';
 import { loadConfig } from './orchestration-config.mjs';
 import { validateManifest } from './manifest/validate.mjs';
 export { BRIDGE_REVIEW_WRAPPERS, BRIDGE_REVIEW_MODE, KIT_GROUNDING_TOOL };
@@ -269,6 +270,7 @@ export const VELOCITY_STAMP = 'VELOCITY_STAMP';
 export const VELOCITY_UNSAFE_MODE = 'VELOCITY_UNSAFE_MODE';
 export const VELOCITY_MALFORMED = 'VELOCITY_MALFORMED';
 export const VELOCITY_SYMLINK = 'VELOCITY_SYMLINK';
+export const VELOCITY_WORKTREES_HOME = 'VELOCITY_WORKTREES_HOME';
 // The --autonomy render refuses an absent policy file (a writer renders only a declared policy).
 export const VELOCITY_NO_POLICY = 'VELOCITY_NO_POLICY';
 
@@ -299,6 +301,7 @@ const FLAG_ACCEPT_EDITS = '--accept-edits';
 const FLAG_KIT_TOOLS = '--kit-tools';
 const FLAG_BRIDGE_TIER = '--bridge-tier';
 const FLAG_AUTONOMY = '--autonomy';
+const FLAG_WORKTREES = '--worktrees';
 const FLAG_CHECK = '--check';
 const FLAG_CWD = '--cwd';
 const FLAG_HELP = '--help';
@@ -329,6 +332,7 @@ const RESIDUAL_NOTICE =
 const USAGE = `usage: velocity-profile [--dry-run | --apply] [--kit-tools] [--bridge-tier] [--accept-edits] [--cwd <dir>] [--help]
        velocity-profile --autonomy [--apply] [--cwd <dir>]        (render the autonomy policy)
        velocity-profile --autonomy --check [--cwd <dir>]          (read-only drift gate)
+       velocity-profile --worktrees [--apply] [--cwd <dir>]       (grant the worktrees parent)
 
 Allowlist mode (default): seeds the fixed read-only Claude Code allowlist into .claude/settings.json.
 Default is --dry-run. --apply writes; --accept-edits only sets defaultMode when applying.
@@ -337,7 +341,7 @@ absolute path (args wildcard), run-gates.mjs as ONE exact project-root-pinned by
 (project-exec - it runs YOUR declared gates.json), source-size-check.mjs as ONE exact --check
 byte-string (its read-only mode only - its writers keep prompting), and the writers' exact arg-free
 dry-run preview byte-strings. Never touches settings.local.json.
-Every apply also appends the apply ask rule ${APPLY_ASK_RULE} to permissions.ask once, so all work
+Every flagless, --kit-tools and --bridge-tier apply also appends the apply ask rule ${APPLY_ASK_RULE} to permissions.ask once, so all work
 can stay in auto mode: without it auto mode refuses a harness apply and you must leave auto mode for it; with it the harness shows its usual dialog. It allows nothing.
 --bridge-tier (own consent) derives each entry for a used bridge from the effective project recipes:
 review wrappers' CODE mode (codex-review code, agy-review code), the quoted grounding pre-step rule,
@@ -354,7 +358,16 @@ permissions.ask/deny red-lines + permissions.defaultMode. POLICY-ONLY: never see
 leaves permissions.allow untouched. Preview by default; --apply writes; --check is a read-only drift
 gate (exit 1 on drift). --autonomy cannot combine with --accept-edits, --kit-tools, or --bridge-tier
 (allowlist-mode flags). Refuses an absent policy (seed one first with set-autonomy). Never touches
-settings.local.json.`;
+settings.local.json.
+
+--worktrees (own consent, its own mode) writes ONE sandbox.filesystem.allowWrite entry, the worktrees
+parent (docs/ai/worktrees.json parentDir, else the repository's own parent), into this copy's
+.claude/settings.local.json only, never .claude/settings.json, and creates the parent when it is
+missing; it seeds no core and no ask rule.
+It widens, ${HOST_HONORS_QUALIFIER}: every sandboxed command of this copy
+and of every worktree provisioned from it can then write the whole parent dir, sibling repositories
+under it included. A parent that is the home or holds it is refused. It cannot combine with
+--autonomy, --kit-tools, --bridge-tier or --accept-edits.`;
 
 const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
 
@@ -578,13 +591,13 @@ const collectPreExistingNonReadonly = (sources, derivedTier = [], derivedBridgeA
       .map((entry) => ({ source, entry })),
   );
 
-const assertTargetWritable = (absPath, deps = {}) => {
+const assertTargetWritable = (absPath, deps = {}, relPath = SETTINGS_FILE) => {
   const fs = fsDeps(deps);
   const stat = lstatNoFollow(absPath, fs);
   if (stat !== null && !stat.isFile()) {
     throw makeVelocityProfileError(
       VELOCITY_SYMLINK,
-      `${SETTINGS_FILE} exists but is not a regular file - refusing to clobber it`,
+      `${relPath} exists but is not a regular file - refusing to clobber it`,
     );
   }
 };
@@ -689,6 +702,19 @@ const formatBridgeTier = (result) =>
       ]
     : [];
 
+export const KIT_WORKTREES_GRANT_NOTICE =
+  `worktrees grant: ${HOST_HONORS_QUALIFIER}, every sandboxed command of this copy, and of every worktree provisioned from it afterwards (provision copies the local settings), can write the whole worktrees parent dir, sibling repositories under it included, for every later session. ` +
+  'The entry lands in this copy\'s .claude/settings.local.json only, never the committed project settings. A host that ignores the key, a session under permissions.blockReadsOutsideWorkingDirectories and an admin-required sandbox are unchanged by it. ' +
+  'Narrow it: choose a dedicated docs/ai/worktrees.json parentDir BEFORE the first apply — no apply removes an entry, so a parent changed later leaves the earlier entry in settings.local.json until you delete it, your own step.';
+
+const formatWorktreesGrant = (result) => [
+  `${result.wrote ? 'added' : 'would add'} worktrees grant (sandbox.filesystem.allowWrite in ${SETTINGS_LOCAL_FILE}) entries: ${result.worktreesDirToAdd.length}`,
+  ...formatEntryList(result.worktreesDirToAdd),
+  `already present (worktrees grant): ${result.worktreesDirAlreadyPresent.length}`,
+  ...result.worktreesDirsToCreate.map((dir) => `${result.wrote ? 'created' : 'would create'}: ${dir}`),
+  KIT_WORKTREES_GRANT_NOTICE,
+];
+
 const formatGateAdvisory = (gateCandidates) => [
   'gate advisory: candidates you may add BY HAND to .claude/settings.json or settings.local.json; this tool will NOT add them',
   ...(gateCandidates.length
@@ -710,7 +736,10 @@ const formatDefaultMode = (result) =>
     : `defaultMode: ${result.setsDefaultMode ? `would set to ${ACCEPT_EDITS_MODE}` : 'would not be set by this run'}`;
 
 const formatVelocityProfileResult = (result) =>
-  [
+  result.worktrees ? [
+    result.dryRun ? 'agent-workflow velocity profile - DRY RUN (no changes)' : 'agent-workflow velocity profile - APPLY',
+    ...formatWorktreesGrant(result),
+  ].join(LF) : [
     result.dryRun ? 'agent-workflow velocity profile - DRY RUN (no changes)' : 'agent-workflow velocity profile - APPLY',
     ...formatAllowlist(result),
     ...formatKitTier(result),
@@ -986,7 +1015,65 @@ const deriveUsedBridgeTier = (root, deps = {}) => {
   return { used, recipe, dirs, env, home };
 };
 
+const NO_WORKTREES_GRANT = Object.freeze({
+  worktrees: false, worktreesDir: null, worktreesDirToAdd: [], worktreesDirAlreadyPresent: [], worktreesDirsToCreate: [],
+});
+
+const assertLocalSandboxMergeable = (data) => {
+  const malformed = (key, shape) => makeVelocityProfileError(VELOCITY_MALFORMED, `${SETTINGS_LOCAL_FILE}: ${key} must be ${shape}`);
+  const sandbox = data?.sandbox;
+  if (sandbox === undefined) return {};
+  if (!isJsonObject(sandbox)) throw malformed('sandbox', 'a JSON object');
+  for (const key of ['filesystem', 'network']) {
+    if (sandbox[key] !== undefined && !isJsonObject(sandbox[key])) throw malformed(`sandbox.${key}`, 'a JSON object');
+  }
+  if (sandbox.excludedCommands !== undefined && !Array.isArray(sandbox.excludedCommands)) throw malformed('sandbox.excludedCommands', 'an array');
+  if (sandbox.network?.allowedDomains !== undefined && !Array.isArray(sandbox.network.allowedDomains)) {
+    throw malformed('sandbox.network.allowedDomains', 'an array');
+  }
+  const allowWrite = sandbox.filesystem?.allowWrite;
+  if (allowWrite !== undefined && !(Array.isArray(allowWrite) && allowWrite.every(isResolvableDeclaredEntry))) {
+    throw malformed('sandbox.filesystem.allowWrite', 'an array of non-blank strings');
+  }
+  return sandbox;
+};
+
+const planWorktreesGrant = (preflight, opts) => {
+  const home = opts.home ?? homedir();
+  const root = preflight.cwd;
+  const dir = (() => {
+    try {
+      return worktreesGrantDir(root, opts);
+    } catch (err) {
+      throw makeVelocityProfileError(VELOCITY_MALFORMED, String(err?.message ?? err).replace(/^\[agent-workflow-kit\] /u, ''));
+    }
+  })();
+  if (worktreesGrantHoldsHome(dir, home, opts)) {
+    throw makeVelocityProfileError(VELOCITY_WORKTREES_HOME,
+      `the worktrees parent dir ${dir} is the home or holds it - the kit grants no write surface there; point docs/ai/worktrees.json parentDir at a dedicated directory`);
+  }
+  const sandbox = assertLocalSandboxMergeable(preflight.localSettings?.data);
+  const entry = homeRelative(dir, home);
+  const { dirs: worktreesDirToAdd } = sandboxSurfaceDelta({ excludedCommands: [], hosts: [], dirs: [entry] }, sandbox, { home, root });
+  const existing = nearestExistingDir(dir, opts);
+  const worktreesDirsToCreate = [];
+  for (let at = dir; at !== existing; at = dirname(at)) worktreesDirsToCreate.unshift(at);
+  return {
+    ...planVelocityProfile(preflight, {}),
+    toAdd: [],
+    alreadyPresent: [],
+    askToAdd: [],
+    askAlreadyPresent: [],
+    worktrees: true,
+    worktreesDir: entry,
+    worktreesDirToAdd,
+    worktreesDirAlreadyPresent: worktreesDirToAdd.length ? [] : [entry],
+    worktreesDirsToCreate,
+  };
+};
+
 export const planVelocityProfile = (preflight, opts = {}) => {
+  if (opts.worktrees === true) return planWorktreesGrant(preflight, opts);
   const { acceptEdits, kitTools, bridgeTier } = opts;
   const projectAllow = getAllowEntries(preflight.projectSettings?.data);
   const projectAsk = getPermissions(preflight.projectSettings?.data).ask ?? [];
@@ -1041,17 +1128,32 @@ export const planVelocityProfile = (preflight, opts = {}) => {
     dirsAlreadyPresent,
     executeToAdd,
     setsDefaultMode: acceptEdits === true,
+    ...NO_WORKTREES_GRANT,
   };
 };
 
-export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true, kitTools = false, bridgeTier = false } = {}, deps = {}) => {
+// The parent chain goes first, outermost first, so the entry never names a missing directory.
+const applyWorktreesGrant = (projectDir, preflight, plan, resultBase, deps) => {
+  const fs = fsDeps(deps);
+  for (const dir of plan.worktreesDirsToCreate) fs.mkdir(dir);
+  if (plan.worktreesDirToAdd.length === 0) return { wrote: true, dryRun: false, settingsPath: null, ...resultBase };
+  if (preflight.claudeDirAbsent) fs.mkdir(join(projectDir, CLAUDE_DIR), { recursive: true });
+  const settingsPath = join(projectDir, SETTINGS_LOCAL_FILE);
+  const merged = mergeAllowWrite(preflight.localSettings.data ?? {}, plan.worktreesDirToAdd);
+  fs.writeFile(settingsPath, formatJson(merged, preflight.localSettings.eol ?? LF), UTF8);
+  return { wrote: true, dryRun: false, settingsPath, ...resultBase };
+};
+
+export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true, kitTools = false, bridgeTier = false, worktrees = false } = {}, deps = {}) => {
   const projectDir = cwd ?? deps.cwd ?? process.cwd();
+  if (worktrees === true) assertTargetWritable(join(projectDir, SETTINGS_LOCAL_FILE), deps, SETTINGS_LOCAL_FILE);
   const preflight = preflightVelocityProfile({ cwd: projectDir }, deps);
   const plan = planVelocityProfile(preflight, {
     ...deps,
     acceptEdits,
     kitTools,
     bridgeTier,
+    worktrees,
   });
   // Drift guard runs on BOTH dry-run and apply (so a dry-run faithfully predicts the apply) and
   // validates the FULL audited core, not just the to-add delta — a drifted core entry is caught even
@@ -1079,6 +1181,7 @@ export const writeVelocityProfile = ({ cwd, acceptEdits = false, dryRun = true,
       `not a deployed agent-workflow project at lineage ${EXPECTED_WORKFLOW_VERSION} (found ${preflight.stamp ?? 'none'}) - run init/upgrade first`,
     );
   }
+  if (worktrees === true) return applyWorktreesGrant(projectDir, preflight, plan, resultBase, deps);
 
   const fs = fsDeps(deps);
   const settingsPath = join(projectDir, SETTINGS_FILE);
@@ -1697,7 +1800,7 @@ export const formatAutonomyResult = (r) => {
     // boundary is deliberate: permissions.* precedence is the harness's own documented permission
     // model (the layer this whole mode rests on), so those masks stay flat statements.
     const scoped = m.key.startsWith(`${SANDBOX_KEY}.`) ? ` ${HOST_HONORS_QUALIFIER}` : '';
-    lines.push(`  ⚠ ${SETTINGS_LOCAL_FILE} sets ${m.key}=${JSON.stringify(m.local)}, which MASKS this render's ${m.key}=${JSON.stringify(m.rendered)} (local > project) — the local value wins${scoped}, so the render is not effective for that key; the local file is the maintainer's and is never written by the kit.`);
+    lines.push(`  ⚠ ${SETTINGS_LOCAL_FILE} sets ${m.key}=${JSON.stringify(m.local)}, which MASKS this render's ${m.key}=${JSON.stringify(m.rendered)} (local > project) — the local value wins${scoped}, so the render is not effective for that key; the local file is the maintainer's and this render never writes it.`);
   }
   for (const b of r.redlineBypass ?? []) {
     lines.push(`  ⚠ DEGRADE: ${b.source} has a pre-existing allow entry ${b.entry} that would BYPASS the rendered red-line(s) ${b.redlines.join('/')} (a matching allow rule AUTO-APPROVES the command, defeating ask/deny) — remove it by hand; this render never touches permissions.allow.`);
@@ -1881,6 +1984,7 @@ export const parseArgs = (argv) => {
       if (arg === FLAG_KIT_TOOLS) return { ...state, kitTools: true };
       if (arg === FLAG_BRIDGE_TIER) return { ...state, bridgeTier: true };
       if (arg === FLAG_AUTONOMY) return { ...state, autonomy: true };
+      if (arg === FLAG_WORKTREES) return { ...state, worktrees: true };
       if (arg === FLAG_CHECK) return { ...state, check: true };
       if (arg === FLAG_CWD) {
         const next = allArgs[index + 1];
@@ -1890,8 +1994,11 @@ export const parseArgs = (argv) => {
       if (arg.startsWith('-')) throw fail(EXIT_USAGE, `unknown flag: ${arg}`);
       throw fail(EXIT_USAGE, `unexpected argument: ${arg}`);
     },
-    { help: false, dryRunFlag: false, apply: false, acceptEdits: false, kitTools: false, bridgeTier: false, autonomy: false, check: false, cwd: undefined, skipNext: false },
+    { help: false, dryRunFlag: false, apply: false, acceptEdits: false, kitTools: false, bridgeTier: false, autonomy: false, worktrees: false, check: false, cwd: undefined, skipNext: false },
   );
+  const worktreesConflict = [[parsed.autonomy, FLAG_AUTONOMY], [parsed.kitTools, FLAG_KIT_TOOLS],
+    [parsed.bridgeTier, FLAG_BRIDGE_TIER], [parsed.acceptEdits, FLAG_ACCEPT_EDITS]].find(([set]) => parsed.worktrees && set);
+  if (worktreesConflict) throw fail(EXIT_USAGE, `${FLAG_WORKTREES} is its own mode writing ${SETTINGS_LOCAL_FILE} alone — it cannot be combined with ${worktreesConflict[1]}`);
 
   if (parsed.dryRunFlag && parsed.apply) throw fail(EXIT_USAGE, `${FLAG_DRY_RUN} and ${FLAG_APPLY} cannot be used together`);
   // The --autonomy render is a SEPARATE mode from the allowlist seeding: the allowlist-only flags
@@ -1911,6 +2018,7 @@ export const parseArgs = (argv) => {
     kitTools: parsed.kitTools,
     bridgeTier: parsed.bridgeTier,
     autonomy: parsed.autonomy,
+    worktrees: parsed.worktrees,
     check: parsed.check,
     cwd: parsed.cwd,
   };
@@ -1939,7 +2047,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       return EXIT_OK;
     }
     const result = writeVelocityProfile(
-      { cwd, acceptEdits: args.acceptEdits, dryRun: args.dryRun, kitTools: args.kitTools, bridgeTier: args.bridgeTier },
+      { cwd, acceptEdits: args.acceptEdits, dryRun: args.dryRun, kitTools: args.kitTools, bridgeTier: args.bridgeTier, worktrees: args.worktrees },
       deps,
     );
     log(formatVelocityProfileResult(result));