@ngockhoale/ukit 3.4.26 → 3.4.28

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/index/route-task.mjs

@@ -4220,6 +4220,9 @@ function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
   const WAIT_TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and|nhung|roi|then|later|sau\\s+do)\\s+[^.,;\\n]*?\\b(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\\s+the|cap\\s+nhat|viet|chay|cai|chinh|trien\\s+khai|cau\\s+hinh)(?![A-Za-z0-9_])|[.,;]|\\s*$)';
   const residue = trimmed
     .replace(/"[^"\n]*"|«[^»\n]*»/g, ' ')
+    // Descriptive state, not an order: "đã/vừa [được] + verb" ("hooks vừa được cài đặt") reports
+    // something already done. Only the verb is stripped, so a later imperative still survives.
+    .replace(/(?<![a-z0-9_])(?:da|vua)\s+(?:duoc\s+)?(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\s+the|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh)(?![a-z0-9_])/g, ' ')
     .replace(/\bwrite-evidence\b|\bverification-evidence\b|\bimpact-evidence\b|\broot-cause\b/g, ' ')
     .replace(new RegExp(`\\bgiu\\s+nguyen\\b${TAIL}`, 'g'), ' ')
     .replace(new RegExp(`\\bmuon\\s+giu\\b${TAIL}`, 'g'), ' ')

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,34 @@ 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, shellCwd) {
+  const here = { root: projectRoot, foreign: false };
+  const match = String(command || '').match(/^\s*cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|<>$`~]+))\s*(?:&&|;)/);
+  // The host reports the shell's cwd: a session that already `cd`-ed into a linked worktree
+  // runs bare commands there, with no leading `cd` to parse.
+  const cwdDir = typeof shellCwd === 'string' && path.isAbsolute(shellCwd) ? shellCwd : null;
+  if ((!match && !cwdDir) || !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(match ? path.resolve(cwdDir || projectRoot, match[1] || match[2] || match[3]) : cwdDir);
+  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
@@ -640,6 +739,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 —
@@ -676,9 +783,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);
@@ -696,6 +803,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,
@@ -948,6 +1058,7 @@ function carriedEvidenceLedger(fresh, current) {
     // 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,
@@ -1058,6 +1169,7 @@ function freshLedger(payload, routeState, harness) {
     // TASK-005 (FR-005): OutcomeRecord dedupe ledger ({verdict, runKey, at}).
     // Emitted-once for INTERRUPTED survives re-keys via carriedEvidenceLedger.
     outcomes: [],
+    startedAt: Date.now(),
     updatedAt: Date.now(),
   };
 }
@@ -1202,7 +1314,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', 'workspaceFp', 'bashReadOnly'];
+const JOURNAL_RECEIPT_FIELDS = ['ts', 'kind', 'toolName', 'toolUseId', 'success', 'exitCode', 'file', 'command', 'scope', 'workspaceFp', 'workspaceRoot', 'workspaceHeadTs', 'bashReadOnly', 'exitStatusUnproven'];
 
 // TASK-009 (BL-011): evidence attestations are whitelisted verbatim — class /
 // surface / result / claim, the ARCH §Evidence Schema fields a receipt may
@@ -1665,9 +1777,23 @@ function applyReceiptToLedger(ledger, receipt, options = {}) {
   const fp = typeof receipt.workspaceFp === 'string' && receipt.workspaceFp ? receipt.workspaceFp : null;
   let base = ledger;
   if (fp) {
-    const prior = ledger?.workspaceFp || null;
-    base = { ...ledger, workspaceFp: fp };
-    if (prior && prior !== fp && receipt.kind === 'workspace' && receipt.toolName === 'Bash' && receipt.success === true && receipt.bashReadOnly !== true) {
+    // 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];
+    }
+    // First sight of a linked worktree: no baseline to diff, so credit only a HEAD commit newer
+    // than this session's ledger (never a historical commit, never a read-only command).
+    const firstSeenNewCommit = Boolean(rootKey && !prior && receipt.workspaceHeadTs > 0
+      && ledger?.startedAt > 0 && receipt.workspaceHeadTs >= Math.floor(ledger.startedAt / 1000) * 1000); // %ct has 1 s resolution
+    if ((firstSeenNewCommit || (prior && prior !== fp)) && receipt.kind === 'workspace' && receipt.toolName === 'Bash' && receipt.success === true && receipt.bashReadOnly !== true) {
       const applied = applyReceiptCore(base, {
         ts: receipt.ts,
         kind: 'write',
@@ -2250,7 +2376,11 @@ export async function recordExecutionReceipt({
   const success = !failed && (exitCode === null || exitCode === 0);
   const toolInput = payload.tool_input || {};
   const evidence = receiptEvidenceAttestation(payload, toolInput);
-  const workspaceFp = workspaceFingerprint(projectRoot);
+  const bashScope = toolName === 'Bash'
+    ? bashWorkspaceScope(toolInput.command, projectRoot, payload.cwd)
+    : { root: projectRoot, foreign: false };
+  const workspaceRoot = bashScope.root;
+  const workspaceFp = workspaceFingerprint(workspaceRoot);
   const receipt = {
     ts: Date.now(),
     toolName,
@@ -2265,7 +2395,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
@@ -2273,6 +2403,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
@@ -2286,7 +2423,7 @@ 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
@@ -2298,6 +2435,11 @@ export async function recordExecutionReceipt({
   }
   if (workspaceFp) {
     receipt.workspaceFp = workspaceFp;
+    if (workspaceRoot !== projectRoot) {
+      receipt.workspaceRoot = workspaceRoot;
+      const ct = Number(gitOutput(['log', '-1', '--format=%ct'], workspaceRoot));
+      if (Number.isFinite(ct) && ct > 0) receipt.workspaceHeadTs = ct * 1000;
+    }
     if (toolName === 'Bash' && isReadOnlyBashCommand(toolInput.command)) receipt.bashReadOnly = true;
   }
   if (evidence) {

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,61 @@ 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;
+  }
+}
+
+// Paused: `Paused: yes`, `Phase: paused`, or token PAUSED in Cursor/Next. Never resume/spawn; RUN.md untouched.
+export function runCursorPaused(text) {
+  const field = (name) => (String(text || '').match(new RegExp(`^${name}:\\s*(.+)$`, 'm'))?.[1] || '').trim();
+  if (/^(?:yes|true|1)\b/i.test(field('Paused'))) return true;
+  if (/^paused\b/i.test(field('Phase'))) return true;
+  return /\bPAUSED\b/.test(field('Cursor')) || /\bPAUSED\b/.test(field('Next'));
+}

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/loop-state.mjs

@@ -0,0 +1,131 @@
+// Deterministic local loop detection for Stop blocks (no LLM/network). Release is not approval.
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { withAsyncLock } from './async-lock.mjs';
+
+const DEFAULTS = { enabled: true, maxNoProgressBlocks: 3 };
+const MAX_SESSIONS = 20;
+const MAX_CAUSES = 20;
+const cache = (root, name) => path.join(root, '.ukit', 'storage', 'cache', name);
+const sha = (t) => crypto.createHash('sha1').update(String(t)).digest('hex').slice(0, 16);
+const readJson = async (f, d) => { try { const v = JSON.parse(await fs.readFile(f, 'utf8')); return v && typeof v === 'object' ? v : d; } catch { return d; } };
+async function writeJson(f, v) {
+  await fs.mkdir(path.dirname(f), { recursive: true });
+  const tmp = `${f}.${process.pid}.${Date.now()}.tmp`;
+  await fs.writeFile(tmp, `${JSON.stringify(v)}\n`, 'utf8');
+  await fs.rename(tmp, f);
+}
+
+export function reasonCodeFor(owner, reason) {
+  const norm = String(reason || '').split('\n', 1)[0]
+    .replace(/'[^']*'|"[^"]*"/g, '<Q>').replace(/(?:[A-Za-z]:)?[\\/][\w.\-@\\/]+/g, '<P>')
+    .replace(/\d+/g, 'N').replace(/\s+/g, ' ').trim().slice(0, 160);
+  return `${owner || 'unknown'}:${sha(norm)}`;
+}
+
+export async function loadLoopConfig(root) {
+  const c = (await readJson(path.join(root, '.ukit', 'storage', 'config.json'), {})).loopBreaker || {};
+  const num = (v, d) => (Number.isFinite(v) ? Math.max(1, v) : d);
+  return {
+    enabled: typeof c.enabled === 'boolean' ? c.enabled : DEFAULTS.enabled,
+    maxNoProgressBlocks: Math.floor(num(c.maxNoProgressBlocks, DEFAULTS.maxNoProgressBlocks)),
+  };
+}
+
+// Task-relevant evidence only: RUN.md cursor, banked ledger evidence, trusted prompt.
+export async function progressFingerprint(root, runRoot = root, payload = {}) {
+  let cur = 'no-run';
+  try {
+    const t = await fs.readFile(path.join(runRoot, 'docs', 'AI_HANDOFF', 'RUN.md'), 'utf8');
+    cur = ['Phase', 'Cursor', 'Next'].map((n) => t.match(new RegExp(`^${n}:\\s*(.+)$`, 'm'))?.[1] || '').join('|');
+  } catch {}
+  const id = payload.session_id ? String(payload.session_id).trim().replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96)
+    : payload.transcript_path ? `transcript-${crypto.createHash('sha256').update(String(payload.transcript_path)).digest('hex').slice(0, 20)}` : 'default';
+  const led = await readJson(cache(root, path.join('exec-ledger', `${id || 'default'}.json`)), {});
+  const bank = (f) => Object.keys(led[f] && typeof led[f] === 'object' ? led[f] : {}).sort();
+  const rc = (await readJson(path.join(root, '.claude', 'ukit', 'skill-router-state.json'), {})).routingContext || {};
+  return sha(JSON.stringify([cur, bank('bankedWrites'), bank('bankedVerifications'), rc.lastExplicitUserPromptText || '', rc.mutationOrder, rc.planOnly]));
+}
+
+// Mode: router-stamped routingContext only.
+export async function trustedTaskMode(root) {
+  const rc = (await readJson(path.join(root, '.claude', 'ukit', 'skill-router-state.json'), {})).routingContext || {};
+  if (rc.planOnly === true) return 'REPORT_ONLY';
+  if (rc.mutationOrder === false) return 'READ_ONLY';
+  return rc.mutationOrder === true ? 'IMPLEMENTATION' : null;
+}
+
+export async function recordBlock({ projectRoot, sessionId, hookEvent = 'Stop', reasonCode, cause = reasonCode, fingerprint, taskExecutionMode = null, stopHookActive = false, now = Date.now(), cfg, lockBudgetMs = 600 }) {
+  if (!projectRoot || !sessionId || !reasonCode) return null;
+  const config = cfg || await loadLoopConfig(projectRoot);
+  const stateFile = cache(projectRoot, 'loop-state.json');
+  const run = async () => {
+    const state = await readJson(stateFile, {});
+    const sessions = state.sessions && typeof state.sessions === 'object' ? state.sessions : {};
+    const sid = String(sessionId).slice(0, 80);
+    const causes = sessions[sid] || (sessions[sid] = {});
+    const key = `${hookEvent}|${cause}`;
+    const prev = causes[key];
+    const repeated = Boolean(prev);
+    const progressChanged = repeated && prev.progressFingerprint !== fingerprint;
+    const stale = repeated && !progressChanged;
+    // Terminal records persist (LRU-bounded) until task-relevant progress.
+    const term = stale && prev.terminal === true;
+    const rec = {
+      sessionId: sid, hookEvent, reasonCode, progressFingerprint: fingerprint,
+      attemptCount: stale ? prev.attemptCount + (term ? 0 : 1) : 1,
+      firstBlockedAt: stale ? prev.firstBlockedAt : now, lastBlockedAt: now,
+      progressChanged, taskExecutionMode: taskExecutionMode || 'UNKNOWN',
+    };
+    const quick = stale && (stopHookActive === true || taskExecutionMode === 'READ_ONLY' || taskExecutionMode === 'REPORT_ONLY');
+    const limitReached = term || rec.attemptCount > config.maxNoProgressBlocks || quick;
+    if (limitReached) rec.terminal = true;
+    causes[key] = rec;
+    // Retention: never evict the current record; terminal records go last. Beyond 20 terminal
+    // sessions/causes the oldest terminal one is dropped and gets one fresh bounded budget.
+    const keep = (o, cur, max) => Object.keys(o).sort((a, b) => (b === cur) - (a === cur) || rank(o[b]) - rank(o[a])).slice(max);
+    const rank = (v) => (v.terminal || Object.values(v).some((x) => x.terminal) ? 1e15 : 0) + (v.lastBlockedAt || Math.max(0, ...Object.values(v).map((x) => x.lastBlockedAt || 0)));
+    for (const id of keep(sessions, sid, MAX_SESSIONS)) delete sessions[id];
+    for (const k of keep(causes, key, MAX_CAUSES)) delete causes[k];
+    await writeJson(stateFile, { sessions });
+    const mf = cache(projectRoot, 'loop-metrics.json');
+    const m = await readJson(mf, {});
+    const inc = (k) => { m[k] = (m[k] || 0) + 1; };
+    inc('stop_block_count');
+    if (repeated) inc('repeated_block_count');
+    if (stale) inc('retry_without_progress');
+    if (limitReached && !term) {
+      inc('loop_break_count');
+      m.time_to_safe_stop_ms_last = now - rec.firstBlockedAt;
+    }
+    await writeJson(mf, m);
+    return { attemptCount: rec.attemptCount, limitReached, firstBlockedAt: rec.firstBlockedAt };
+  };
+  try {
+    const out = await withAsyncLock(stateFile, { deadlineMs: lockBudgetMs }, run);
+    if (out.ok) return out.value;
+  } catch {}
+  try { return await run(); } catch { return null; }
+}
+
+export async function applyLoopBreak({ merged, projectRoot, runRoot, payload, sessionKey, now, lockBudgetMs }) {
+  if (merged.decision !== 'block' || merged.policyOwner === 'fail-closed') return merged;
+  const cfg = await loadLoopConfig(projectRoot);
+  if (!cfg.enabled) return merged;
+  const mode = await trustedTaskMode(projectRoot);
+  const res = await recordBlock({
+    projectRoot, sessionId: sessionKey, reasonCode: reasonCodeFor(merged.policyOwner, merged.reason), cause: merged.policyOwner || 'unknown',
+    fingerprint: await progressFingerprint(projectRoot, runRoot, payload), taskExecutionMode: mode,
+    stopHookActive: payload?.stop_hook_active === true, now, cfg, lockBudgetMs,
+  });
+  if (!res?.limitReached) return merged;
+  const minutes = Math.max(0, Math.round((now - res.firstBlockedAt) / 60_000));
+  const note = [
+    `[ukit-loop-breaker] BLOCKED/ESCALATED: ${merged.policyOwner} refused this stop ${res.attemptCount - 1} consecutive times with no change in the work state (~${minutes} min, mode ${mode || 'UNKNOWN'}).`,
+    `Unresolved blocker: ${String(merged.reason || '').split('\n', 1)[0].slice(0, 200)}`,
+    'Stop released. This is NOT approval: nothing was verified and no safety/permission denial is lifted.',
+    'Report it verbatim; do not retry, wake up, or resume any handoff.',
+  ].join('\n');
+  return { ...merged, decision: null, reason: undefined, loopBreak: true, policyOwner: 'loop-breaker', systemMessage: merged.systemMessage ? `${note}\n${merged.systemMessage}` : note };
+}