@ngockhoale/ukit 2.7.7 → 2.7.9

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -16,13 +16,12 @@ import {
   markNotified,
   readExecutionLedger,
   readRouteState,
-  recordExecutionReceipt,
 } from '../../../.claude/ukit/runtime/execution-ledger.mjs';
 import {
   PAYLOAD_INLINE_MAX_BYTES,
-  createPayloadReference,
-  maybeSweepStalePayloads,
-  probePayloadIntegrity,
+  createPayloadReferenceAsync,
+  maybeSweepStalePayloadsAsync,
+  probePayloadIntegrityAsync,
 } from '../../../.claude/ukit/runtime/hook-payload-store.mjs';
 // TASK-018 review fix round 1: the chain budget is resolved by ONE shared module,
 // so the runner's inner deadline and this bridge's outer pi.exec timeout can never
@@ -30,6 +29,13 @@ import {
 // for Edit|Write is a fail-closed transport failure = every edit blocked).
 import { resolveChainExecTimeoutMs } from '../../../.claude/ukit/runtime/hook-chain-budget.mjs';
 
+// OMP-3 (TASK-002): pi.exec forwards only {cwd, signal, timeout} to its spawn —
+// an `env` option is dropped (verified against the bundled omp exec). The only
+// channel that reaches the chain runner AND its in-proc .mjs steps is the host
+// environment, so the bridge stamps the harness here: record-execution.mjs
+// reads env.UKIT_HARNESS (default 'claude-code') when journaling receipts.
+process.env.UKIT_HARNESS = 'omp';
+
 export const HOOK_EVENT_MAP = {
   tool_call: {
     'Read|Grep|Glob': ['sensitive-data-guard.mjs'],
@@ -140,6 +146,17 @@ function classifyFailure(scriptName) {
 // closed (the .sh thin wrapper is still invocable as a fallback path).
 const TIMEOUT_STAYS_CLOSED = new Set(['block-dangerous.sh', 'block-dangerous.mjs']);
 
+// TASK-002 (OMP-4): a hook crash or transport failure whose stderr is a
+// transient filesystem error (EAGAIN/EBUSY/EMFILE/ENFILE/ESTALE — the
+// stalled-external-mount class) produced NO verdict, so it must degrade to a
+// loud "could not verify" warning instead of a block showing raw errno text.
+// The match is deliberately conservative: the errno code must appear in an
+// fs-syscall context (open/read/write/mkdir/stat/rename/unlink/rm), in either
+// order, or the Node "resource temporarily unavailable" phrasing — a genuine
+// block reason containing e.g. "again" in prose never downgrades. ONE pattern
+// shared by translateExecResult and runScriptChain.
+const TRANSIENT_INFRA_STDERR_RE = /\bresource temporarily unavailable\b|\b(?:EAGAIN|EBUSY|EMFILE|ENFILE|ESTALE)\b[\s\S]*?\b(?:open|read|write|mkdir|stat|rename|unlink|rm)\b|\b(?:open|read|write|mkdir|stat|rename|unlink|rm)\b[\s\S]*?\b(?:EAGAIN|EBUSY|EMFILE|ENFILE|ESTALE)\b/i;
+
 // TASK-018: the hook-chain-runner's failure taxonomy. Infrastructure outcomes
 // (overflow / timeout / signal / budget-exhausted) produced NO verdict, so their
 // captured output is untrustworthy and never reaches the model context, a block
@@ -184,10 +201,18 @@ function redactDiagnosticText(text, maxChars = 500) {
 
 function runtimeMetadata(event = {}, context = {}) {
   const sessionManager = context?.sessionManager;
+  const transcriptPath = event.transcriptPath ?? event.transcript_path ?? sessionManager?.getSessionFile?.();
   return {
-    sessionId: event.sessionId ?? event.session_id ?? sessionManager?.getSessionId?.(),
+    // F-8: one session key for EVERY event. omp session_start events carry no
+    // session id and the context may lack sessionManager — without one,
+    // reset-compact-pressure.sh takes the unknown-caller branch and wipes EVERY
+    // session's pressure records. Falling back to the transcript path here (not
+    // per-caller) keeps the reset key identical to the key the pressure writer
+    // used on prompt/tool events that also lack an id; a per-caller fallback
+    // let the two diverge and the targeted delete silently missed.
+    sessionId: event.sessionId ?? event.session_id ?? sessionManager?.getSessionId?.() ?? transcriptPath,
     cwd: context?.cwd ?? event.cwd,
-    transcriptPath: event.transcriptPath ?? event.transcript_path ?? sessionManager?.getSessionFile?.(),
+    transcriptPath,
   };
 }
 
@@ -323,6 +348,18 @@ function translateExecResult(scriptName, execResult) {
     }
     return { block: true, reason: stderr || `${scriptName} exited 2 (blocked)`, stdout, stderr };
   }
+  // TASK-002 (OMP-4): a crash whose stderr is a transient fs error produced no
+  // verdict — it is an infrastructure event, not a safety decision. Fail open
+  // loudly instead of blocking on raw errno text. TIMEOUT_STAYS_CLOSED scripts
+  // (block-dangerous .sh/.mjs) keep their never-fail-open contract.
+  if (TRANSIENT_INFRA_STDERR_RE.test(stderr) && !TIMEOUT_STAYS_CLOSED.has(scriptName)) {
+    return {
+      block: false,
+      warning: `${scriptName} exited ${code} with a transient filesystem error — treated as "could not verify", not as a block (an infrastructure event, not a verdict): ${redactDiagnosticText(stderr) || 'no stderr'}`,
+      stdout,
+      stderr,
+    };
+  }
   if (classifyFailure(scriptName) === 'closed') {
     return {
       block: true,
@@ -366,17 +403,18 @@ function hookErrorsDirFor(projectRoot) {
 }
 
 // Bounded work on THIS session's file only — identical keep-newest-half shape
-// as hook-telemetry's rotateIfNeeded.
-function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
+// as hook-telemetry's rotateIfNeeded. TASK-002 (OMP-4): async fs only — a
+// stalled mount must never freeze the omp host loop.
+async function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
   let size = 0;
   try {
-    size = fs.statSync(filePath).size;
+    size = (await fs.promises.stat(filePath)).size;
   } catch {
     return; // first row for this session
   }
   if (size + incomingBytes <= maxBytes) return;
   try {
-    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    const lines = (await fs.promises.readFile(filePath, 'utf8')).split('\n');
     if (lines.length && lines[lines.length - 1] === '') lines.pop();
     const keepBudget = Math.floor(maxBytes / 2);
     const keep = [];
@@ -387,16 +425,17 @@ function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
       keep.unshift(lines[i]);
       kept += lineBytes;
     }
-    fs.writeFileSync(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
+    await fs.promises.writeFile(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
   } catch {
     // Rotation failed; drop this row rather than grow past the cap.
   }
 }
 
 // sweepHookErrorsDir(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
-//   { scanned, removed } — bounded: never scans or removes more than the caps,
-// so a pre-existing oversized dir is amortized down across sampled sweeps.
-function sweepHookErrorsDir(dir, {
+//   Promise<{ scanned, removed }> — bounded: never scans or removes more than
+// the caps, so a pre-existing oversized dir is amortized down across sampled
+// sweeps. TASK-002 (OMP-4): async fs only — host loop must never block.
+async function sweepHookErrorsDir(dir, {
   now = Date.now,
   maxAgeMs = HOOK_ERROR_MAX_AGE_MS,
   maxFiles = HOOK_ERROR_MAX_FILES,
@@ -405,7 +444,7 @@ function sweepHookErrorsDir(dir, {
 } = {}) {
   let names;
   try {
-    names = fs.readdirSync(dir);
+    names = await fs.promises.readdir(dir);
   } catch {
     return { scanned: 0, removed: 0 };
   }
@@ -421,7 +460,7 @@ function sweepHookErrorsDir(dir, {
     if (scanned >= maxEntries) break;
     scanned += 1;
     try {
-      const stats = fs.statSync(path.join(dir, name));
+      const stats = await fs.promises.stat(path.join(dir, name));
       if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
     } catch { /* raced away — fine */ }
   }
@@ -435,7 +474,7 @@ function sweepHookErrorsDir(dir, {
     if (removed >= maxRemovals) break;
     if (removed < overflow || entry.mtimeMs < cutoff) {
       try {
-        fs.rmSync(path.join(dir, entry.name), { force: true });
+        await fs.promises.rm(path.join(dir, entry.name), { force: true });
         removed += 1;
       } catch { /* raced away — fine */ }
     }
@@ -449,18 +488,18 @@ function hookErrorsSweepProbabilityFromEnv() {
   return Math.min(1, Math.max(0, raw));
 }
 
-function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic, { maxBytes = HOOK_ERROR_MAX_BYTES } = {}) {
+async function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic, { maxBytes = HOOK_ERROR_MAX_BYTES } = {}) {
   try {
     const dir = hookErrorsDirFor(projectRoot);
-    fs.mkdirSync(dir, { recursive: true });
+    await fs.promises.mkdir(dir, { recursive: true });
     const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
     const filePath = path.join(dir, `${safeSession}.jsonl`);
     const line = `${JSON.stringify(diagnostic)}\n`;
-    rotateHookErrorFileIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), maxBytes);
-    fs.appendFileSync(filePath, line, 'utf8');
+    await rotateHookErrorFileIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), maxBytes);
+    await fs.promises.appendFile(filePath, line, 'utf8');
     // Sampled bounded dir sweep — amortizes down any pre-existing oversized dir.
     if (Math.random() < hookErrorsSweepProbabilityFromEnv()) {
-      sweepHookErrorsDir(dir);
+      await sweepHookErrorsDir(dir);
     }
   } catch {
     // Diagnostics are advisory and must never block or throw.
@@ -505,11 +544,11 @@ function payloadsDirFor(projectRoot) {
 }
 
 function schedulePayloadSweep(projectRoot) {
-  // Deferred: runs after the current turn settles, never inside the chain request.
+  // Deferred: runs after the current turn settles, never inside the chain
+  // request. Async fs only — a stalled mount must not freeze the host loop.
   const timer = setTimeout(() => {
-    try {
-      maybeSweepStalePayloads(payloadsDirFor(projectRoot));
-    } catch { /* deferred sweeping is best effort */ }
+    maybeSweepStalePayloadsAsync(payloadsDirFor(projectRoot))
+      .catch(() => { /* deferred sweeping is best effort */ });
   }, 0);
   timer.unref?.();
 }
@@ -530,7 +569,7 @@ export async function runScriptChain(
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
   const nodeExecutable = resolveNodeExecutable();
   const startedAt = Date.now();
-  const payloadReference = createPayloadReference(JSON.stringify(payload), {
+  const payloadReference = await createPayloadReferenceAsync(JSON.stringify(payload), {
     maxBytes: PAYLOAD_INLINE_MAX_BYTES,
     dir: payloadsDirFor(projectRoot),
   });
@@ -549,8 +588,8 @@ export async function runScriptChain(
     // TASK-031: verify the staged payload survived the chain intact BEFORE removing it —
     // a file that vanished or was truncated mid-flight means the scripts ran against a
     // different payload than the host captured, so their verdicts are void.
-    payloadProbe = probePayloadIntegrity(payloadReference);
-    payloadReference.cleanup();
+    payloadProbe = await probePayloadIntegrityAsync(payloadReference);
+    await payloadReference.cleanupAsync();
     if (payloadReference.mode === 'file') schedulePayloadSweep(projectRoot);
   }
   const elapsedMs = Date.now() - startedAt;
@@ -595,7 +634,7 @@ export async function runScriptChain(
       parseError: parseError?.message || null,
       wrapperError: chainResult?.wrapperError || null,
     };
-    recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    await recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
     // TASK-031: a staged payload that was lost or corrupted mid-chain voids every
     // verdict below it. Chains that must not fail open on an unverifiable verdict
     // (Edit|Write transport policy, and block-dangerous's never-fail-open rule)
@@ -626,6 +665,15 @@ export async function runScriptChain(
         + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
         + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
         + `See .ukit/storage/cache/hook-errors/.${nodePathHint}`;
+    // TASK-002 (OMP-4): a transport failure whose stderr is a transient fs
+    // error produced no verdict — an infrastructure event, not a safety
+    // decision. Even on a fail-closed chain it degrades to a loud warning
+    // instead of a block showing raw errno text. A staged-payload integrity
+    // failure (payloadProbe !== null) already returned above and stays closed.
+    if (failClosedOnTransportError && TRANSIENT_INFRA_STDERR_RE.test(diagnostic.stderrExcerpt)) {
+      pi.logger?.warn?.(`[UKit] ${reason} Transient filesystem error — treated as "could not verify", not as a block.`);
+      return { block: false, context, invoked };
+    }
     if (failClosedOnTransportError) {
       return { block: true, reason, context, invoked };
     }
@@ -767,17 +815,13 @@ export async function runToolResult(pi, event, { projectRoot, context: extension
     toolUseId: event.toolCallId,
     ...metadata,
   });
+  // OMP-3 (TASK-002): the receipt is journaled by exactly ONE path — the
+  // record-execution.mjs chain step inside runScriptChain (the same step Claude
+  // Code runs, carrying the runner's deadline/signal into the ledger lock). The
+  // former direct recordExecutionReceipt({harness:'omp'}) call here minted a
+  // second receipt per tool result, so one failed test counted as streak 2 and
+  // tripped the verification-loop blocker after a single failure.
   const result = await runScriptChain(pi, scriptsForToolResult(toolName), payload, { projectRoot });
-  try {
-    await recordExecutionReceipt({
-      projectRoot,
-      payload,
-      toolName,
-      harness: 'omp',
-    });
-  } catch (error) {
-    pi.logger?.warn?.(`[UKit] execution receipt failed open: ${error?.message || error}`);
-  }
 
   const hookOutput = result.context.join('\n').trim();
   if (!hookOutput) return undefined;
@@ -849,19 +893,36 @@ export async function runSessionCompact(pi, event, { projectRoot, context: exten
 // harnesses; a clean evaluation deletes it, so the count is consecutive crashes.
 const COMPLETION_CRASH_STREAK_FILE = path.join('.ukit', 'storage', 'cache', 'completion-gate-crash.streak');
 
-async function bumpCompletionCrashStreak(projectRoot) {
+// OMP-1: the bridge is a long-lived in-proc module, so a streak that cannot persist
+// (unwritable cache dir, stalled volume, lock-busy sibling writers) still advances
+// in memory per project root. Pre-fix the catch path returned a constant 1 — the
+// 3-crash loud release was unreachable and every omp Stop blocked forever. The
+// in-memory count is the floor; a persisted count higher than it wins on the next
+// successful read so cross-harness streaks still converge.
+const crashStreakFallback = new Map();
+
+async function bumpCompletionCrashStreak(projectRoot, pi = null) {
   const file = path.join(projectRoot, COMPLETION_CRASH_STREAK_FILE);
   try {
     await fs.promises.mkdir(path.dirname(file), { recursive: true });
     await fs.promises.appendFile(file, '.');
     const buf = await fs.promises.readFile(file);
-    return buf.length || 1;
-  } catch {
-    return 1;
+    const count = Math.max(buf.length || 1, (crashStreakFallback.get(projectRoot) || 0) + 1);
+    crashStreakFallback.set(projectRoot, count);
+    return count;
+  } catch (error) {
+    const count = (crashStreakFallback.get(projectRoot) || 0) + 1;
+    crashStreakFallback.set(projectRoot, count);
+    pi?.logger?.warn?.(
+      `[UKit] completion crash streak could not persist (${error?.message || error}); `
+      + `counting in memory (streak ${count}) so the breaker still advances.`,
+    );
+    return count;
   }
 }
 
 async function resetCompletionCrashStreak(projectRoot) {
+  crashStreakFallback.delete(projectRoot);
   try {
     await fs.promises.rm(path.join(projectRoot, COMPLETION_CRASH_STREAK_FILE), { force: true });
   } catch { /* best effort */ }
@@ -879,6 +940,38 @@ async function readStopGateMaxCrashStreaks(projectRoot) {
   }
 }
 
+// ── TASK-007 (F-10/OMP-2): stop-path parity with stop-coordinator.mjs ─────────
+// Claude's Stop runs one coordinator with three protections the omp bridge never
+// had: the handoff-cursor lane (a non-done docs/AI_HANDOFF/RUN.md bounces the
+// stop with the run's own Next: line, bounded by the stopGateMaxStalledBlocks
+// liveness breaker), the 2s double-Stop dedupe window (one logical stop burns
+// exactly one continuation), and a 600ms budget on every ledger/state lock.
+// The evaluators are reused from stop-coordinator.mjs itself so semantics and
+// the shared state file (.ukit/storage/cache/stop-coordinator/state.json) stay
+// byte-identical across both engines.
+const STOP_GATE_LOCK_BUDGET_MS = 600;
+const HANDOFF_PROVENANCE_PREFIX = '[ukit-stop-coordinator] handoff-cursor also requested a block: ';
+
+let stopCoordinatorModulePromise = null;
+
+// Lazy + env-scrubbed: stop-coordinator.mjs arms a process.exit self-deadline at
+// module top level whenever UKIT_HOOK_DEADLINE_MS is set. That env var is only
+// ever set for spawned hook children, but the bridge is a long-lived in-proc
+// module — a leaked value would kill the whole omp host. Same scrub the
+// chain-runner applies around in-proc .mjs steps (hook-chain-runner.mjs:180).
+function loadStopCoordinatorModule() {
+  if (!stopCoordinatorModulePromise) {
+    const scrubbed = 'UKIT_HOOK_DEADLINE_MS' in process.env
+      ? process.env.UKIT_HOOK_DEADLINE_MS : undefined;
+    delete process.env.UKIT_HOOK_DEADLINE_MS;
+    stopCoordinatorModulePromise = import('../../../.claude/ukit/runtime/stop-coordinator.mjs')
+      .finally(() => {
+        if (scrubbed !== undefined) process.env.UKIT_HOOK_DEADLINE_MS = scrubbed;
+      });
+  }
+  return stopCoordinatorModulePromise;
+}
+
 export async function runSessionStop(
   pi,
   event,
@@ -887,10 +980,69 @@ export async function runSessionStop(
     context: extensionContext = {},
     state: suppliedState,
     ledger: suppliedLedger,
+    now = Date.now(),
+    dedupeWindowMs,
+    lockBudgetMs = STOP_GATE_LOCK_BUDGET_MS,
   },
 ) {
-  const metadata = runtimeMetadata(event, extensionContext);
+  // TASK-007 (OMP-2d): the stop path keys its session identity ONLY from the
+  // event itself — never the context's sessionManager fallback. omp emits
+  // session_id on every top-level session_stop (verified against the bundled
+  // binary: emitSessionStop carries session_id/session_file/stop_hook_active),
+  // so an event without one is a nested/foreign stop; attributing it to the
+  // parent session would burn the parent's continuation budget and dedupe slot.
+  const metadata = {
+    sessionId: event?.sessionId ?? event?.session_id,
+    cwd: extensionContext?.cwd ?? event?.cwd,
+    transcriptPath: event?.transcriptPath ?? event?.transcript_path ?? event?.session_file,
+  };
   const payload = buildHookPayload('Stop', metadata);
+
+  // TASK-007 (OMP-2b): the coordinator's once-per-stop dedupe. omp can deliver
+  // two session_stop events for one logical stop; the second inside the window
+  // is skipped entirely — it must not burn a second continuation.
+  let coordinator = null;
+  try {
+    coordinator = await loadStopCoordinatorModule();
+  } catch (error) {
+    // Advisory lane: a missing/unloadable coordinator module must never wedge a
+    // session — the completion gate below still owns the stop.
+    pi.logger?.warn?.(`[UKit] stop-coordinator module unavailable (dedupe + handoff lanes skipped): ${error?.message || error}`);
+  }
+  if (coordinator) {
+    const sessionKey = typeof payload.session_id === 'string' && payload.session_id
+      ? payload.session_id
+      : (typeof payload.transcript_path === 'string' && payload.transcript_path ? payload.transcript_path : 'no-session');
+    const duplicate = await coordinator.alreadyCoordinatedThisStop({
+      projectRoot,
+      sessionKey,
+      now,
+      dedupeWindowMs: dedupeWindowMs ?? coordinator.DEDUPE_WINDOW_MS,
+      lockBudgetMs,
+    });
+    if (duplicate) return undefined;
+  }
+
+  // TASK-007 (OMP-2c): the handoff-cursor lane. While docs/AI_HANDOFF/RUN.md
+  // reports a phase outside {done, blocked} the run owns this stop — the
+  // cursor's Next: line is the continuation instruction. Advisory on failure,
+  // bounded by the stopGateMaxStalledBlocks breaker (always advances post-S3).
+  let handoff = null;
+  if (coordinator) {
+    try {
+      handoff = await coordinator.evaluateHandoffCursor({ projectRoot, now, lockBudgetMs });
+    } catch (error) {
+      pi.logger?.warn?.(`[UKit] handoff-cursor evaluator failed (advisory lane): ${error?.message || error}`);
+    }
+  }
+  const handoffBlock = handoff?.kind === 'block' ? handoff.reason : null;
+  // A breaker-release advisory (or any handoff systemMessage) is the omp
+  // equivalent of the coordinator's systemMessage channel — surface it once,
+  // visibly, whichever way the stop itself resolves.
+  if (handoff?.kind === 'advisory' && handoff.systemMessage) {
+    sendContext(pi, [handoff.systemMessage], 'nextTurn', { display: true });
+  }
+
   const state = suppliedState ?? await readRouteState(projectRoot, payload);
   const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
   let evaluation;
@@ -899,8 +1051,7 @@ export async function runSessionStop(
   } catch (error) {
     // BUG-C22-05: fail-closed like the shell gate (continue the turn), but only up
     // to the configured consecutive-crash cap — a persistently broken evaluator
-    // must release loudly instead of looping every Stop forever.
-    const streak = await bumpCompletionCrashStreak(projectRoot);
+    const streak = await bumpCompletionCrashStreak(projectRoot, pi);
     const maxStreak = await readStopGateMaxCrashStreaks(projectRoot);
     if (streak > maxStreak) {
       await resetCompletionCrashStreak(projectRoot);
@@ -917,7 +1068,8 @@ export async function runSessionStop(
       continue: true,
       additionalContext:
         `UKit stop coordinator: infrastructure failure while evaluating this stop (crash streak ${streak}/${maxStreak}) — `
-        + 'the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message.',
+        + 'the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message.'
+        + (handoffBlock ? `\n${HANDOFF_PROVENANCE_PREFIX}${handoffBlock}` : ''),
     };
   }
   // A clean evaluation resets the consecutive-crash streak (shared with the shell hook).
@@ -940,20 +1092,33 @@ export async function runSessionStop(
       // message) stays as a second guaranteed channel.
       sendContext(pi, [notice], 'nextTurn', { display: true });
     }
+    // The completion gate released, but an in-flight handoff run still owns the
+    // stop (coordinator merge order: handoff-cursor block outranks a released
+    // completion). Its own stall streak — not the ledger continuation counter —
+    // bounds this lane, so no continuation bookkeeping runs here.
+    if (handoffBlock) {
+      return { continue: true, additionalContext: handoffBlock };
+    }
     return undefined;
   }
 
   if (suppliedLedger === undefined) {
     try {
-      if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
-      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state));
+      // TASK-007 (OMP-2a): the 600ms lock budget — a contended ledger lock must
+      // never hold the omp host near its hook deadline.
+      if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger, { deadlineMs: lockBudgetMs });
+      else await incrementContinuation(projectRoot, payload, ledger, state?.requestKey || null, evidencePromptKey(state), { deadlineMs: lockBudgetMs });
     } catch (error) {
       pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
     }
   }
   return {
     continue: true,
-    additionalContext: evaluation.reason,
+    // Coordinator merge order: the completion gate owns the continuation, and a
+    // losing handoff-cursor block travels inside the winning reason.
+    additionalContext: handoffBlock
+      ? `${evaluation.reason}\n${HANDOFF_PROVENANCE_PREFIX}${handoffBlock}`
+      : evaluation.reason,
   };
 }
 

package/templates/docs/AI_HANDOFF/INDEX.md

@@ -4,7 +4,7 @@
 Status values (xem RULES.md §Status state machine):
 ready | in_progress | pending_review | changes_requested | critical_block | approved | approved_minor | blocked | done
 
-Owner = tool đang giữ task: claude-code | kilo-code | codex | -
+Owner = tool đang giữ task: claude-code | codex | omp | -
 -->
 
 | ID | Title | Priority | Size | Status | Owner | Reviewer | File |

package/templates/docs/AI_HANDOFF/RULES.md

@@ -92,21 +92,21 @@ Next: <bước kế tiếp chính xác>
 
 ## Handoff Flow (tool-agnostic, file-based state machine)
 
-UKit handoff hoạt động qua **file state**. Anh tự chọn tool nào cho từng phase — Claude Code / Kilo Code / Codex / tool mới sau này — đều được. UKit chỉ care về **role của model**, không care tool.
+UKit handoff hoạt động qua **file state**. Anh tự chọn tool nào cho từng phase — Claude Code / Codex / omp / tool mới sau này — đều được. UKit chỉ care về **role của model**, không care tool.
 
 3 phase × 3 role model:
 
 - **Plan** — model mạnh nhất anh có (reasoning model). Có thể chạy ở bất kỳ tool nào hỗ trợ planning tốt.
-- **Execute** — model rẻ-mà-vẫn-thông-minh (code model). Có thể là subagent code của Kilo, hay feature-implementer của Claude Code.
-- **Review** — **MODEL KHÁC executor** (reasoning model thường tốt hơn). Có thể là tool khác, hoặc cùng tool nhưng subagent khác model (ví dụ Kilo có subagent code và subagent review riêng).
+- **Execute** — model rẻ-mà-vẫn-thông-minh (code model). Có thể là subagent code của omp, hay feature-implementer của Claude Code.
+- **Review** — **MODEL KHÁC executor** (reasoning model thường tốt hơn). Có thể là tool khác, hoặc cùng tool nhưng subagent khác model.
 
 Hai mô hình triển khai đều hợp lệ:
-- **Cross-tool**: ví dụ Claude (plan) → Kilo (execute) → Claude (review). Bridge qua file.
-- **Same-tool different-subagent**: ví dụ Kilo:plan → Kilo:code → Kilo:review, miễn 3 subagent dùng MODEL khác nhau ở role tương ứng.
+- **Cross-tool**: ví dụ Claude (plan) → Codex (execute) → Claude (review). Bridge qua file.
+- **Same-tool different-subagent**: ví dụ omp:plan → omp:task → omp:code-reviewer, miễn 3 subagent dùng MODEL khác nhau ở role tương ứng.
 
 Mỗi tool/subagent đọc cùng `INDEX.md` + `tasks/TASK-xxx.md` → chọn task theo `status` → cập nhật status khi xong.
 
-> **Quan trọng — UKit không enforce model:** `handoff.executor.cheapSmartModelHint` và `handoff.reviewer.model` trong `.ukit/storage/config.json` chỉ là **nhãn** để anh biết MUỐN dùng gì. Tool nào dùng model nào là do anh chọn trong settings của tool đó. UKit enforce contract bằng cách bắt executor TỰ KHAI `EXECUTOR_MODEL` trong Executor Report; reviewer so với chính nó và refuse nếu trùng. Vì vậy nếu trong Kilo anh để cả code-subagent và review-subagent đều dùng cùng model → reviewer sẽ tự refuse, không silent-pass.
+> **Quan trọng — UKit không enforce model:** `handoff.executor.cheapSmartModelHint` và `handoff.reviewer.model` trong `.ukit/storage/config.json` chỉ là **nhãn** để anh biết MUỐN dùng gì. Tool nào dùng model nào là do anh chọn trong settings của tool đó. UKit enforce contract bằng cách bắt executor TỰ KHAI `EXECUTOR_MODEL` trong Executor Report; reviewer so với chính nó và refuse nếu trùng. Vì vậy nếu anh để cả executor-subagent và review-subagent đều dùng cùng model → reviewer sẽ tự refuse, không silent-pass.
 
 ### Status state machine
 

package/templates/ukit/storage/config.json

@@ -442,7 +442,7 @@
         "field": "handoff.reviewer.model",
         "mac_dinh": "unic-smart",
         "y_nghia": "Model dùng cho reviewer agent ở Phase 3. BẮT BUỘC khác model executor để bắt được lỗi mà executor miss. Có thể dùng claude-opus-5, unic-smart, hoặc bất kỳ model reasoning mạnh nào.",
-        "vi_du": "Nếu executor là unic-code (Kilo Code), set reviewer.model=unic-smart hoặc claude-opus-5. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
+        "vi_du": "Nếu executor là unic-code, set reviewer.model=unic-smart hoặc claude-opus-5. Nếu executor là claude-sonnet, set reviewer thành claude-opus."
       },
       "tat_reviewer_phase": {
         "field": "handoff.reviewer.enabled",
@@ -601,7 +601,7 @@
     },
     "handoff": {
       "enabled": "Bật Quality Gate cho handoff: plan có Test Plan, executor test-first, reviewer model khác. Tắt = quay về flow cũ (dễ lọt lỗi vặt).",
-      "crossTool": "true nghĩa là handoff truyền qua file (PLAN/INDEX/tasks) chứ không qua in-process subagent — cho phép plan ở Claude Code, execute ở Kilo Code, review ở Claude Code khác model.",
+      "crossTool": "true nghĩa là handoff truyền qua file (PLAN/INDEX/tasks) chứ không qua in-process subagent — cho phép plan ở một tool, execute ở tool khác, review ở tool thứ ba khác model.",
       "maxParallelAgents": "Số agent chạy song song TỐI ĐA trong một wave (mặc định 2 để giữ session chính nhẹ và hạn chế rủi ro compact/worktree rác; nếu máy khỏe và task độc lập nhiều thì có thể nâng dần 3-5, tối đa ~10-15). Một wave có nhiều task hơn số này sẽ được chia thành nhiều batch chạy lần lượt — áp dụng cho cả Phase 3 Implement và Phase 4 Review. Lý do giới hạn vẫn còn: mỗi agent nền có context window riêng, và report của agent khi xong sẽ được inject ngược vào session chính — chạy quá nhiều cùng lúc (vd 20+) vẫn có thể làm session chính vượt context window và bỏ lại worktree rác. Hạ xuống 1-2 nếu task nặng (verification output dài) hoặc thấy compact bị trigger liên tục.",
       "plan": {
         "requireTestPlan": "Bắt buộc PLAN.md §4 phải có Test Plan trước khi task chuyển ready.",