@ngockhoale/ukit 2.7.6 → 2.7.8

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.",