@sabaiway/agent-workflow-kit 14.31.0 → 14.33.0

package/tools/recommendations.mjs

@@ -46,7 +46,7 @@ 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';
@@ -80,7 +80,7 @@ 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 { nearestExistingDir, worktreesGrantDir, worktreesGrantHoldsHome } from './worktrees.mjs';
 import { preflightCheapAgents, EXECUTOR_VEHICLE } from './cheap-agents.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.
@@ -120,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.';
@@ -197,6 +199,7 @@ export const SEVERITIES = Object.freeze({
   '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.
@@ -280,6 +283,7 @@ export const WHATS = Object.freeze({
   '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',
@@ -883,7 +887,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 +896,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 +928,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 +952,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);
   }
@@ -1379,46 +1406,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);
   }
@@ -1594,7 +1606,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"
@@ -1686,7 +1698,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/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));

package/tools/worktrees.mjs

@@ -23,11 +23,12 @@ import {
   patternToProbe,
 } from './known-footprint.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { isScratchPlanName, plansInFlight, PLANS_REL, shellQuoteArg } from './review-state.mjs';
+import { isScratchPlanName, plansInFlight, PLANS_REL } from './plan-files.mjs';
+import { shellQuoteArg } from './repo-lex.mjs';
 import { writeContainedFileAtomic } from './atomic-write.mjs';
 import { assertContainedRealPath } from './fs-safe.mjs';
 import { GIT_MAX_BUFFER } from './git-env.mjs';
-import { isFinalCapableDeclaration } from './run-gates.mjs';
+import { isFinalCapableDeclaration } from './gates-declaration.mjs';
 import {
   WORKTREES_STOP, stop, EXIT, handoffBasename, recordValue, hasControlByte, displayValue,
   composeProvisionRecordSection, composeLandingValue, composeHandoffStub,
@@ -38,6 +39,8 @@ import {
   readSatelliteIdentity,
 } from './satellite-locator.mjs';
 import { composeSatellitePrompt, resolveSeededPlan } from './worktree-prompt.mjs';
+import { applySlot } from './write-lanes.mjs';
+import { dirCovers } from './declared-paths.mjs';
 
 // The record format and the satellite locator now live in leaves the dispatch side reads too — but
 // every name they took away is re-exported here, so no import site and no asserted error `code`
@@ -577,11 +580,25 @@ export const nearestExistingDir = (path, deps = {}) => {
   return walk(resolve(path));
 };
 
-// The ONE canonical probe-dir derivation provision AND the recommendations advisor share:
-// resolve through the existing-parent realpath, then walk to the nearest existing dir.
+// The provision preflight's probe-dir derivation: resolve through the existing-parent realpath, then
+// walk to the nearest existing dir (the advisor walks worktreesGrantDir's answer the same way).
 export const resolveProbeDir = (path, deps = {}) =>
   nearestExistingDir(realpathThroughExistingParent(path, deps), deps);
 
+// The worktrees write grant names the parent ITSELF (spec bridges/velocity-profile, part worktrees-grant):
+// the writer, the advisor and the danger check read this one derivation, never resolveProbeDir's ancestor.
+export const worktreesGrantDir = (root, deps = {}) => {
+  const realRoot = realpathThroughExistingParent(root, deps);
+  const { parentDir } = loadWorktreesConfig(realRoot, deps);
+  const dir = realpathThroughExistingParent(parentDir == null ? dirname(realRoot) : resolve(realRoot, parentDir), deps);
+  const st = lstatNoFollow(fsOf(deps).lstat, dir);
+  if (st !== null && !st.isDirectory()) throw stop(`${CONFIG_REL}: parentDir names an existing non-directory: ${dir}`);
+  return dir;
+};
+
+export const worktreesGrantHoldsHome = (dir, home, deps = {}) =>
+  dirCovers(dir, resolve(home)) || dirCovers(dir, realpathThroughExistingParent(resolve(home), deps));
+
 export const probeParentWritable = (parentDir, deps = {}) => {
   const { mkdirPlain, rmdir, rand } = fsOf(deps);
   const probe = join(parentDir, `.aw-write-probe-${rand()}`);
@@ -620,10 +637,13 @@ const quoteOwnTool = () => `'${WORKTREES_TOOL_ABS.replace(/'/g, `'\\''`)}'`;
 const composeOwnToolPrefix = (root) =>
   `cd ${shellQuoteArg(root)} && node ${quoteOwnTool()}`;
 
+const composeGrantRoute = (root) => `the kit's worktrees-dir item grants the configured worktrees parent on your yes: the agent runs ${
+  applySlot('worktrees-dir', { toolsDir: dirname(WORKTREES_TOOL_ABS), root }).check
+} and, on your yes on its result, its apply line by the consent route, then runs this command again; when that check refuses, prints nothing to change, or grants a dir that does not hold this command's target, use the terminal fallback below`;
+
 const landWritabilityStop = ({ parentDir, root, slug }) => stop([
   `the worktrees parent dir is not writable from this session: ${parentDir}`,
-  'Arm the ONE-TIME consent (then land runs promptless):',
-  `  .claude/settings.json → sandbox.filesystem.allowWrite += ${JSON.stringify(parentDir)}`,
+  composeGrantRoute(root),
   'Or run the full command yourself in a plain terminal:',
   `  ${composeOwnToolPrefix(root)} land ${shellQuoteArg(slug)} --prepare`,
 ].join('\n'));
@@ -638,8 +658,7 @@ const writabilityStop = ({ parentDir, root, slug, flags }) => {
   return stop(
     [
       `the worktrees parent dir is not writable from this session: ${parentDir}`,
-      'Arm the ONE-TIME consent (then every provision/cleanup runs promptless):',
-      `  .claude/settings.json → sandbox.filesystem.allowWrite += ${JSON.stringify(parentDir)}`,
+      composeGrantRoute(root),
       'Or run the full command yourself in a plain terminal:',
       `  ${composeProvisionArgv({ root, slug, flags })}`,
       `(from the target repo root, when that checkout carries the kit at agent-workflow-kit/: node agent-workflow-kit/tools/worktrees.mjs provision ${q(slug)} ${provisionFlagsTail(flags, q).join(' ')})`,
@@ -3150,8 +3169,7 @@ const destructiveRecovery = ({ slug, branch }) =>
 
 const cleanupWritabilityStop = ({ parentDir, root, slug, branch, abandon }) => stop([
   `the worktrees parent dir is not writable from this session: ${parentDir}`,
-  'Arm the ONE-TIME consent (then every provision/cleanup runs promptless):',
-  `  .claude/settings.json → sandbox.filesystem.allowWrite += ${JSON.stringify(parentDir)}`,
+  composeGrantRoute(root),
   'Or run the full command yourself in a plain terminal:',
   `  ${composeOwnToolPrefix(root)} ${composeCleanupCommand({ slug, branch, abandon })}`,
 ].join('\n'));