@ngockhoale/ukit 3.4.27 → 3.4.29

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

@@ -501,15 +501,17 @@ function extractExitCode(payload = {}) {
   return null;
 }
 
+// The trailing boundary accepts shell terminators (`;`, `&`, `|`, `)`) so
+// `yarn release:verify; echo "exit=$?"` — the real-exit-code idiom — still mints a receipt.
 function isVerificationCommand(command) {
   const text = String(command || '').trim();
   if (!text) return false;
   return [
-    /(?:^|\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)(?: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,
+    /(?:^|\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)(?: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));
 }
 
@@ -624,10 +626,13 @@ function gitOutput(args, cwd) {
 // 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) {
+function bashWorkspaceScope(command, projectRoot, shellCwd) {
   const here = { root: projectRoot, foreign: false };
   const match = String(command || '').match(/^\s*cd\s+(?:"([^"]+)"|'([^']+)'|([^\s;&|<>$`~]+))\s*(?:&&|;)/);
-  if (!match || !projectRoot) return here;
+  // 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);
@@ -637,7 +642,7 @@ function bashWorkspaceScope(command, 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 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);
@@ -1166,6 +1171,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(),
   };
 }
@@ -1310,7 +1316,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', 'workspaceRoot', 'bashReadOnly', 'exitStatusUnproven'];
+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
@@ -1785,7 +1791,11 @@ function applyReceiptToLedger(ledger, receipt, options = {}) {
       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) {
+    // 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',
@@ -2369,7 +2379,7 @@ export async function recordExecutionReceipt({
   const toolInput = payload.tool_input || {};
   const evidence = receiptEvidenceAttestation(payload, toolInput);
   const bashScope = toolName === 'Bash'
-    ? bashWorkspaceScope(toolInput.command, projectRoot)
+    ? bashWorkspaceScope(toolInput.command, projectRoot, payload.cwd)
     : { root: projectRoot, foreign: false };
   const workspaceRoot = bashScope.root;
   const workspaceFp = workspaceFingerprint(workspaceRoot);
@@ -2427,7 +2437,11 @@ export async function recordExecutionReceipt({
   }
   if (workspaceFp) {
     receipt.workspaceFp = workspaceFp;
-    if (workspaceRoot !== projectRoot) receipt.workspaceRoot = workspaceRoot;
+    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

@@ -402,3 +402,11 @@ export function resolveHandoffRunRoot(projectRoot, cwd) {
     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/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 };
+}

package/template_project/.claude/ukit/runtime/observability-emit.mjs

@@ -1088,6 +1088,15 @@ function outcomeCost(value) {
   };
 }
 
+// A3 (C100 O8): agent/model/provider linkage. Nullable and additive: a value the hook payload
+// or emitter did not supply stays null (UNKNOWN) — never a guess, never 0, never inferred from a model name.
+function linkageField(...candidates) {
+  for (const value of candidates) {
+    if (typeof value === 'string' && value.trim().length > 0) return value.trim().slice(0, 96);
+  }
+  return null;
+}
+
 /**
  * buildOutcomeObservedRecord({ outcome, projectRoot, payload, sessionId,
  * engine, env }) → semantic-record candidate for `outcome.observed`.
@@ -1135,6 +1144,11 @@ export function buildOutcomeObservedRecord({
     implementer: isNonEmptyString(safe.implementer) ? safe.implementer.slice(0, 96) : null,
     reviewer: isNonEmptyString(safe.reviewer) ? safe.reviewer.slice(0, 96) : null,
     reviewVerdict: isNonEmptyString(safe.reviewVerdict) ? safe.reviewVerdict.slice(0, 96) : null,
+    agentId: linkageField(safe.agentId, payload?.agent_id),
+    parentAgentId: linkageField(safe.parentAgentId, payload?.parent_agent_id),
+    agentType: linkageField(safe.agentType, payload?.agent_type),
+    model: linkageField(safe.model, payload?.model),
+    provider: linkageField(safe.provider),
     enforcement: OUTCOME_ENFORCEMENTS.has(safe.enforcement)
       ? safe.enforcement
       : deriveEnforcement({ engine: engineName, env }),

package/template_project/.claude/ukit/runtime/read-advisory.mjs

@@ -0,0 +1,92 @@
+// read-advisory.mjs — C100 O4: advisory note when the SAME unchanged file region is read again.
+//
+// Evidence (docs/analysis/c100): implementer sessions re-read one file up to 31 times; every
+// repeat enlarges the context that is re-billed on all later calls. This module only REMINDS —
+// it never blocks, never alters tool output, never touches the verdict.
+//
+// A read counts as a repeat only when path, mtimeMs, size AND offset/limit all match the previous
+// read in the same (session, agent). Any Edit/Write by the agent changes mtime/size, a different
+// region has a different offset/limit, so a legitimate re-read is never flagged.
+//
+// Contract: advisory end-to-end (every failure returns ''), bounded state, metadata only (no file
+// content, no raw paths on disk: paths are sha1-hashed), kill switch UKIT_READ_ADVISORY=0.
+//
+// KNOWN LIMITS (A5 review): (1) emitted as `systemMessage`; on Claude Code that is documented as
+// user-visible, model visibility is UNVERIFIED (the model-visible channel is
+// hookSpecificOutput.additionalContext, but the chain runner treats any hookSpecificOutput as a
+// permission-verdict owner, so it is not used here). omp surfaces hook output in the tool result;
+// Codex is not wired. (2) One fingerprint per path: alternating regions A,B,A resets the count.
+// (3) Per-session state files are not pruned.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_ENTRIES = 200;
+const MAX_STATE_BYTES = 64 * 1024;
+
+function safeName(value) {
+  return String(value || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
+}
+
+function hash12(text) {
+  return crypto.createHash('sha1').update(text).digest('hex').slice(0, 12);
+}
+
+function intOrNull(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+// Emit on the 2nd identical read, then at 4, 8, 16, ... so a loop cannot flood the channel.
+function shouldNotify(count) {
+  return count >= 2 && (count & (count - 1)) === 0;
+}
+
+export function readAdvisoryMessage({ payload, projectRoot, env = process.env } = {}) {
+  try {
+    if (env.UKIT_READ_ADVISORY === '0') return '';
+    if (!payload || payload.tool_name !== 'Read') return '';
+    const input = payload.tool_input;
+    const rawPath = input && typeof input.file_path === 'string' ? input.file_path : '';
+    if (!rawPath || !projectRoot) return '';
+    const response = payload.tool_response;
+    if (response && (response.isError === true || response.is_error === true)) return '';
+
+    const abs = path.resolve(projectRoot, rawPath);
+    const st = fs.statSync(abs);
+    if (!st.isFile()) return '';
+
+    const fingerprint = [st.mtimeMs, st.size, intOrNull(input.offset), intOrNull(input.limit), input.pages ?? null].join(':');
+    const key = hash12(abs);
+    const scope = `${safeName(payload.session_id)}.${safeName(payload.agent_id || 'main')}`;
+    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'read-advisory');
+    const file = path.join(dir, `${scope}.json`);
+
+    let state = {};
+    try {
+      if (fs.statSync(file).size <= MAX_STATE_BYTES) state = JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+    } catch { state = {}; }
+    if (!state || typeof state !== 'object' || Array.isArray(state)) state = {};
+
+    const prev = state[key];
+    const count = prev && prev.fp === fingerprint ? prev.count + 1 : 1;
+    state[key] = { fp: fingerprint, count, at: Date.now() };
+
+    const keys = Object.keys(state);
+    if (keys.length > MAX_ENTRIES) {
+      keys.sort((a, b) => (state[a].at || 0) - (state[b].at || 0));
+      for (const k of keys.slice(0, keys.length - MAX_ENTRIES)) delete state[k];
+    }
+    fs.mkdirSync(dir, { recursive: true });
+    // temp + rename: parallel Reads must never leave a torn state file.
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(state));
+    fs.renameSync(tmp, file);
+
+    if (!shouldNotify(count)) return '';
+    const name = path.basename(abs);
+    return `UKit read-advisory: ${name} was read ${count}x unchanged (same region) in this session — reuse the earlier read instead of re-reading.`;
+  } catch {
+    return '';
+  }
+}

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

@@ -1026,6 +1026,17 @@ export async function evaluateHandoffCursor({ projectRoot, runRoot = projectRoot
     return { kind: 'none' };
   }
 
+  // PAUSED run: never force continuation.
+  const intentMod = await loadHandoffIntentModule();
+  if (intentMod?.runCursorPaused?.(text) === true) {
+    return {
+      kind: 'advisory',
+      waitForApproval: true,
+      systemMessage: '[ukit-stop-coordinator] handoff run is PAUSED: stop allowed, nothing is resumed or forced. '
+        + 'Only an explicit user instruction (/ukit:handoff-fullstack or "continue") lifts the pause.',
+    };
+  }
+
   const signature = `${phase}|${cursor}|${next}`;
   const streak = await bumpHandoffStallCount({ projectRoot: runRoot, signature, lockBudgetMs });
   // Reentrancy valve (stop_hook_active): Claude Code sets it when this Stop fires
@@ -1301,7 +1312,20 @@ export async function runStopCoordinator({
     process.stderr.write(`[ukit-stop-coordinator] handoff-cursor evaluator failed: ${failures.handoff}\n`);
   }
 
-  const merged = coordinateStopDecisions({ completion, watchdog, handoff, failures });
+  let merged = coordinateStopDecisions({ completion, watchdog, handoff, failures });
+
+  // Bounded loop detection (fail-closed infra block keeps its own cap).
+  try {
+    const loop = await import('./loop-state.mjs');
+    merged = await loop.applyLoopBreak({ merged, projectRoot, runRoot: await resolveRunRoot(projectRoot, payload?.cwd), payload, sessionKey, now, lockBudgetMs });
+  } catch { /* detector failure keeps the original decision */ }
+
+  // Termination contract (label only; no new hook, no LLM): every coordinated stop ends in one
+  // outcome. A loop-breaker release is BLOCKED_AND_STOP, never approval; a PAUSED run waits.
+  // Advisory label only (nothing consumes it); a gate block approves nothing.
+  merged.terminalOutcome = merged.decision === 'block' ? 'CONTINUE_REQUIRED'
+    : merged.loopBreak === true ? 'BLOCKED_AND_STOP'
+    : handoff?.waitForApproval === true ? 'WAIT_FOR_APPROVAL' : 'COMPLETE_AND_STOP';
 
   // C85 TASK-015 (BL-015): advisory review-policy verdict. The evaluator runs
   // only when a route record exists; its action + namedCheck are recorded on
@@ -1327,6 +1351,14 @@ export async function runStopCoordinator({
     }
   } catch { /* advisory verdicts never affect the stop decision */ }
 
+  // C100 MB-1b: stage-gated (default off) shadow capture of per-call usage
+  // metadata from the host transcript. Observation only; never affects the
+  // stop decision and never throws.
+  try {
+    const { captureUsageShadow } = await import('./usage-capture.mjs');
+    await captureUsageShadow({ projectRoot, payload });
+  } catch { /* advisory */ }
+
   // TASK-005 (FR-005): the coordinator's terminal verdict lands ONE
   // `outcome.observed` record per coordinated stop — the merged evaluator
   // decision is the session's honest outcome at this stop. Fire-and-forget: