@ngockhoale/ukit 3.4.25 → 3.4.27

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.27 - 2026-10-09
+
+**Stop-gate evidence loop hardening and linked-worktree isolation (follow-up to 3.4.26).**
+- `execution-ledger`: `yarn`/`npm`/`pnpm release:verify` is recorded as a verification receipt. A verification command piped through `| tail`/`| grep` no longer journals as a pass unless `pipefail`/`PIPESTATUS` proves the real exit status. Verification verdicts are scoped to the checkout they ran in, and path-qualified runners are recognised; Bash work in sibling worktrees is attributed to the right checkout.
+- `stop-coordinator` / `handoff-resume`: the Stop/SessionStart handoff cursor is scoped to the git-verified linked worktree, so a run in one worktree no longer blocks or resumes another.
+- `safe-patch` / `pre-edit-backup`: Edit/Write targets inside git-listed linked worktrees of the same repo are accepted; backups are isolated per worktree even when two worktrees share one relative path.
+- `hook-chain-runner --emit-verdict`: multi-document JSON on stdout from chained hooks is coalesced into one valid document.
+- `auto-allow-bash`: a burst of concurrent hooks no longer silently loses allow rules. Dropped rules are journaled and the bounded lock slice is widened. Trade-off: worst-case lock wait under contention rises from ~1.2 s to ~3 s.
+- Dev tooling: `scripts/dev/worktree-preflight.mjs` bootstraps the gitignored runtime in a fresh worktree via `ukit install`, re-renders drifted gitignored `CLAUDE.md`/`AGENTS.md`, warns on a symlinked `node_modules`, and bounds its git/render children with explicit timeouts. `manifests/documentation.yaml` declares `WORKLOG_ARCHIVE.md` as `local_only`.
+- Test-only: route-audit `tmpDir` cleanup retries so a detached decision-shadow child cannot fail `afterEach` with `ENOTEMPTY`.
+- Known limits: 1 of 165 stress iterations of the concurrent auto-allow burst still lost a rule (cause not yet identified). Existing checkouts must re-run `ukit install` to pick up the new runtime.
+
+## 3.4.26 - 2026-10-08
+
+**P1 fix: completion gate no longer reports `missing write-evidence` for tracked-file changes made through Bash.**
+- `execution-ledger`: a Bash receipt records a git workspace fingerprint (HEAD + hash of `git diff HEAD`, tracked files only). When it differs from the previous receipt, a synthetic write is applied. First observation, git failure/timeout, non-git directories and untracked files record nothing (fail-closed).
+- Strictly read-only Bash (`ls`, `cat`, `git status`, ...) and verification commands absorb the delta into the baseline instead of earning a write, so a background process or subagent edit is not credited to the main agent.
+- Evidence tier: a Bash-derived write is `inferred` (`evidenceTier: 'inferred'`, supporting evidence); only Edit/Write is direct. Inferred writes never satisfy `verification-evidence`.
+- Known limits: the first Bash of a session only seeds the baseline, so a mutation made by that very command is not credited; a delta that coincides with a non-read-only Bash is still attributed to it (inferred, not proof).
+- Regression tests: `tests/hooks/bashMutationEvidence.test.js` (12 cases).
+- Not included: AWAITING_USER stop handling (separate bug); `isVerificationCommand` coverage for commands such as `yarn release:verify`.
+
 ## 3.4.25 - 2026-10-08
 
 **P0 hotfix: Stop hook no longer force-continues a run the user paused or cancelled.**

package/manifests/documentation.yaml

@@ -282,6 +282,8 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
+    notes: gitignored machine-local rotation target (created by the WORKLOG archive workflow); absent on a clean checkout is valid, validated normally when present
 
   # ── docs/ runtime + dir families ─────────────────────────────────────────
   - id: docs-status

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.25",
+  "version": "3.4.27",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -56,6 +56,7 @@
     "index:query": "node ./scripts/index/query-index.mjs",
     "bug:triage": "node ./scripts/bug/triage.mjs",
     "skill:audit": "node ./scripts/skill/audit-skill.mjs",
+    "worktree:preflight": "node ./scripts/dev/worktree-preflight.mjs",
     "docs:render": "node scripts/docs/render-instructions.mjs --write",
     "docs:render:check": "node scripts/docs/render-instructions.mjs --check",
     "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",

package/scripts/dev/worktree-preflight.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Bootstrap the gitignored UKit runtime in a fresh `git worktree` so targeted tests can run.
+//
+// A new worktree only has tracked files. `.claude/`, `.ukit/`, `CLAUDE.md`, … are generated by
+// `ukit install` and gitignored, so mirror/runtime tests fail there for environment reasons.
+// This reuses `bin/ukit install` (no new generator), idempotently:
+//   - already bootstrapped            → no-op
+//   - missing prerequisites           → run `ukit install` once, re-check
+//   - not a linked worktree           → refuse (the primary checkout's .claude/ is the maintainer runtime)
+// `ukit install` writes the install flavour of root CLAUDE.md/AGENTS.md, but those files are
+// gitignored *render outputs* of template_project/instructions (docs:render). The preflight
+// re-renders them when they drift — never a tracked render target, which is only reported.
+// It copies nothing from another checkout (no sessions, secrets, handoff state) and does not
+// link node_modules — run `yarn install` in the worktree (a symlinked node_modules is warned:
+// realpath-sensitive hooks resolve it outside the project and misjudge delete targets).
+//
+// Usage: node scripts/dev/worktree-preflight.mjs [--root <dir>] [--check] [--json]
+// Exit:  0 ready · 1 prerequisites missing (--check, or bootstrap failed) · 2 refused
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Generated by `ukit install`; each is required by a mirror/runtime test family.
+export const PREREQUISITES = [
+  'node_modules',
+  '.claude/settings.json',
+  '.claude/hooks',
+  '.claude/ukit/runtime/execution-ledger.mjs',
+  '.ukit/storage/config.json',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+
+// Explicit bounds so a wedged git/render child can never hang the preflight. Normal runs take
+// milliseconds; these sit far above that yet below `ukit install`'s own 120s budget.
+const GIT_TIMEOUT_MS = 30_000;
+const RENDER_TIMEOUT_MS = 60_000;
+
+function git(root, args) {
+  const res = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+export function isLinkedWorktree(root) {
+  const gitDir = git(root, ['rev-parse', '--path-format=absolute', '--git-dir']);
+  const common = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return Boolean(gitDir && common && path.resolve(gitDir) !== path.resolve(common));
+}
+
+function isTracked(root, rel) {
+  const res = spawnSync('git', ['ls-files', '--error-unmatch', '--', rel], { cwd: root, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+  // A timed-out probe proves nothing: treat as tracked so the file is reported, never overwritten.
+  return res.status === 0 || Boolean(res.error);
+}
+
+const RENDER_CLI = 'scripts/docs/render-instructions.mjs';
+
+// → rel paths whose rendered bytes differ from disk (`DRIFT <target>` lines of --check).
+export function renderDrift(root) {
+  const res = spawnSync(process.execPath, [path.join(root, RENDER_CLI), '--check'], { cwd: root, encoding: 'utf8', timeout: RENDER_TIMEOUT_MS });
+  // A killed check prints nothing, which would read as "no drift" — fail loudly instead.
+  if (res.error) throw new Error(`render check did not complete (${res.error.code || res.error.message})`);
+  return `${res.stdout || ''}`.split('\n').map((l) => l.match(/^DRIFT (.+)$/)?.[1]).filter(Boolean);
+}
+
+export function missingPrerequisites(root) {
+  return PREREQUISITES.filter((rel) => !fs.existsSync(path.join(root, rel)));
+}
+
+export function preflight({ root, check = false } = {}) {
+  const projectRoot = fs.realpathSync(root);
+  const result = { root: projectRoot, ok: false, bootstrapped: false, missing: [], rendered: [], warnings: [], home: null, error: null };
+
+  if (!fs.existsSync(path.join(projectRoot, 'bin/ukit'))) {
+    return { ...result, exitCode: 2, error: `not a UKit checkout (no bin/ukit): ${projectRoot}` };
+  }
+  if (!isLinkedWorktree(projectRoot)) {
+    return { ...result, exitCode: 2, error: 'refusing: not a linked worktree (git worktree add …); the primary checkout keeps its own runtime' };
+  }
+
+  result.missing = missingPrerequisites(projectRoot);
+  if (result.missing.length > 0) {
+    if (check) return { ...result, exitCode: 1 };
+    if (result.missing.includes('node_modules')) {
+      return { ...result, exitCode: 1, error: 'node_modules missing — run `yarn install` in the worktree first (not linked from another checkout)' };
+    }
+
+    // `ukit install` also writes user-level state (~/.ukit playbooks). Point HOME inside the
+    // worktree's ignored .cache/ so a preflight never mutates the real home or leaks from it.
+    result.home = path.join(projectRoot, '.cache/worktree-preflight-home');
+    fs.mkdirSync(result.home, { recursive: true });
+    const install = spawnSync(process.execPath, [path.join(projectRoot, 'bin/ukit'), 'install'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      env: { ...process.env, HOME: result.home, USERPROFILE: result.home },
+      timeout: 120_000,
+    });
+    result.bootstrapped = true;
+    result.missing = missingPrerequisites(projectRoot);
+    if (install.status !== 0 || result.missing.length > 0) {
+      const tail = `${install.stdout || ''}${install.stderr || ''}`.trim().split('\n').slice(-5).join('\n');
+      return { ...result, exitCode: 1, error: `ukit install did not produce all prerequisites (exit ${install.status})\n${tail}` };
+    }
+  }
+
+  if (fs.lstatSync(path.join(projectRoot, 'node_modules')).isSymbolicLink()) {
+    result.warnings.push('node_modules is a symlink — realpath-sensitive tests (block-dangerous) fail; run `yarn install` in this worktree for a real copy');
+  }
+
+  const drift = renderDrift(projectRoot);
+  if (drift.length > 0) {
+    if (check) return { ...result, missing: drift.map((t) => `render:${t}`), exitCode: 1 };
+    const tracked = drift.filter((t) => isTracked(projectRoot, t));
+    if (tracked.length > 0) {
+      return { ...result, exitCode: 1, error: `tracked render target(s) drifted, not overwriting: ${tracked.join(', ')} — commit or revert the source edit` };
+    }
+    const write = spawnSync(process.execPath, [path.join(projectRoot, RENDER_CLI), '--write'], { cwd: projectRoot, encoding: 'utf8', timeout: RENDER_TIMEOUT_MS });
+    const still = renderDrift(projectRoot);
+    if (write.status !== 0 || still.length > 0) {
+      return { ...result, exitCode: 1, error: `docs:render did not clear drift: ${still.join(', ') || (write.stderr || '').trim()}` };
+    }
+    result.rendered = drift;
+  }
+  return { ...result, ok: true, exitCode: 0 };
+}
+
+function main(argv) {
+  const args = { root: process.cwd(), check: false, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') args.root = path.resolve(argv[++i] || '');
+    else if (argv[i] === '--check') args.check = true;
+    else if (argv[i] === '--json') args.json = true;
+  }
+  const { exitCode, ...result } = preflight(args);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (result.ok) {
+    console.log(`[worktree-preflight] ready${result.bootstrapped ? ' (bootstrapped via ukit install)' : ' (already bootstrapped)'}: ${result.root}`);
+  } else {
+    console.error(`[worktree-preflight] ${result.error || `missing: ${result.missing.join(', ')}`}`);
+  }
+  process.exit(exitCode);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));

package/src/core/docContracts.js

@@ -232,6 +232,7 @@ function validateRegistryDoc(doc, fileExists) {
       }
     }
     if (e.notes !== undefined && typeof e.notes !== 'string') problems.push(`${tag}: notes must be a string`);
+    if (e.local_only !== undefined && typeof e.local_only !== 'boolean') problems.push(`${tag}: local_only must be a boolean`);
   });
   return problems;
 }
@@ -626,6 +627,8 @@ async function checkRegistry(rootDir, registry, fileExists) {
   const problems = validateRegistryDoc(registry, fileExists);
   for (const e of registry.entries || []) {
     if (typeof e.path !== 'string' || e.path.length === 0) continue;
+    // local_only = optional gitignored machine-local doc: absent on a clean checkout is valid
+    if (e.local_only === true && !fileExists(e.path)) continue;
     if (!fileExists(e.path)) problems.push(`entry path '${e.path}' does not exist on disk`);
     if (typeof e.source_of_truth === 'string' && e.source_of_truth.length > 0 && !fileExists(e.source_of_truth)) {
       problems.push(`entry '${e.path}': source_of_truth '${e.source_of_truth}' does not exist on disk`);

package/template_project/.claude/hooks/auto-allow-bash.sh

@@ -289,16 +289,34 @@ async function applyMutation() {
     // costs the normal permission prompt for this one command.
     return;
   }
+  // The default 1.2s slice is shorter than the queue a burst of parallel hooks builds on a
+  // loaded host, so waiters gave up "busy" and lost their rule (measured: 194 busy drops in
+  // 165 bursts of 30). A longer slice is still BOUNDED — lockBudgetMs takes the min with the
+  // remaining hook deadline minus the cleanup reserve — and exhaustion stays fail-closed.
   const deadlineMs = lockModule.lockBudgetMs({
     hookDeadlineMs: HOOK_DEADLINE_MS,
     startedAt: LOCK_STARTED_AT,
+    maxWaitMs: 3000,
   });
   const outcome = await lockModule.withAsyncLock(usagePath, { deadlineMs }, applyMutation);
   if (!outcome.ok) {
-    // busy or aborted: fail closed — write nothing unlocked, exit 0.
+    // busy or aborted: fail closed — write nothing unlocked, exit 0. The drop is journaled
+    // (reason + waited ms only — never the rule or command) so a lost allow rule is
+    // diagnosable instead of silent.
+    if (typeof lockModule.journalDroppedLockMutation === "function") {
+      await lockModule.journalDroppedLockMutation(usagePath, { reason: outcome.reason, waitedMs: outcome.waitedMs });
+    }
     return;
   }
-})().catch(() => {});
+})().catch(async (error) => {
+  // A throw inside the locked mutation (e.g. atomic rename failure) is also a dropped rule.
+  // Record only the errno-style code, never the message (it can embed paths/rule text).
+  try {
+    const code = /^[A-Z0-9_]{2,24}$/.test(String(error && error.code)) ? error.code : "UNKNOWN";
+    const lockModule = await import(pathToFileURL(path.join(process.env.UKIT_RUNTIME_DIR || "", "async-lock.mjs")).href);
+    await lockModule.journalDroppedLockMutation(process.argv[2], { reason: "error:" + code, waitedMs: Date.now() - LOCK_STARTED_AT });
+  } catch {}
+});
 ' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$RULE" "$NOW_UTC" "$MAX_RULES" >/dev/null 2>&1 || true
 
 exit 0

package/template_project/.claude/hooks/handoff-resume.sh

@@ -103,7 +103,7 @@ setTimeout(() => {
 }, HOOK_DEADLINE_MS).unref();
 
 const projectRoot = process.env.PROJECT_ROOT;
-const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+let runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
 const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
 const intentPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'handoff-intent.mjs');
 
@@ -169,6 +169,17 @@ async function emitOrdinaryResume(payload, source) {
   })();
   const source = typeof payload.source === 'string' ? payload.source : 'startup';
 
+  // Worktree scoping: the host pins CLAUDE_PROJECT_DIR to the primary checkout, so a
+  // session in an independent linked worktree must not be handed the primary's
+  // cursor. Only a git-verified worktree of this repo re-scopes the cursor; any
+  // failure keeps the primary path.
+  try {
+    const mod = await import(pathToFileURL(intentPath).href);
+    if (typeof mod.resolveHandoffRunRoot === 'function') {
+      runPath = path.join(mod.resolveHandoffRunRoot(projectRoot, payload.cwd), 'docs', 'AI_HANDOFF', 'RUN.md');
+    }
+  } catch {}
+
   let text;
   try {
     text = await fs.promises.readFile(runPath, 'utf8');

package/template_project/.claude/ukit/index/post-edit-verify.mjs

@@ -3,7 +3,7 @@ import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { analyzeTextBuffer, analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
-import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { classifySafePatchRisk, isSafePatchAdvisoryOnly, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveEditTarget } from '../runtime/safe-patch-core.mjs';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): the post-edit-verify hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
@@ -179,10 +179,10 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
   if (config.enabled === false || config.backupEnabled === false) return { status: 'disabled' };
   const filePath = getFilePath(payload);
   if (!filePath) return { status: 'skipped', reason: 'no-file' };
-  const resolved = resolveProjectFile(projectRoot, filePath);
+  const resolved = resolveEditTarget(projectRoot, filePath);
   if (!(await pathExists(resolved.absolute))) return { status: 'skipped', reason: 'missing-after', file: resolved.relative };
 
-  const latest = await findLatestBackup(projectRoot, resolved.relative);
+  const latest = await findLatestBackup(projectRoot, resolved.key);
   // Consumed (or absent) baseline → there is nothing truthful to diff against.
   // Skipping is deliberate: a fabricated delta is strictly worse than no gate.
   if (!latest || latest.consumed) return { status: 'skipped', reason: 'no-backup', file: resolved.relative };
@@ -209,7 +209,7 @@ export async function verifyPostEdit({ projectRoot = process.cwd(), payload = {}
   const status = risk.strict && (overChangedLines || overHunks) ? (handoffAdvisory ? 'advisory' : 'blocked') : 'ok';
   const postEntry = {
     event: 'post-edit',
-    file: resolved.relative,
+    file: resolved.key,
     beforeHash: beforeProfile.sha256,
     afterHash: afterProfile.sha256,
     timestamp: new Date().toISOString(),

package/template_project/.claude/ukit/index/pre-edit-backup.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
-import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveProjectFile } from '../runtime/safe-patch-core.mjs';
+import { classifySafePatchRisk, parseJsonInput, pathExists, readRuntimeSafePatchConfig, resolveEditTarget } from '../runtime/safe-patch-core.mjs';
 import { fileURLToPath } from 'node:url';
 
 // Hook-context self-deadline (2.4.1 orphan-leak class): the pre-edit-backup hook passes
@@ -49,7 +49,7 @@ async function backupIfNeeded({ projectRoot, payload }) {
   await pruneOldBackups(projectRoot, config);
   const filePath = getFilePath(payload);
   if (!filePath) return { status: 'skipped', reason: 'no-file' };
-  const resolved = resolveProjectFile(projectRoot, filePath);
+  const resolved = resolveEditTarget(projectRoot, filePath);
   if (!(await pathExists(resolved.absolute))) return { status: 'skipped', reason: 'new-file', file: resolved.relative };
   const profile = await analyzeTextFile(resolved.absolute);
   const risk = classifySafePatchRisk(resolved.relative, profile, config);
@@ -68,7 +68,7 @@ async function backupIfNeeded({ projectRoot, payload }) {
     // manifest order, so readers must be able to tell a pre-edit backup row
     // from a post-edit audit row without inferring it from field presence.
     event: 'pre-edit',
-    file: resolved.relative,
+    file: resolved.key,
     beforeHash: profile.sha256,
     profile: publicTextProfile(profile),
     tool: getToolName(payload),

package/template_project/.claude/ukit/runtime/execution-ledger.mjs

@@ -505,20 +505,91 @@ function isVerificationCommand(command) {
   const text = String(command || '').trim();
   if (!text) return false;
   return [
-    /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)/i,
+    /(?:^|\s|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)/i,
     /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+(?:test|lint|typecheck|check|build)(?:\s|$)/i,
-    /(?:^|\s)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$)/i,
+    /(?:^|\s)(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+release:verify(?:\s|$)/i,
+    /(?:^|\s|\.bin\/)(?:tsc|eslint|biome|ruff|mypy)(?:\s|$)/i,
     /(?:^|\s)node\s+--check(?:\s|$)/i,
   ].some((pattern) => pattern.test(text));
 }
 
+// Split a shell command into pipelines of stages (quote/escape aware). `&&`, `||`, `;` and
+// newlines separate pipelines; a lone `|` (or `|&`) separates stages. Redirections such as
+// `2>&1` / `&>` are not separators.
+function shellPipelineStages(command) {
+  const text = String(command || '');
+  const pipelines = [];
+  let stages = [];
+  let buffer = '';
+  let quote = null;
+  let escaped = false;
+  const closeStage = () => {
+    if (buffer.trim()) stages.push(buffer.trim());
+    buffer = '';
+  };
+  const closePipeline = () => {
+    closeStage();
+    if (stages.length) pipelines.push(stages);
+    stages = [];
+  };
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (escaped) { escaped = false; buffer += char; continue; }
+    if (char === '\\') { escaped = true; buffer += char; continue; }
+    if (quote) { if (char === quote) quote = null; buffer += char; continue; }
+    if (char === "'" || char === '"') { quote = char; buffer += char; continue; }
+    if (char === '|') {
+      if (text[i + 1] === '|') { closePipeline(); i += 1; continue; }
+      closeStage();
+      if (text[i + 1] === '&') i += 1;
+      continue;
+    }
+    if (char === '&') {
+      if (text[i + 1] === '&') { closePipeline(); i += 1; continue; }
+      buffer += char; // `2>&1`, `&>file`, trailing background `&`
+      continue;
+    }
+    if (char === ';' || char === '\n') { closePipeline(); continue; }
+    buffer += char;
+  }
+  closePipeline();
+  return pipelines;
+}
+
+// A shell pipeline exits with its LAST stage's status, so `npx vitest run | tail` is exit 0
+// even when vitest failed. A verification command in a non-final stage therefore has an
+// unproven exit status — unless the command enables `pipefail` or reads `PIPESTATUS`.
+// Returns the masked verification stage (string) or null.
+function maskedVerificationStage(command) {
+  const text = String(command || '');
+  if (/\bpipefail\b|\bPIPESTATUS\b|\bpipestatus\b/.test(text)) return null;
+  for (const stages of shellPipelineStages(text)) {
+    for (const stage of stages.slice(0, -1)) {
+      if (isVerificationCommand(stage)) return stage;
+    }
+  }
+  return null;
+}
+
+// Announce through the in-proc hook emitter only (never fd 1 from library callers).
+function noteUnprovenExitStatus(stage) {
+  if (!ledgerMessageEmitter) return;
+  const message =
+    `UKit execution-ledger: \`${stage}\` ran in a pipeline, so the exit status belongs to the last pipe stage `
+    + '(e.g. tail/grep), not the test runner — it is NOT counted as passing verification. '
+    + 'Re-run with `set -o pipefail; <cmd> | tail` (or without the pipe) to prove the result.';
+  try {
+    ledgerMessageEmitter(`${JSON.stringify({ systemMessage: message })}\n`);
+  } catch { /* an emitter failure never loses the ledger event */ }
+}
+
 function compactReceipt(receipt) {
   const compact = {
     ts: receipt.ts,
     kind: receipt.kind,
     success: receipt.success,
   };
-  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail']) {
+  for (const key of ['toolName', 'toolUseId', 'file', 'command', 'exitCode', 'scope', 'error', 'verdict', 'evidence', 'evidenceSurface', 'class', 'status', 'detail', 'exitStatusUnproven']) {
     if (receipt[key] !== undefined && receipt[key] !== null && receipt[key] !== '') {
       compact[key] = receipt[key];
     }
@@ -549,6 +620,77 @@ function gitOutput(args, cwd) {
   }
 }
 
+// A Bash command may run in a sibling worktree of the session's repo (`cd ../repo-wt && ...`),
+// so the session root's fingerprint never moves for work done there. Only a LEADING `cd <dir>`
+// that lands in a checkout sharing this repo's git common dir redirects the fingerprint; an
+// unrelated repo, a missing dir or any git failure keeps the session root (fail-closed).
+function bashWorkspaceScope(command, projectRoot) {
+  const here = { root: projectRoot, foreign: false };
+  const match = String(command || '').match(/^\s*cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|<>$`~]+))\s*(?:&&|;)/);
+  if (!match || !projectRoot) return here;
+  const real = (dir) => { try { return fsSync.realpathSync(dir); } catch { return null; } };
+  const commonDir = (dir) => {
+    const out = gitOutput(['rev-parse', '--git-common-dir'], dir);
+    return out ? real(path.resolve(dir, out)) : null;
+  };
+  const sessionCommon = commonDir(projectRoot);
+  // A session outside any git repo has no checkout family to compare against: keep the
+  // pre-existing command-text behaviour rather than inventing a foreign verdict.
+  if (!sessionCommon) return here;
+  const target = real(path.resolve(projectRoot, match[1] || match[2] || match[3]));
+  const top = target ? gitOutput(['rev-parse', '--show-toplevel'], target) : null;
+  if (!top || commonDir(target) !== sessionCommon) return { root: projectRoot, foreign: true };
+  const topReal = real(top);
+  if (!topReal || topReal === real(projectRoot)) return here;
+  return { root: topReal, foreign: false };
+}
+
+// Verifiable Bash-mutation evidence: a Bash command is never a write by itself. It counts
+// only when the TRACKED git workspace fingerprint (HEAD + content hash of `git diff HEAD`)
+// differs from the one recorded at the previous receipt. Any git failure, timeout or
+// oversize diff yields null, and null never creates evidence (fail-closed). Untracked files
+// are deliberately excluded: runtime state under .ukit/ would otherwise look like a change.
+function workspaceFingerprint(cwd) {
+  if (!cwd) return null;
+  try {
+    const run = (args) => execFileSync('git', args, {
+      cwd,
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    const head = String(run(['rev-parse', 'HEAD'])).trim();
+    if (!head) return null;
+    const diffHash = crypto.createHash('sha256').update(run(['diff', 'HEAD', '--no-ext-diff'])).digest('hex');
+    return `${head.slice(0, 12)}:${diffHash.slice(0, 16)}`;
+  } catch {
+    return null;
+  }
+}
+
+// A workspace delta cannot be attributed to the Bash call that happened to observe it: a
+// background process or a subagent may have changed the tree in between. The classifier below
+// only ever REMOVES credit — a command it recognises as strictly read-only never receives a
+// delta write (the delta is absorbed into the baseline). It never grants credit by itself;
+// unrecognised commands are merely eligible, and their write stays tier "inferred".
+const READ_ONLY_BASH = new Set([
+  'ls', 'cat', 'head', 'tail', 'wc', 'pwd', 'echo', 'printf', 'grep', 'rg', 'cd', 'which',
+  'stat', 'file', 'diff', 'sort', 'uniq', 'date', 'env', 'true', 'test', '[', 'basename', 'dirname',
+]);
+const READ_ONLY_GIT = new Set(['status', 'diff', 'log', 'show', 'rev-parse', 'ls-files', 'blame', 'describe', 'merge-base']);
+
+function isReadOnlyBashCommand(command) {
+  const text = String(command || '').trim();
+  if (!text || /[>`]|\$\(|<\(|\btee\b|\s-i\b|--in-place|-exec\b|-delete\b/.test(text)) return false;
+  return text.split(/&&|\|\||;|\||\n/).every((segment) => {
+    const words = segment.trim().split(/\s+/).filter(Boolean);
+    while (words.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0])) words.shift();
+    if (words.length === 0) return false;
+    if (words[0] === 'git') return READ_ONLY_GIT.has(words.find((w, i) => i > 0 && !w.startsWith('-')) || '');
+    return READ_ONLY_BASH.has(words[0]);
+  });
+}
+
 // A diff whose changed paths are all tests/docs/lint-format config is
 // stale-but-recoverable: one rebuild at current head restores currency.
 const RECOVERABLE_DIFF_PATH = /(^|\/)(docs\/|[^/]*\.md$)|\.(test|spec)\.[cm]?[jt]sx?$|(^|\/)(tests?|specs?|__tests__)\/|(?:^|\/)\.?eslint|\.prettierrc|biome\.json|\.editorconfig|tsconfig.*\.json$/i;
@@ -594,6 +736,14 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
   if (!verdict || typeof verdict !== 'object') {
     return { status: 'untracked', current: false, headSha: null };
   }
+  if (verdict.workspaceRoot) {
+    // Verified inside a sibling checkout: judge currency there. A checkout that has since been
+    // removed proves nothing — stale, never fail-open.
+    if (!fsSync.existsSync(verdict.workspaceRoot)) {
+      return { status: 'stale', current: false, headSha: null };
+    }
+    cwd = verdict.workspaceRoot;
+  }
   const currentHead = gitOutput(['rev-parse', 'HEAD'], cwd);
   if (!currentHead) {
     // No git repo (or git unavailable): currency cannot be proven either way —
@@ -630,9 +780,9 @@ export function verdictCurrent(verdict, { cwd = process.cwd() } = {}) {
 // (a hook or subagent can attest its own kind/verifier); otherwise the kind is
 // derived from the command shape — test runners prove `test-verified`, a run that
 // only type-checks/lints is honestly `check-only`.
-const TEST_RUNNER_COMMAND = /(?:^|\s)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
+const TEST_RUNNER_COMMAND = /(?:^|\s|\.bin\/)(?:vitest|jest|mocha|ava|pytest|py\.test)(?:\s|$)|(?:npm|pnpm|yarn|bun)(?:\s+run)?\s+test(?:\s|$)/i;
 
-function mintVerificationVerdict(receipt, payload, projectRoot) {
+function mintVerificationVerdict(receipt, payload, projectRoot, sessionRoot = projectRoot) {
   const supplied = payload?.verdict && typeof payload.verdict === 'object' ? payload.verdict : {};
   const cwd = projectRoot || payload?.cwd || process.cwd();
   const headSha = supplied.headSha || gitOutput(['rev-parse', 'HEAD'], cwd);
@@ -650,6 +800,9 @@ function mintVerificationVerdict(receipt, payload, projectRoot) {
   }
   return {
     kind,
+    // The sibling checkout the verification ran in (absent for the session root): currency is
+    // judged against THAT checkout's HEAD, never the session root's.
+    ...(sessionRoot && projectRoot !== sessionRoot ? { workspaceRoot: projectRoot } : {}),
     evidence: supplied.evidence || receipt.command || null,
     verifier: supplied.verifier || 'self',
     headSha: headSha || null,
@@ -899,6 +1052,12 @@ function carriedEvidenceLedger(fresh, current) {
       || current.targetedVerificationSucceeded === true,
     sourceFiles: [...new Set([...(current.sourceFiles || []), ...(fresh.sourceFiles || [])])]
       .slice(-MAX_SOURCE_FILES),
+    // Workspace baseline for Bash-mutation attribution: same-prompt re-keys keep it (the router
+    // re-keys on every tool call); a different prompt returns `fresh` above and re-seeds.
+    workspaceFp: current.workspaceFp || fresh.workspaceFp || null,
+    workspaceFps: { ...(current.workspaceFps || {}), ...(fresh.workspaceFps || {}) },
+    inferredWrite: fresh.inferredWrite === true || current.inferredWrite === true,
+    directWrite: fresh.directWrite === true || current.directWrite === true,
     writeAttempted: fresh.writeAttempted || current.writeAttempted === true,
     writeSucceeded: fresh.writeSucceeded || current.writeSucceeded === true,
     verificationAttempted: fresh.verificationAttempted || current.verificationAttempted === true,
@@ -1032,7 +1191,7 @@ const MAX_JOURNAL_SEEN = 64;
 const MAX_JOURNAL_RECORDS = 128;
 const MAX_JOURNAL_QUARANTINE_LINES = 32;
 const LEDGER_EVENT_TYPES = new Set(['receipt', 'continuation', 'notified', 'stop-progress', 'resumable-run']);
-const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding']);
+const RECEIPT_KINDS = new Set(['source', 'write', 'verification', 'playbook-finding', 'workspace']);
 
 function journalPathFor(target) {
   return `${target}.journal`;
@@ -1151,7 +1310,7 @@ function newEventId() {
   return `${Date.now().toString(36)}-${crypto.randomBytes(8).toString('hex')}`;
 }
 
-const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'bashReadOnly', 'exitStatusUnproven'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -1605,7 +1764,46 @@ function applyBugFixFloorReceipt(ledger, receipt) {
   return receipt;
 }
 
-function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
+// Folds the workspace fingerprint into the ledger, then applies the receipt itself. A
+// successful Bash receipt whose fingerprint moved since the last receipt is additionally
+// applied as a synthetic write (fingerprint equality is the only evidence — never the
+// command text). A first observation only seeds the baseline.
+function applyReceiptToLedger(ledger, receipt, options = {}) {
+  if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
+  const fp = typeof receipt.workspaceFp === 'string' && receipt.workspaceFp ? receipt.workspaceFp : null;
+  let base = ledger;
+  if (fp) {
+    // One baseline per checkout: the session root keeps `workspaceFp`; a sibling worktree the
+    // command ran in is keyed by its path, so work in one checkout is never compared against
+    // another checkout's fingerprint.
+    const rootKey = typeof receipt.workspaceRoot === 'string' && receipt.workspaceRoot ? receipt.workspaceRoot : null;
+    const prior = rootKey ? ledger?.workspaceFps?.[rootKey] || null : ledger?.workspaceFp || null;
+    base = rootKey
+      ? { ...ledger, workspaceFps: { ...(ledger?.workspaceFps || {}), [rootKey]: fp } }
+      : { ...ledger, workspaceFp: fp };
+    if (rootKey) {
+      const keys = Object.keys(base.workspaceFps);
+      for (const key of keys.slice(0, Math.max(0, keys.length - 8))) delete base.workspaceFps[key];
+    }
+    if (prior && prior !== fp && receipt.kind === 'workspace' && receipt.toolName === 'Bash' && receipt.success === true && receipt.bashReadOnly !== true) {
+      const applied = applyReceiptCore(base, {
+        ts: receipt.ts,
+        kind: 'write',
+        toolName: 'Bash',
+        toolUseId: receipt.toolUseId,
+        success: true,
+        exitCode: receipt.exitCode,
+        file: `bash-workspace:${fp}`,
+        detail: 'bash-workspace-delta',
+      }, options);
+      if (applied) base = applied.ledger;
+    }
+  }
+  if (receipt.kind === 'workspace') return { ledger: base, value: null };
+  return applyReceiptCore(base, receipt, options);
+}
+
+function applyReceiptCore(ledger, receipt, { vibecode = false } = {}) {
   if (!receipt || typeof receipt !== 'object' || !RECEIPT_KINDS.has(receipt.kind)) return null;
   const next = { ...ledger };
   if (receipt.kind === 'source') {
@@ -1616,6 +1814,10 @@ function applyReceiptToLedger(ledger, receipt, { vibecode = false } = {}) {
   } else if (receipt.kind === 'write') {
     next.writeAttempted = true;
     next.writeSucceeded = next.writeSucceeded || receipt.success;
+    // Evidence tier: a fingerprint-derived Bash delta is inferred (supporting) evidence; only a
+    // tool-attributed Edit/Write is direct.
+    if (receipt.detail === 'bash-workspace-delta') next.inferredWrite = true;
+    else if (receipt.success) next.directWrite = true;
     // A mutation attempt between failures breaks the "no change in between" loop shape.
     if (next.failedVerificationStreak) next.failedVerificationStreak = null;
     // TASK-026 fix round 1: bank the FIRST successful write to this target. Later replays of
@@ -2166,6 +2368,11 @@ export async function recordExecutionReceipt({
   const success = !failed && (exitCode === null || exitCode === 0);
   const toolInput = payload.tool_input || {};
   const evidence = receiptEvidenceAttestation(payload, toolInput);
+  const bashScope = toolName === 'Bash'
+    ? bashWorkspaceScope(toolInput.command, projectRoot)
+    : { root: projectRoot, foreign: false };
+  const workspaceRoot = bashScope.root;
+  const workspaceFp = workspaceFingerprint(workspaceRoot);
   const receipt = {
     ts: Date.now(),
     toolName,
@@ -2180,7 +2387,7 @@ export async function recordExecutionReceipt({
   } else if (toolName === 'Edit' || toolName === 'Write') {
     receipt.kind = 'write';
     receipt.file = toolInput.file_path || toolInput.path || toolInput.paths?.[0] || null;
-  } else if (toolName === 'Bash' && (isVerificationCommand(toolInput.command) || evidence)) {
+  } else if (toolName === 'Bash' && !bashScope.foreign && (isVerificationCommand(toolInput.command) || evidence)) {
     // TASK-009 (BL-011): a Bash command carrying an evidence attestation
     // records as a verification receipt even when the command is not a known
     // test runner — a repro command, a trace, a one-off check. The typed
@@ -2188,6 +2395,13 @@ export async function recordExecutionReceipt({
     // alone must never mint verification evidence.
     receipt.kind = 'verification';
     receipt.command = String(toolInput.command || '').trim();
+    // A pipe-masked runner status (exit 0 from `| tail`) is not evidence of a pass.
+    const maskedStage = isVerificationCommand(toolInput.command) ? maskedVerificationStage(toolInput.command) : null;
+    if (maskedStage && receipt.success) {
+      receipt.success = false;
+      receipt.exitStatusUnproven = true;
+      noteUnprovenExitStatus(maskedStage);
+    }
     // WS-C routed-verification receipt: a command counts as "targeted" when it matches the
     // routed plan (preferredOrder / primaryCommands). Off-plan verification still records
     // as broad — counted only when the route carried no commands at all. The resolved
@@ -2201,12 +2415,21 @@ export async function recordExecutionReceipt({
     // (kind/evidence/verifier/headSha/baseSha/patchId/ts). Explicit payload.verdict
     // fields win so a hook or subagent verifier can attest its own kind and identity.
     if (isVerificationCommand(toolInput.command)) {
-      receipt.verdict = mintVerificationVerdict(receipt, payload, projectRoot);
+      receipt.verdict = mintVerificationVerdict(receipt, payload, workspaceRoot, projectRoot);
     }
+  } else if (toolName === 'Bash' && workspaceFp) {
+    // Any other Bash: no evidence of its own. The receipt only carries the workspace
+    // fingerprint so a verifiable tracked-file change can be attributed at apply time.
+    receipt.kind = 'workspace';
   } else {
     // Untracked tool: no event, no lock, no write — same as the old unlocked early return.
     return { rejected: true, eventId: null };
   }
+  if (workspaceFp) {
+    receipt.workspaceFp = workspaceFp;
+    if (workspaceRoot !== projectRoot) receipt.workspaceRoot = workspaceRoot;
+    if (toolName === 'Bash' && isReadOnlyBashCommand(toolInput.command)) receipt.bashReadOnly = true;
+  }
   if (evidence) {
     receipt.evidence = evidence;
   }
@@ -2474,6 +2697,12 @@ function recoveryInstruction(missingEvidence, ledger = {}, routeSummary = {}, {
   return instruction ?? 'Complete the current routed milestone before stopping.';
 }
 
+// Write evidence that exists only as a Bash workspace delta is supporting evidence, labelled so
+// consumers never mistake it for tool-attributed proof. It never satisfies verification.
+function writeEvidenceTier(ledger = {}) {
+  return ledger.inferredWrite === true && ledger.directWrite !== true ? { evidenceTier: 'inferred' } : {};
+}
+
 export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
   const routeSummary = state?.routeSummary || {};
   // Explicit vibecode autonomy: the user asked UKit to run one prompt to a finished result,
@@ -2581,6 +2810,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
         complete: true,
         outcome: 'verified',
         missingEvidence: [],
+        ...writeEvidenceTier(effectiveLedger),
       };
     }
   }
@@ -2588,7 +2818,7 @@ export function evaluateCompletion({ state = {}, ledger = {}, cwd } = {}) {
     // Silent success: the route is present and every required evidence is satisfied. Marked
     // `complete` so the CLI dispatch recognizes it BEFORE the loud final else — otherwise a
     // bare loud else would turn a clean stop into user-visible noise.
-    return { continue: false, notify: false, complete: true, missingEvidence: [] };
+    return { continue: false, notify: false, complete: true, missingEvidence: [], ...writeEvidenceTier(effectiveLedger) };
   }
 
   // `find-cause` can validly end clean: an investigation may establish that no actionable

package/template_project/.claude/ukit/runtime/handoff-intent.mjs

@@ -34,6 +34,9 @@
 // new enum every consumer would have to learn (TASK-C97-004).
 
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 // The `(?![\w-])` closer is the exact token boundary: a command name followed by
 // MORE name characters or a hyphen (`handoff-fullstack-custom`) is a different,
@@ -349,3 +352,53 @@ export async function transcriptShowsHandoffRun(transcriptPath, opts = {}) {
   if (!known) return null;
   return intent === 'fullstack';
 }
+
+// ─── Worktree scoping ─────────────────────────────────────────────────────
+function gitOut(cwd, args) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', timeout: 800, stdio: ['ignore', 'pipe', 'ignore'] });
+    return r.error || r.status !== 0 ? null : String(r.stdout).trim();
+  } catch {
+    return null;
+  }
+}
+
+function realOrNull(p) {
+  try { return fsSync.realpathSync(p); } catch { return null; }
+}
+
+/**
+ * Which checkout's RUN.md may this Stop be held to? The host pins CLAUDE_PROJECT_DIR
+ * to the primary checkout even when the session works in a linked worktree, so the
+ * primary's cursor used to be enforced on an unrelated worktree session. `payload.cwd`
+ * is only a CANDIDATE: it is honoured solely when git itself proves it is inside a
+ * linked worktree of `projectRoot`'s own repository (same common git dir AND listed by
+ * `git worktree list`). Anything else — an unrelated repo, a plain directory, a
+ * missing path, a non-string — keeps `projectRoot`, so cwd can never be used to dodge
+ * the gate. Returns `projectRoot` unchanged for the primary checkout.
+ */
+export function resolveHandoffRunRoot(projectRoot, cwd) {
+  try {
+    if (typeof projectRoot !== 'string' || !projectRoot || typeof cwd !== 'string' || !cwd || !path.isAbsolute(cwd)) {
+      return projectRoot;
+    }
+    const top = gitOut(cwd, ['rev-parse', '--show-toplevel']);
+    const topReal = top && realOrNull(top);
+    const projectReal = realOrNull(projectRoot);
+    if (!topReal || !projectReal || topReal === projectReal) return projectRoot;
+    const commonOf = (dir) => {
+      const c = gitOut(dir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+      return c && realOrNull(c);
+    };
+    const common = commonOf(projectReal);
+    if (!common || common !== commonOf(topReal)) return projectRoot;
+    const listing = gitOut(projectReal, ['worktree', 'list', '--porcelain']);
+    if (!listing) return projectRoot;
+    const listed = listing.split('\n')
+      .filter((l) => l.startsWith('worktree '))
+      .map((l) => realOrNull(l.slice('worktree '.length)));
+    return listed.includes(topReal) ? topReal : projectRoot;
+  } catch {
+    return projectRoot;
+  }
+}

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -121,6 +121,74 @@ function chainFailureKind(processResult) {
   }
 }
 
+// Micro-fix #6: Claude Code parses a hook's stdout as ONE JSON document. Several chain steps
+// (post-edit-verify, record-execution, task-watchdog on PostToolUse:Edit) each emit their own
+// `{"systemMessage":…}` object, and plain concatenation yields two documents back to back —
+// "Hook output looks like a JSON object but is not valid JSON". When EVERY byte of the replayed
+// stdout is a sequence of top-level JSON objects, merge them into one (serialised with
+// JSON.stringify, never string-spliced). Anything else — plain-text context, a lone document,
+// unparseable text — is returned untouched, so the block/allow policy and context replay are
+// unchanged. Merge rules: systemMessage values join with "\n"; `continue:false` and
+// `decision:"block"` (with its reason) are sticky; any other key: the later step wins.
+function splitTopLevelJsonObjects(text) {
+  const docs = [];
+  let i = 0;
+  const n = text.length;
+  while (i < n) {
+    while (i < n && /\s/.test(text[i])) i += 1;
+    if (i >= n) break;
+    if (text[i] !== '{') return null;
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    let end = -1;
+    for (let j = i; j < n; j += 1) {
+      const ch = text[j];
+      if (inString) {
+        if (escaped) escaped = false;
+        else if (ch === '\\') escaped = true;
+        else if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') inString = true;
+      else if (ch === '{') depth += 1;
+      else if (ch === '}') {
+        depth -= 1;
+        if (depth === 0) { end = j; break; }
+      }
+    }
+    if (end < 0) return null;
+    let parsed;
+    try { parsed = JSON.parse(text.slice(i, end + 1)); } catch { return null; }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+    docs.push(parsed);
+    i = end + 1;
+  }
+  return docs;
+}
+
+function coalesceJsonStdout(text) {
+  if (typeof text !== 'string' || text.length === 0) return text;
+  const docs = splitTopLevelJsonObjects(text);
+  if (!docs || docs.length < 2) return text;
+  const merged = {};
+  const messages = [];
+  for (const d of docs) {
+    for (const [key, value] of Object.entries(d)) {
+      if (key === 'systemMessage') {
+        if (typeof value === 'string' && value) messages.push(value);
+        continue;
+      }
+      if (key === 'continue' && merged.continue === false) continue;
+      if (key === 'decision' && merged.decision === 'block') continue;
+      if (key === 'reason' && merged.decision === 'block' && d.decision !== 'block') continue;
+      merged[key] = value;
+    }
+  }
+  if (messages.length) merged.systemMessage = messages.join('\n');
+  return `${JSON.stringify(merged)}\n`;
+}
+
 // B1 (TASK-001, SPEC §FR-001): a child that emits a `hookSpecificOutput`
 // permission decision owns the verdict. `hookSpecificOutput` alone is NOT
 // enough — a child killed mid-write can carry the marker in a truncated
@@ -792,14 +860,12 @@ try {
         process.stderr.write(gateMsg + breakerAdvice(gateMsg));
         process.exitCode = 2;
       } else if (last.code === 2) {
-        if (contextStdout) process.stdout.write(contextStdout);
-        if (last.stdout) process.stdout.write(last.stdout);
+        process.stdout.write(coalesceJsonStdout(`${contextStdout}${last.stdout || ''}`));
         if (last.stderr) process.stderr.write(last.stderr + breakerAdvice(last.stderr));
         else process.stderr.write(breakerAdvice(`${last.scriptName} blocked (exit 2) with no reason`));
         process.exitCode = 2;
       } else {
-        if (contextStdout) process.stdout.write(contextStdout);
-        if (last.stdout) process.stdout.write(last.stdout);
+        process.stdout.write(coalesceJsonStdout(`${contextStdout}${last.stdout || ''}`));
         // A spawn-unavailable `last` carries only the warning already written above.
         if (last.stderr && last.failureKind !== 'spawn-unavailable') process.stderr.write(last.stderr);
         process.exitCode = last.code === 0 ? 0 : (lastIsFailClosed ? 2 : 0);

package/template_project/.claude/ukit/runtime/safe-patch-core.mjs

@@ -1,5 +1,7 @@
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 export const DEFAULT_SAFE_PATCH_CONFIG = {
   enabled: true,
@@ -78,6 +80,75 @@ export function resolveProjectFile(projectRoot, filePath) {
   };
 }
 
+function realpathNearest(absolute) {
+  // Real path of the deepest existing ancestor + the not-yet-existing tail, so a Write
+  // that creates a new file is judged by where it would actually land (symlinks resolved).
+  let probe = absolute;
+  const tail = [];
+  for (;;) {
+    try {
+      return path.join(fsSync.realpathSync(probe), ...tail.reverse());
+    } catch {
+      const parent = path.dirname(probe);
+      if (parent === probe) return null;
+      tail.push(path.basename(probe));
+      probe = parent;
+    }
+  }
+}
+
+function listedLinkedWorktrees(projectRoot) {
+  // `git worktree list` run from the project root only names worktrees of THIS repository.
+  try {
+    const r = spawnSync('git', ['worktree', 'list', '--porcelain'], {
+      cwd: projectRoot, encoding: 'utf8', timeout: 800, stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (r.error || r.status !== 0) return [];
+    const projectReal = fsSync.realpathSync(projectRoot);
+    return String(r.stdout).split('\n')
+      .filter((line) => line.startsWith('worktree '))
+      .map((line) => { try { return fsSync.realpathSync(line.slice('worktree '.length)); } catch { return null; } })
+      .filter((dir) => dir && dir !== projectReal);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Edit/Write target resolver for the Safe Patch hooks. CLAUDE_PROJECT_DIR stays pinned to the
+ * primary checkout, so a file in a linked worktree is lexically "outside" it. The strict
+ * resolveProjectFile contract is tried first and is unchanged; only when it rejects does the
+ * target get a second chance, and only if its REAL path (symlinks resolved) lies inside a
+ * worktree that git lists for this same repository and not inside that worktree's `.git`.
+ * Anything else rethrows the original "Path escapes project root" error.
+ * `relative` is worktree-relative (risk classification); `key` is the project-root-relative
+ * identity used for backup manifests so primary and worktree copies of one path never collide.
+ */
+export function resolveEditTarget(projectRoot, filePath) {
+  try {
+    const resolved = resolveProjectFile(projectRoot, filePath);
+    return resolved && { ...resolved, key: resolved.relative };
+  } catch (error) {
+    const root = path.resolve(projectRoot || process.cwd());
+    const absolute = path.resolve(String(filePath).trim());
+    const real = path.isAbsolute(String(filePath).trim()) ? realpathNearest(absolute) : null;
+    if (real) {
+      for (const worktree of listedLinkedWorktrees(root)) {
+        const inside = path.relative(worktree, real);
+        if (!inside || inside.startsWith('..') || path.isAbsolute(inside)) continue;
+        if (inside.split(path.sep)[0] === '.git') break;
+        return {
+          absolute: real,
+          relative: normalizeRelativePath(inside),
+          key: normalizeRelativePath(path.relative(root, real)),
+          worktreeRoot: worktree,
+        };
+      }
+    }
+    throw error;
+  }
+}
+
 export async function pathExists(filePath) {
   try {
     await fs.access(filePath);

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -956,13 +956,17 @@ async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
  *
  * Advisory lane: EVERY failure path returns { kind: 'none' }, never throws.
  */
-export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false } = {}) {
+export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null, stopHookActive = false } = {}) {
+  // `runRoot` is the checkout whose RUN.md cursor this session may be held to: the
+  // git-verified linked worktree when the session runs in one, else `projectRoot`.
+  // Policy (gate config) stays with `projectRoot`; the cursor, its exit predicate
+  // and its stall state are per-checkout.
   const gate = await loadHandoffGateConfig(projectRoot);
   if (!gate.enabled) return { kind: 'none' };
 
   let text;
   try {
-    text = await fs.readFile(path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    text = await fs.readFile(path.join(runRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
   } catch {
     return { kind: 'none' };
   }
@@ -988,7 +992,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   if (terminal === 'done') {
     let predicate;
     try {
-      predicate = await evaluateExitPredicate(projectRoot, exitPredicate);
+      predicate = await evaluateExitPredicate(runRoot, exitPredicate);
     } catch {
       return { kind: 'none' }; // advisory lane: evaluator failure never wedges a stop
     }
@@ -1023,7 +1027,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   }
 
   const signature = `${phase}|${cursor}|${next}`;
-  const streak = await bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs });
+  const streak = await bumpHandoffStallCount({ projectRoot: runRoot, signature, lockBudgetMs });
   // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
   // inside the continuation turn WE forced. The same cursor signature seen again
   // (streak > 1) means that continuation made no cursor progress — blocking again
@@ -1042,7 +1046,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
     let predicateState = 'no ExitPredicate recorded';
     if (exitPredicate) {
       try {
-        predicateState = formatPredicateState(await evaluateExitPredicate(projectRoot, exitPredicate));
+        predicateState = formatPredicateState(await evaluateExitPredicate(runRoot, exitPredicate));
       } catch {
         predicateState = 'predicate evaluation failed';
       }
@@ -1206,6 +1210,16 @@ export async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now,
   }
 }
 
+// ─── Worktree scoping ─────────────────────────────────────────────────────
+// The resolver lives in the shared handoff-intent module (also used by the
+// SessionStart resume hook). Unavailable module → the primary `projectRoot`, i.e.
+// the pre-existing, stricter behaviour.
+async function resolveRunRoot(projectRoot, cwd) {
+  const mod = await loadHandoffIntentModule();
+  if (!mod || typeof mod.resolveHandoffRunRoot !== 'function') return projectRoot;
+  return mod.resolveHandoffRunRoot(projectRoot, cwd);
+}
+
 // ─── Orchestration ────────────────────────────────────────────────────────
 /**
  * One coordinator invocation: event guard → once-per-stop dedupe → completion
@@ -1276,6 +1290,7 @@ export async function runStopCoordinator({
   try {
     handoff = await evaluateHandoffCursor({
       projectRoot,
+      runRoot: await resolveRunRoot(projectRoot, payload?.cwd),
       now,
       lockBudgetMs,
       transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,