@ngockhoale/ukit 2.7.7 → 2.7.8

package/templates/.claude/ukit/runtime/token-utils.mjs

@@ -3,6 +3,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { journalDroppedLockMutation, withAsyncLock } from './async-lock.mjs';
+
 export const DEFAULT_PROMPT_CACHE_MAX_ENTRIES = 20;
 export const DEFAULT_COMPACT_HISTORY_MAX_ENTRIES = 50;
 const DEFAULT_MAX_COMPACT_ANCHORS = 3;
@@ -60,7 +62,17 @@ export async function writeJson(filePath, value) {
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
   try {
     await fs.writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-    await fs.rename(tempPath, filePath);
+    try {
+      await fs.rename(tempPath, filePath);
+    } catch (renameError) {
+      // EXDEV: the tmp file and the destination sit on different mounts (union
+      // mounts, per-dir bind mounts, tmpfs overlays), so rename cannot link them.
+      // The payload is already fully written — copy it over and unlink the tmp.
+      // Less atomic than rename, but the update must not be silently lost.
+      if (renameError?.code !== 'EXDEV') throw renameError;
+      await fs.copyFile(tempPath, filePath);
+      await fs.rm(tempPath, { force: true });
+    }
   } catch (error) {
     try {
       await fs.rm(tempPath, { force: true });
@@ -74,140 +86,39 @@ export async function writeJson(filePath, value) {
 const LOCK_STALE_MS = 10_000;
 const LOCK_MAX_WAIT_MS = 5_000;
 
-function lockBackoffDelayMs() {
-  return 3 + Math.floor(Math.random() * 9);
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    // EPERM: the process exists but belongs to another user — still alive.
-    return error?.code === 'EPERM';
-  }
-}
-
-async function readLockOwner(lockPath) {
-  try {
-    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
-    const pid = Number(raw?.pid);
-    return Number.isInteger(pid) && pid > 0
-      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-// In-process holder registry: same-pid holders are parallel async flows whose liveness a
-// pid probe cannot prove, so the module tracks them itself.
-const inProcessLockHolders = new Map();
-
 /**
  * Serialize read-modify-write mutations of a shared state file — across processes
  * (hook invocations run as separate node processes) and across concurrent async
  * flows in one process (parallel subagents). The lock is a directory created next
  * to the target file: `mkdir` is atomic, so exactly one caller can create it.
- * Ownership is recorded in an `owner` file inside the lock dir: stale reclaim first
- * proves the recorded holder is gone (dead pid, or no in-process holder for our own
- * pid — no owner file means a pre-token holder and keeps the legacy mtime-only
- * reclaim), so a slow-but-alive holder on a crawling disk is waited out, not stolen.
- * Release only removes a dir this acquisition still owns, so a reclaimed-then-
- * re-acquired lock is never deleted out from under its successor.
- * Liveness wins over strictness: if the lock cannot be acquired within maxWaitMs
- * the callback runs anyway (the pre-lock behaviour) — these state files are
- * advisory caches, and losing an update beats freezing a hook mid-flight.
- * Protocol-compatible with src/core/fileOps.js withFileLock (same `<file>.lock`
- * path and owner-file format), so CLI processes and hook processes serialize
- * against each other.
+ *
+ * The entire lock protocol lives in async-lock.mjs (TASK-004 fix round 1): owner
+ * stamping (pid + token + pstart), recycled-pid detection via recordedProcessGone,
+ * claim+quarantine stale reclaim, and verified release exist exactly once there —
+ * this function and the src/core/fileOps.js twin both delegate to it so the two
+ * protocol copies can never drift apart again.
+ *
+ * FAIL-CLOSED (TASK-004, unified with async-lock/ledger policy): if the lock cannot
+ * be acquired within maxWaitMs the callback is SKIPPED — never run unlocked — and
+ * the drop is journaled to `<file>.lock-drops.jsonl`. These state files are
+ * advisory caches: losing an update was already the accepted outcome of the old
+ * fail-open race; now it is explicit and journaled instead of a silent torn write.
  * @param {string} filePath - state file the mutation targets (lock lives beside it)
  * @param {() => Promise<*>} fn - critical section; its result is returned
- * @returns {Promise<*>} whatever fn resolves with
+ * @returns {Promise<*|undefined>} whatever fn resolves with, or undefined when the
+ *   lock wait expired and the mutation was skipped (journaled)
  */
 export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxWaitMs = LOCK_MAX_WAIT_MS } = {}) {
-  const lockPath = `${filePath}.lock`;
-  const startedAt = Date.now();
-  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
-  let locked = false;
-  let ownerStamped = false;
-
-  while (!locked) {
-    try {
-      await fs.mkdir(path.dirname(lockPath), { recursive: true });
-      await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
-      locked = true;
-      inProcessLockHolders.set(lockPath, ownerToken);
-      try {
-        await fs.writeFile(
-          path.join(lockPath, 'owner'),
-          `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
-          'utf8',
-        );
-        ownerStamped = true;
-      } catch {
-        ownerStamped = false; // unverifiable release skips removal; stale reclaim cleans up
-      }
-      break;
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-    }
-
-    // Someone holds the lock. Reclaim it only when the holder is provably gone.
-    try {
-      const stat = await fs.stat(lockPath);
-      if (Date.now() - stat.mtimeMs > staleMs) {
-        const owner = await readLockOwner(lockPath);
-        const liveInProcess = inProcessLockHolders.has(lockPath);
-        // Stealing a live holder reintroduces the exact interleaved-write race this
-        // lock exists to prevent, and the stolen holder's release then deleted the
-        // successor's lock. Only a dead pid (or a leaked same-pid dir with no live
-        // registered flow) may be reclaimed.
-        const reclaimable = !owner || owner.pid === process.pid
-          ? !liveInProcess
-          : !isPidAlive(owner.pid);
-        if (reclaimable) {
-          await fs.rm(lockPath, { recursive: true, force: true });
-          continue; // the slot is free now — retry immediately
-        }
-      }
-    } catch (statError) {
-      // BUG-C22-16: a persistent stat error (EPERM/ENOTDIR/EIO on a failing
-      // mount, or ELOOP/ENOENT on a dangling symlink where mkdir still reports
-      // EEXIST) must not busy-spin — a bare `continue` skipped both the
-      // maxWait break and the backoff sleep, looping mkdir→stat→throw forever.
-      if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
-      if (statError?.code === 'ENOENT') continue; // lock vanished — retry immediately
-      await sleep(lockBackoffDelayMs());
-      continue;
-    }
-
-    if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
-    await sleep(lockBackoffDelayMs());
-  }
-
-  try {
-    return await fn();
-  } finally {
-    if (locked) {
-      try {
-        // Remove the lock only if THIS acquisition still owns it: after a stale reclaim
-        // another holder may already own the dir, and deleting it would unlock their
-        // critical section for a third waiter.
-        const current = ownerStamped ? await readLockOwner(lockPath) : null;
-        if (current && current.token === ownerToken) {
-          await fs.rm(lockPath, { recursive: true, force: true });
-        }
-        if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
-      } catch {
-        // best-effort release; a stale lock is reclaimed by the next waiter
-      }
-    }
-  }
+  const outcome = await withAsyncLock(filePath, { deadlineMs: maxWaitMs, staleMs }, fn);
+  if (outcome?.ok === true) return outcome.value;
+  // Fail closed: the mutation is dropped, never run unlocked. The drop is
+  // journaled so the lost update is auditable; callers treat undefined as
+  // "update skipped" (they already tolerated losing it silently).
+  await journalDroppedLockMutation(filePath, {
+    reason: 'lock-wait-expired',
+    waitedMs: outcome?.waitedMs ?? maxWaitMs,
+  });
+  return undefined;
 }
 
 export function buildCompactMachineKey(prefix, payload = {}) {

package/templates/.codex/settings.json

@@ -358,10 +358,6 @@
     "non-trivial": "full test + lint + typecheck"
   },
   "verification": {
-    "requiredBeforeCompletion": [
-      "{{runtime.packageManager}} test",
-      "{{runtime.packageManager}} lint",
-      "{{runtime.packageManager}} typecheck"
-    ]
+    "requiredBeforeCompletion": {{verification.requiredBeforeCompletion}}
   }
 }

package/templates/.omp/agents/bug-debugger.md

@@ -49,7 +49,7 @@ Systematic debugging — understand before fixing.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as. "unknown" if you cannot tell.]
 EXECUTOR_SUBAGENT: [subagent name within your host, if any, else "-"]
 SUMMARY: [1-2 sentences — root cause and fix]

package/templates/.omp/agents/feature-implementer.md

@@ -71,9 +71,9 @@ and even then, report it, don't ask about it.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as — e.g. unic-code, claude-sonnet-4-5, gpt-5-mini. If you truly cannot tell, write "unknown" — reviewer treats unknown as suspicious and asks the human to confirm.]
-EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Kilo:code", "Claude:feature-implementer". Otherwise "-".]
+EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Claude:feature-implementer", "omp:task". Otherwise "-".]
 SUMMARY: [1-2 sentences of what was implemented]
 TEST_PLAN_FOLLOWED: [task §4 / inline / N/A — reason]
 FILES_CHANGED:

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

@@ -16,11 +16,10 @@ import {
   markNotified,
   readExecutionLedger,
   readRouteState,
-  recordExecutionReceipt,
 } from '../../../.claude/ukit/runtime/execution-ledger.mjs';
 import {
   PAYLOAD_INLINE_MAX_BYTES,
-  createPayloadReference,
+  createPayloadReferenceAsync,
   maybeSweepStalePayloads,
   probePayloadIntegrity,
 } from '../../../.claude/ukit/runtime/hook-payload-store.mjs';
@@ -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'],
@@ -184,10 +190,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,
   };
 }
 
@@ -530,7 +544,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),
   });
@@ -767,17 +781,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 +859,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 +906,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 +946,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 +1017,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 +1034,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 +1058,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.",