@ngockhoale/ukit 3.4.26 → 3.4.28

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/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
     }
@@ -1022,8 +1026,19 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
     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, 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 +1057,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 +1221,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 +1301,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,
@@ -1286,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
@@ -1312,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:

package/template_project/.claude/ukit/runtime/usage-capture.mjs

@@ -0,0 +1,338 @@
+#!/usr/bin/env node
+// usage-capture.mjs — C100 MB-1b: SHADOW capture of per-call usage metadata.
+//
+// Attached to the EXISTING Stop event (stop-coordinator.mjs) — no extra hook
+// invocation. Stage-gated by `.ukit/storage/config.json` -> usageCapture.stage;
+// absent / 'off' / anything but 'shadow' emits nothing. Observation only: it
+// never changes a routing, stop or tool decision, makes no network or LLM call.
+//
+// Reads the host transcript INCREMENTALLY: a per-session byte cursor means each
+// Stop reads only bytes appended since the previous Stop, never more than
+// MAX_READ_BYTES. Rows are metadata only — no prompt, response, tool input,
+// credential or credentialId is ever copied.
+//
+// Provenance: every row read from a host transcript is HOST_TRANSCRIPT.
+// providerId / gatewayId are identity metadata copied from explicit record keys;
+// they are NOT evidence of who measured the usage. PROVIDER / GATEWAY would need
+// an authenticated source (none exists yet), so they are never emitted here.
+//
+// Completeness: the capture is bounded, so it can be incomplete. Every gap
+// (skipped history, backlog, truncation/rotation, unparsable usage lines, row
+// cap, log rotation, lock timeout, deadline) is written as a `kind:'coverage'`
+// record and a sticky per-session flag. Consumers must treat a session with any
+// partial coverage as partial and never report its cache hit-rate as complete
+// (see summarizeUsageRows).
+//
+// Delivery is at-least-once with dedupe: a crash between the log append and the
+// cursor write replays the window; rows already present in the bounded log tail
+// are skipped by dedupeKey.
+//
+// Engines: Claude Code transcripts (snake_case usage) are supported; omp's
+// camelCase shape is parsed when handed in but the omp bridge does not call this
+// module yet; Codex is explicitly unsupported.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { withAsyncLock } from './async-lock.mjs';
+
+export const USAGE_ROW_VERSION = 1;
+export const MAX_READ_BYTES = 1024 * 1024;
+export const MAX_ROWS_PER_STOP = 5000;
+export const MAX_LOG_BYTES = 256 * 1024;
+export const DEDUPE_TAIL_BYTES = 64 * 1024;
+export const CAPTURE_DEADLINE_MS = 250;
+const LOCK_DEADLINE_MS = 150;
+
+const CACHE_STATUS = Object.freeze({ ZERO: 'present_zero', POSITIVE: 'present_positive', ABSENT: 'absent', INVALID: 'invalid' });
+const READ_KEYS = ['cache_read_input_tokens', 'cache_read_tokens', 'cacheRead'];
+const WRITE_KEYS = ['cache_creation_input_tokens', 'cache_creation_tokens', 'cacheWrite'];
+const SAFE_ID = /^[A-Za-z0-9._:/@-]{1,128}$/;
+const SECRET_LIKE = /sk-[A-Za-z0-9]{8,}|bearer|secret|passw|token=|key=|api[_-]?key/i;
+const PROVIDER_KEYS = ['providerId', 'provider_id', 'provider', 'apiProvider'];
+const GATEWAY_KEYS = ['gatewayId', 'gateway_id', 'gatewayName', 'gateway'];
+
+export function resolveUsageCaptureStage(config) {
+  return config?.usageCapture?.stage === 'shadow' ? 'shadow' : 'off';
+}
+
+export function classifyCache(usage, keys) {
+  if (!usage || typeof usage !== 'object') return { status: CACHE_STATUS.ABSENT, value: null };
+  for (const key of keys) {
+    const raw = usage[key];
+    if (raw === undefined || raw === null) continue;
+    if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 0) return { status: CACHE_STATUS.INVALID, value: null };
+    return { status: raw === 0 ? CACHE_STATUS.ZERO : CACHE_STATUS.POSITIVE, value: raw };
+  }
+  return { status: CACHE_STATUS.ABSENT, value: null };
+}
+
+export function cacheMetadataStatus(read, write) {
+  if (read.status === CACHE_STATUS.INVALID || write.status === CACHE_STATUS.INVALID) return CACHE_STATUS.INVALID;
+  if (read.status === CACHE_STATUS.ABSENT) return CACHE_STATUS.ABSENT;
+  return read.status;
+}
+
+function safeId(record, message, keys) {
+  for (const holder of [message, record]) {
+    for (const key of keys) {
+      const value = holder?.[key];
+      if (typeof value !== 'string') continue;
+      return SAFE_ID.test(value) && !SECRET_LIKE.test(value) ? value : null;
+    }
+  }
+  return null;
+}
+
+const count = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : null);
+const hash = (s) => crypto.createHash('sha1').update(s).digest('hex').slice(0, 16);
+
+export function buildUsageRow(record, { harness = 'claude-code', now = Date.now(), line = null } = {}) {
+  if (!record || (record.type !== 'assistant' && record.role !== 'assistant')) return null;
+  const message = record.message && typeof record.message === 'object' ? record.message : record;
+  const usage = message.usage && typeof message.usage === 'object' && !Array.isArray(message.usage) ? message.usage : null;
+  if (!usage) return null;
+  const read = classifyCache(usage, READ_KEYS);
+  const write = classifyCache(usage, WRITE_KEYS);
+  const id = typeof message.id === 'string' && SAFE_ID.test(message.id) ? message.id : null;
+  return {
+    v: USAGE_ROW_VERSION,
+    kind: 'usage',
+    ts: new Date(now).toISOString(),
+    harness,
+    provenance: 'HOST_TRANSCRIPT',
+    dedupeKey: id ? `id:${id}` : `h:${hash(line ?? JSON.stringify(usage))}`,
+    messageId: id,
+    model: typeof message.model === 'string' && SAFE_ID.test(message.model) ? message.model : null,
+    providerId: safeId(record, message, PROVIDER_KEYS),
+    gatewayId: safeId(record, message, GATEWAY_KEYS),
+    inputTokens: count(usage.input_tokens ?? usage.input),
+    outputTokens: count(usage.output_tokens ?? usage.output),
+    cacheReadTokens: read.value,
+    cacheWriteTokens: write.value,
+    cacheReadStatus: read.status,
+    cacheWriteStatus: write.status,
+    cacheMetadataStatus: cacheMetadataStatus(read, write),
+  };
+}
+
+/**
+ * Consumer helper: hit-rate over rows with KNOWN cache metadata only. A session
+ * with any partial coverage record reports coverage:'partial' and withholds the
+ * headline hitRate (partialHitRate is explicitly labelled).
+ */
+export function summarizeUsageRows(rows) {
+  let partial = false;
+  let known = 0; let unknown = 0; let cacheRead = 0; let inputSide = 0;
+  for (const row of rows || []) {
+    if (row?.kind === 'coverage') { if (row.status === 'partial') partial = true; continue; }
+    if (row?.kind !== 'usage') continue;
+    if (row.cacheMetadataStatus === 'absent' || row.cacheMetadataStatus === 'invalid') { unknown += 1; continue; }
+    known += 1;
+    cacheRead += row.cacheReadTokens ?? 0;
+    inputSide += (row.inputTokens ?? 0) + (row.cacheReadTokens ?? 0) + (row.cacheWriteTokens ?? 0);
+  }
+  const rate = inputSide > 0 ? cacheRead / inputSide : null;
+  return {
+    coverage: partial ? 'partial' : 'complete',
+    knownCalls: known,
+    unknownCalls: unknown,
+    hitRate: partial ? null : rate,
+    partialHitRate: partial ? rate : null,
+  };
+}
+
+async function readConfig(projectRoot) {
+  try {
+    return JSON.parse(await fs.readFile(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+const sessionFile = (value) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+
+async function readLogTailKeys(file) {
+  const keys = new Set();
+  let handle;
+  try {
+    handle = await fs.open(file, 'r');
+    const { size } = await handle.stat();
+    const start = Math.max(0, size - DEDUPE_TAIL_BYTES);
+    const buf = Buffer.alloc(size - start);
+    await handle.read(buf, 0, buf.length, start);
+    let text = buf.toString('utf8');
+    if (start > 0) text = text.slice(text.indexOf('\n') + 1);
+    for (const line of text.split('\n')) {
+      if (!line.includes('"dedupeKey"')) continue;
+      try { const k = JSON.parse(line)?.dedupeKey; if (typeof k === 'string') keys.add(k); } catch { /* torn line */ }
+    }
+  } catch { /* no log yet */ } finally {
+    await handle?.close().catch(() => {});
+  }
+  return keys;
+}
+
+async function rotateIfNeeded(file, incoming) {
+  try {
+    const { size } = await fs.stat(file);
+    if (size + incoming > MAX_LOG_BYTES) { await fs.rename(file, `${file}.1`); return true; }
+  } catch { /* ENOENT or race: append recreates */ }
+  return false;
+}
+
+async function readCursor(file) {
+  try {
+    const c = JSON.parse(await fs.readFile(file, 'utf8'));
+    if (Number.isInteger(c?.offset) && c.offset >= 0) return c;
+  } catch { /* none/corrupt */ }
+  return null;
+}
+
+async function startsAtLineBoundary(handle, offset) {
+  if (offset === 0) return true;
+  const b = Buffer.alloc(1);
+  const { bytesRead } = await handle.read(b, 0, 1, offset - 1);
+  return bytesRead === 1 && b[0] === 0x0a;
+}
+
+async function captureInner({ projectRoot, payload = {}, harness, now = Date.now() }) {
+  const result = { stage: 'off', rows: 0, bytesRead: 0 };
+  const config = await readConfig(projectRoot);
+  result.stage = resolveUsageCaptureStage(config);
+  if (result.stage !== 'shadow') return result;
+  const engine = harness || process.env.UKIT_HARNESS || 'claude-code';
+  if (engine === 'codex') return { ...result, skipped: 'unsupported-engine' };
+  const transcript = payload?.transcript_path;
+  if (typeof transcript !== 'string' || !transcript) return { ...result, skipped: 'no-transcript-path' };
+
+  const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'usage-capture');
+  const key = sessionFile(payload.session_id || transcript);
+  const cursorFile = path.join(dir, `${key}.cursor.json`);
+  const logFile = path.join(dir, `${key}.jsonl`);
+  await fs.mkdir(dir, { recursive: true });
+
+  // The cursor is read, advanced and written under ONE lock: two concurrent
+  // Stops cannot both consume the same window. A lock timeout leaves the cursor
+  // untouched, so the bytes are picked up by the next Stop (delayed, not lost).
+  const lock = await withAsyncLock(logFile, { deadlineMs: LOCK_DEADLINE_MS }, async () => {
+    const handle = await fs.open(transcript, 'r');
+    try {
+      const st = await handle.stat();
+      const size = st.size;
+      const cursor = await readCursor(cursorFile);
+      const reasons = [];
+      let skippedBytes = 0;
+      let offset = 0;
+      if (cursor) {
+        if ((cursor.ino != null && cursor.ino !== st.ino) || cursor.offset > size) {
+          reasons.push('transcript-rotated-or-truncated');
+        } else {
+          offset = cursor.offset;
+        }
+      } else {
+        reasons.push('initial-window');
+      }
+      if (size - offset > MAX_READ_BYTES && (!cursor || reasons.length)) {
+        // No trustworthy cursor: only the newest window is read; older bytes are a declared gap.
+        skippedBytes = size - MAX_READ_BYTES - offset;
+        offset = size - MAX_READ_BYTES;
+        if (!reasons.length) reasons.push('initial-window');
+      } else if (!cursor && size === 0) {
+        reasons.length = 0;
+      } else if (!reasons.includes('transcript-rotated-or-truncated') && reasons[0] === 'initial-window' && skippedBytes === 0) {
+        reasons.length = 0; // whole small transcript read from byte 0: nothing was skipped
+      }
+      const length = Math.min(size - offset, MAX_READ_BYTES);
+      let pendingBytes = size - offset - length;
+      const next = { v: 1, offset, ino: st.ino, partial: Boolean(cursor?.partial) };
+      let lines = [];
+      let consumed = 0;
+      if (length > 0) {
+        const buf = Buffer.alloc(length);
+        const { bytesRead } = await handle.read(buf, 0, length, offset);
+        result.bytesRead = bytesRead;
+        const text = buf.subarray(0, bytesRead).toString('utf8');
+        const lastNl = text.lastIndexOf('\n');
+        if (lastNl >= 0) {
+          consumed = Buffer.byteLength(text.slice(0, lastNl + 1), 'utf8');
+          lines = text.slice(0, lastNl + 1).split('\n');
+          if (!(await startsAtLineBoundary(handle, offset))) lines = lines.slice(1); // window began mid-line
+        }
+      }
+      if (pendingBytes > 0) reasons.push('backlog');
+      next.offset = offset + consumed;
+
+      let unparsedUsageLines = 0;
+      const rows = [];
+      const seen = new Set();
+      for (const line of lines) {
+        if (!line.includes('"usage"')) continue;
+        let record;
+        try { record = JSON.parse(line); } catch { unparsedUsageLines += 1; continue; }
+        const row = buildUsageRow(record, { harness: engine, now, line });
+        if (!row) continue;
+        if (seen.has(row.dedupeKey)) { // streaming chunks of one message: last chunk wins
+          rows[rows.findIndex((r) => r.dedupeKey === row.dedupeKey)] = row;
+          continue;
+        }
+        seen.add(row.dedupeKey);
+        rows.push(row);
+      }
+      let droppedRows = 0;
+      if (rows.length > MAX_ROWS_PER_STOP) { droppedRows = rows.length - MAX_ROWS_PER_STOP; rows.splice(0, droppedRows); reasons.push('row-cap'); }
+      if (unparsedUsageLines > 0) reasons.push('unparsed-usage-lines');
+
+      const known = rows.length ? await readLogTailKeys(logFile) : new Set();
+      const fresh = rows.filter((r) => !known.has(r.dedupeKey));
+      const records = [...fresh];
+      let rotated = false;
+      const partialNow = reasons.length > 0;
+      if (partialNow) {
+        records.push({
+          v: USAGE_ROW_VERSION, kind: 'coverage', ts: new Date(now).toISOString(), harness: engine,
+          status: 'partial', reasons: [...new Set(reasons)], skippedBytes, pendingBytes, droppedRows, unparsedUsageLines,
+        });
+        next.partial = true;
+      }
+      if (records.length) {
+        const body = records.map((r) => JSON.stringify(r)).join('\n') + '\n';
+        rotated = await rotateIfNeeded(logFile, Buffer.byteLength(body));
+        if (rotated) {
+          // Older rows beyond the retention window are gone: say so, and let consumers know.
+          records.unshift({ v: USAGE_ROW_VERSION, kind: 'coverage', ts: new Date(now).toISOString(), harness: engine, status: 'partial', reasons: ['log-rotated'], skippedBytes: 0, pendingBytes: 0, droppedRows: 0, unparsedUsageLines: 0 });
+          next.partial = true;
+        }
+        await fs.appendFile(logFile, records.map((r) => JSON.stringify(r)).join('\n') + '\n', 'utf8');
+      }
+      const tmp = `${cursorFile}.${process.pid}.tmp`;
+      await fs.writeFile(tmp, JSON.stringify(next));
+      await fs.rename(tmp, cursorFile);
+      result.rows = fresh.length;
+      result.coverage = next.partial ? 'partial' : 'complete';
+      if (pendingBytes > 0) result.pendingBytes = pendingBytes;
+    } finally {
+      await handle.close().catch(() => {});
+    }
+  });
+  if (lock?.ok === false) return { ...result, skipped: 'lock-timeout' };
+  return result;
+}
+
+/**
+ * Capture usage rows appended to the transcript since the last Stop.
+ * Never throws and never takes longer than CAPTURE_DEADLINE_MS to return; a
+ * deadline hit returns skipped:'deadline' (the next Stop resumes from the cursor).
+ */
+export async function captureUsageShadow(opts = {}) {
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve({ stage: 'shadow', rows: 0, bytesRead: 0, skipped: 'deadline' }), opts.deadlineMs ?? CAPTURE_DEADLINE_MS);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([captureInner(opts).catch(() => ({ stage: 'off', rows: 0, bytesRead: 0, skipped: 'error' })), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}