@ngockhoale/ukit 3.4.11 → 3.4.12

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.12 - 2026-10-02
+
+**Handoff Stop gate is session-scoped — a stale `RUN.md` no longer hijacks unrelated sessions.**
+Before, any session in a repo was bounced with "CONTINUE IMMEDIATELY" whenever
+`docs/AI_HANDOFF/RUN.md` carried a live `Phase:` (or a `done` whose ExitPredicate
+failed, e.g. `git:clean` on a dirty tree) — even a fresh session opened only to plan.
+`evaluateHandoffCursor` now takes the session `transcriptPath` and enforces the
+gate only when that session itself drives the run, proven by STRUCTURED transcript
+evidence (a real user turn with the `/ukit:handoff-fullstack` tag, a `Skill` call for
+it, or a SessionStart attachment carrying the resume banner). Marker strings in tool
+output, bash commands or source files do not count. An unreadable/oversized
+transcript keeps the legacy block (a real run is never released by a lost read).
+The omp bridge passes the transcript path too.
+
+- `handoff-resume.sh`: `startup`/`clear` sessions get an informational note (ignore
+  unless asked; `/ukit:handoff-fullstack` to continue, `/ukit:handoff-clear` to
+  discard) instead of a resume order; `compact`/`resume` still resume automatically.
+- New config `handoff.fullstack.stopGateScope`: `"session"` (default) | `"project"`
+  (legacy repo-wide gate).
+- `reset-compact-pressure.sh`: staged-payload read is async (was a sync
+  `readFileSync` inside the hook deadline window; fixes BUG-C22-03 test).
+- `async-lock.mjs`: an `EEXIST` from the lock's PARENT-directory mkdir (a regular file
+  squatting on the store path) is a hard error, not lock contention — it used to spin
+  out the whole acquisition budget and hang crash-path hooks (`reinject-context`,
+  `output-compression`) for ~15 s instead of failing fast with a systemMessage.
+- `skill-router.sh`: restored a missing `};` (v3.4.11 syntax error that silently
+  disabled the whole router).
+- Hook-deadline conventions: no sync-fs mention in `verification-guard.sh`/
+  `observability-emit.mjs`, explicit timeout on the codex probe's `spawnSync`.
+- Test/doc hygiene: tests follow the cycle-91 inventory archive move; baseline
+  reconciliation pins the major.minor line instead of exact patch; decision-coverage
+  allowlist covers `deriveTypedDelegationAdvice`.
+
+## 3.4.11 - 2026-10-01
+
+**Gate posture is answer-first; only explicit change orders mint work debt.**
+The router now stamps `routingContext.planOnly` (new `isPlanOnlyRequest` —
+"chỉ lên plan", "plan thôi", "just plan it", "plan … không implement") next to
+`mutationOrder`. The completion gate's `no-mutation-order` valve covers both:
+when a prompt ordered no mutation or asked only for a plan/answer, missing
+`write-evidence` AND `verification-evidence` release loud instead of forcing
+an Edit loop. A prompt that does order a change — or a turn that already
+attempted an edit — keeps the normal gate. To implement a reviewed plan:
+"implement", "sửa", "làm luôn", or `execute this plan`.
+
 ## 3.4.10 - 2026-10-01
 
 **sensitive-data-guard reads .env placeholders.** `classifySecretFile` now

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.11",
+  "version": "3.4.12",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/probe/codex-capability-probe.mjs

@@ -34,7 +34,7 @@ const out = [];
 const say = (line = '') => { out.push(line); console.log(line); };
 
 function commandOnPath(cmd) {
-  const r = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8' });
+  const r = spawnSync('sh', ['-c', `command -v ${cmd}`], { encoding: 'utf8', timeout: 5000 });
   return r.status === 0 ? r.stdout.trim() : null;
 }
 

package/template_project/.claude/hooks/handoff-resume.sh

@@ -170,6 +170,20 @@ async function emitOrdinaryResume(payload, source) {
   const cursor = field('Cursor');
   const next = field('Next');
 
+  // A brand-new session (startup / clear) did not start this run and may be about
+  // something else entirely (e.g. planning). Tell it the run exists, but do NOT
+  // order a resume and do NOT use the resume marker the Stop gate treats as proof
+  // that the session owns the run. Resume stays automatic for compact / resume.
+  if (source === 'startup' || source === 'clear') {
+    process.stdout.write([
+      'UKit note: docs/AI_HANDOFF/RUN.md has an unfinished handoff-fullstack run '
+        + `(Phase: ${phase}; Next: ${next || 'not recorded'}).`,
+      'It belongs to an earlier session. Ignore it unless the user asks to continue it; their current request comes first.',
+      'To pick it up the user can run /ukit:handoff-fullstack; to discard it, /ukit:handoff-clear.',
+    ].join('\n') + '\n');
+    process.exit(0);
+  }
+
   const out = [
     'UKIT HANDOFF RESUME — an unfinished handoff-fullstack run was found on disk.',
     `  Goal:   ${goal || '(not recorded)'}`,

package/template_project/.claude/hooks/observability-emit.mjs

@@ -10,5 +10,9 @@
 // so the `execution.started` record lands before any slow .sh member can
 // exhaust the chain budget (a timeout further down would silently skip a
 // trailing emit step).
+//
+// Deadline contract: the chain runner passes `deadlineMs` into runHook and the
+// emit module bounds every write by it (HOOK_DEADLINE_MS fallback), so this
+// thin entry needs no watchdog of its own.
 
 export { runHook } from '../ukit/runtime/observability-emit.mjs';

package/template_project/.claude/hooks/reset-compact-pressure.sh

@@ -195,9 +195,10 @@ async function withLock(lockPath, fn) {
 // this hook waiting on EOF.
 const inputFile = process.argv[2];
 (async () => {
-  const payload = (() => {
+  // Async on purpose — a sync read on a stalled mount would park the deadline timer.
+  const payload = await (async () => {
     try {
-      const raw = require("fs").readFileSync(inputFile, "utf8");
+      const raw = await fsp.readFile(inputFile, "utf8");
       return JSON.parse(raw || "{}");
     } catch {
       return {};

package/template_project/.claude/hooks/skill-router.sh

@@ -2873,6 +2873,7 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
       ...(typeof routingContext.planOnly === 'boolean'
         ? { planOnly: routingContext.planOnly }
         : {}),
+    };
   }
 
   function compactHelpers({

package/template_project/.claude/hooks/verification-guard.sh

@@ -433,7 +433,7 @@ const NEW_SOURCE_FILE_RE = /\.(jsx?|tsx?|mjs|cjs|vue|svelte|css|scss|sass|less|h
 // `git status --porcelain` positions: untracked entries start '??', index-staged
 // adds start 'A'. Both are "component-create" candidates for the wiring check.
 // W2-D06: async execFile — a wedged git (slow index lock, network fs) must not
-// park the event loop inside the armed deadline block the way execFileSync did.
+// park the event loop inside the armed deadline block the way a synchronous exec did.
 // SIGKILL keeps the child bound hard even for a TERM-ignoring process.
 async function readGitChangedPaths(projectRoot) {
   return new Promise((resolve) => {

package/template_project/.claude/ukit/runtime/async-lock.mjs

@@ -451,6 +451,7 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
   // they get the fixed cleanup reserve instead of the acquisition slice.
   const releaseRetry = (op) => withTransientFsRetry(op, { deadlineMs: LOCK_RESERVE_MS });
 
+  let parentFailed = false;
   while (true) {
     // Abort wins over every other condition, checked once per iteration: an abort
     // landing mid-sweep/mid-op must still surface the typed aborted outcome — the
@@ -467,7 +468,9 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     try {
       // The lock parent must exist before the atomic acquire — a first-ever run in a
       // fresh project would otherwise fail mkdir with ENOENT.
+      parentFailed = true;
       await retry(() => fs.mkdir(path.dirname(lockPath), { recursive: true }));
+      parentFailed = false;
       await retry(() => fs.mkdir(lockPath)); // atomic acquire — EEXIST means another holder exists
       inProcessLockHolders.set(lockPath, ownerToken);
       try {
@@ -503,7 +506,10 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
       if (signal?.aborted) {
         return { ok: false, reason: 'aborted', waitedMs: Date.now() - startedAt };
       }
-      if (error?.code !== 'EEXIST') throw error;
+      // EEXIST from the PARENT mkdir means a regular file squats on the directory path —
+      // a broken store, not a lock holder. Waiting out the budget for it would burn the
+      // whole acquisition slice and then report 'busy'; surface the real error instead.
+      if (error?.code !== 'EEXIST' || parentFailed) throw error;
     }
 
     // Someone holds the lock. Reclaim it only after the stale threshold AND only when

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

@@ -201,6 +201,12 @@ export const HANDOFF_CURSOR_DEFAULTS = Object.freeze({
   // gate releases instead of trapping the session in an unstoppable loop — same
   // liveness shape as the ledger's noProgressCount breaker.
   maxStalledBlocks: 12,
+  // 'session' (default): the gate only bounces a stop when THIS session is the one
+  // driving the run (its transcript shows a handoff-fullstack invocation or a
+  // resume injection). A fresh session that merely shares the repo with a stale
+  // RUN.md — e.g. one opened just to plan something else — is never hijacked.
+  // 'project': legacy behaviour, any session in the repo is bounced.
+  scope: 'session',
 });
 
 // ─── Redaction ────────────────────────────────────────────────────────────
@@ -636,7 +642,17 @@ export async function evaluateStopReviewPolicy({ projectRoot, completionKind = n
       : 0;
 
     const ledgerModule = await loadLedgerReceiptModule();
-    const appendDecisionReceipt = ledgerModule?.appendDecisionReceipt;
+    // The policy fires its calibration receipt without awaiting it; collect the promises so
+    // the receipt is on disk before this evaluator returns (a loaded host otherwise leaves
+    // the write racing the next reader).
+    const pendingReceipts = [];
+    const appendDecisionReceipt = typeof ledgerModule?.appendDecisionReceipt === 'function'
+      ? (...args) => {
+        const written = ledgerModule.appendDecisionReceipt(...args);
+        pendingReceipts.push(Promise.resolve(written).catch(() => {}));
+        return written;
+      }
+      : undefined;
 
     const decision = policyModule.evaluateReviewPolicy({
       signals: routeSummary.suspicionSignals ?? {},
@@ -648,6 +664,7 @@ export async function evaluateStopReviewPolicy({ projectRoot, completionKind = n
       projectRoot,
       appendDecisionReceipt,
     });
+    await Promise.all(pendingReceipts);
     if (!decision || typeof decision !== 'object') return null;
 
     // Persist the round counter + last verdict for the next stop (same atomic
@@ -686,6 +703,9 @@ async function loadHandoffGateConfig(projectRoot) {
       maxStalledBlocks: Number.isFinite(gate?.stopGateMaxStalledBlocks)
         ? Math.max(1, gate.stopGateMaxStalledBlocks)
         : HANDOFF_CURSOR_DEFAULTS.maxStalledBlocks,
+      scope: gate?.stopGateScope === 'project' || gate?.stopGateScope === 'session'
+        ? gate.stopGateScope
+        : HANDOFF_CURSOR_DEFAULTS.scope,
     };
   } catch {
     return { ...HANDOFF_CURSOR_DEFAULTS };
@@ -835,6 +855,81 @@ function formatPredicateState(result) {
   return result.terms.map((t) => `${t.term}=${t.pass ? 'pass' : `FAIL (${t.detail})`}`).join(', ');
 }
 
+// ─── Session ownership (does THIS session drive the run?) ─────────────────
+// Structured evidence that a session itself started or resumed a handoff-fullstack
+// run. Raw-text matching is NOT enough: the marker strings appear in tool output,
+// bash commands and source files any session may read, so only these shapes count:
+//   - a real user turn carrying the slash-command tag for handoff-fullstack
+//   - a Skill tool call naming handoff-fullstack
+//   - a SessionStart hook attachment carrying the resume injection
+const HANDOFF_COMMAND_TAG = /<command-name>\/?(?:ukit:)?handoff-fullstack\b/;
+const HANDOFF_RESUME_BANNER = 'UKIT HANDOFF RESUME \u2014 an unfinished handoff-fullstack run';
+const OWNERSHIP_SCAN_BUDGET_MS = 1200;
+const OWNERSHIP_SCAN_MAX_BYTES = 64 * 1024 * 1024;
+
+function textOfUserTurn(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  // tool_result blocks are tool output, never the user's own words.
+  return content.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n');
+}
+
+function entryShowsHandoffRun(entry) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (entry.type === 'user' && entry.message && entry.message.role === 'user') {
+    return HANDOFF_COMMAND_TAG.test(textOfUserTurn(entry.message.content));
+  }
+  if (entry.type === 'assistant' && Array.isArray(entry.message?.content)) {
+    return entry.message.content.some((b) => b && b.type === 'tool_use' && b.name === 'Skill'
+      && /^(?:ukit:)?handoff-fullstack$/.test(String(b.input?.skill ?? '')));
+  }
+  if (entry.type === 'attachment' && entry.attachment && entry.attachment.hookEvent === 'SessionStart') {
+    const a = entry.attachment;
+    return [a.content, a.stdout, a.text].some((v) => typeof v === 'string' && v.includes(HANDOFF_RESUME_BANNER));
+  }
+  return false;
+}
+
+/**
+ * Stream the session transcript (JSONL) for structured handoff-run evidence.
+ * Returns true (found), false (whole transcript scanned, none found) or null
+ * (unknown: no path, unreadable, or scan budget/size cap hit). Callers treat
+ * null as "cannot prove this session is not the owner" and keep the legacy
+ * blocking behaviour — a real run must never be released by a lost read.
+ */
+export async function transcriptShowsHandoffRun(transcriptPath, {
+  budgetMs = OWNERSHIP_SCAN_BUDGET_MS,
+  maxBytes = OWNERSHIP_SCAN_MAX_BYTES,
+} = {}) {
+  if (typeof transcriptPath !== 'string' || !transcriptPath.trim()) return null;
+  let handle;
+  try {
+    handle = await fs.open(transcriptPath, 'r');
+    const deadline = Date.now() + budgetMs;
+    const chunk = Buffer.allocUnsafe(1024 * 1024);
+    let carry = '';
+    let total = 0;
+    const scanLine = (line) => {
+      // Cheap prefilter: skip JSON.parse for lines that cannot be evidence.
+      if (!line.includes('handoff-fullstack') && !line.includes('HANDOFF RESUME')) return false;
+      try { return entryShowsHandoffRun(JSON.parse(line)); } catch { return false; }
+    };
+    for (;;) {
+      const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+      if (!bytesRead) return scanLine(carry);
+      total += bytesRead;
+      const lines = (carry + chunk.toString('utf8', 0, bytesRead)).split('\n');
+      carry = lines.pop() ?? '';
+      for (const line of lines) if (scanLine(line)) return true;
+      if (total >= maxBytes || Date.now() > deadline) return null;
+    }
+  } catch {
+    return null;
+  } finally {
+    try { await handle?.close(); } catch {}
+  }
+}
+
 /**
  * Mutate `.ukit/storage/cache/stop-coordinator/state.json`'s `handoff` slot:
  * { signature, count }. Same signature as last time → count+1; a moved cursor
@@ -900,7 +995,7 @@ 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 } = {}) {
+export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), lockBudgetMs = LOCK_BUDGET_MS, transcriptPath = null } = {}) {
   const gate = await loadHandoffGateConfig(projectRoot);
   if (!gate.enabled) return { kind: 'none' };
 
@@ -917,8 +1012,16 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
   if (!phase || terminal === 'blocked') {
     return { kind: 'none' };
   }
+  if (terminal === 'done' && !exitPredicate) return { kind: 'none' }; // legacy phase-only release
+
+  // Session scope: a run owned by another session (or abandoned) must not
+  // hijack an unrelated session. Only a positive "scanned the whole transcript,
+  // no handoff evidence" releases; unknown (null) keeps the block.
+  if (gate.scope === 'session' && await transcriptShowsHandoffRun(transcriptPath) === false) {
+    return { kind: 'none' };
+  }
+
   if (terminal === 'done') {
-    if (!exitPredicate) return { kind: 'none' }; // legacy phase-only release
     let predicate;
     try {
       predicate = await evaluateExitPredicate(projectRoot, exitPredicate);
@@ -1064,7 +1167,12 @@ export async function runStopCoordinator({
   }
   let handoff = null;
   try {
-    handoff = await evaluateHandoffCursor({ projectRoot, now, lockBudgetMs });
+    handoff = await evaluateHandoffCursor({
+      projectRoot,
+      now,
+      lockBudgetMs,
+      transcriptPath: typeof payload?.transcript_path === 'string' ? payload.transcript_path : null,
+    });
   } catch (error) {
     failures.handoff = error?.message || String(error);
     process.stderr.write(`[ukit-stop-coordinator] handoff-cursor evaluator failed: ${failures.handoff}\n`);

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

@@ -1056,7 +1056,12 @@ export async function runSessionStop(
   let handoff = null;
   if (coordinator) {
     try {
-      handoff = await coordinator.evaluateHandoffCursor({ projectRoot, now, lockBudgetMs });
+      handoff = await coordinator.evaluateHandoffCursor({
+        projectRoot,
+        now,
+        lockBudgetMs,
+        transcriptPath: typeof payload.transcript_path === 'string' ? payload.transcript_path : null,
+      });
     } catch (error) {
       pi.logger?.warn?.(`[UKit] handoff-cursor evaluator failed (advisory lane): ${error?.message || error}`);
     }

package/template_project/docs/AI_HANDOFF/RULES.md

@@ -143,6 +143,9 @@ chạy **đến khi không còn gì để làm**:
 - Stop gate (Claude Code): `RUN.md` `Phase:` ≠ `done`/`blocked` → Stop hook từ chối
   stop kèm `Next:` step. Breaker `stopGateMaxStalledBlocks` (mặc định 12) thả ra nếu
   cursor không nhích — lối thoát, không phải đường thường.
+- Gate theo session (`stopGateScope: session`, mặc định): chỉ ép session đã chạy `/ukit:handoff-fullstack`
+  hoặc nhận resume marker (compact/resume). Session mới (startup/clear) chỉ nhận ghi chú, không bị ép;
+  muốn nối run cũ thì chạy `/ukit:handoff-fullstack`. Không đọc được transcript → giữ hành vi chặn cũ.
 - `handoff-clear` PHẢI đặt `Phase: done` (hoặc xóa RUN.md) — cursor sống sẽ giữ gate
   chặn stop của session sau.
 - Phase F: docs sync (WORKLOG luôn; PROJECT/CODE_MAP/CHANGELOG khi đổi surface) →

package/template_project/ukit/storage/config.json

@@ -525,6 +525,7 @@
     "fullstack": {
       "stopGateEnabled": true,
       "stopGateMaxStalledBlocks": 12,
+      "stopGateScope": "session",
       "stopGateMaxCrashStreaks": 3,
       "quietScansRequired": 2,
       "idleWatchdogMin": 5,
@@ -836,6 +837,7 @@
       "fullstack": {
         "stopGateEnabled": "B\u1eadt Stop gate handoff: RUN.md Phase != done/blocked \u2192 Stop hook t\u1eeb ch\u1ed1i stop k\u00e8m Next step, gi\u1eef handoff-fullstack ch\u1ea1y ti\u1ebfp thay v\u00ec \u0111\u1ee9ng sau recap. T\u1eaft ch\u1ec9 khi debug.",
         "stopGateMaxStalledBlocks": "Liveness breaker: cursor kh\u00f4ng nh\u00edch qua N l\u1ea7n block li\u00ean ti\u1ebfp th\u00ec gate th\u1ea3 stop (tr\u00e1nh v\u00f2ng l\u1eb7p v\u00f4 t\u1eadn). M\u1eb7c \u0111\u1ecbnh 12.",
+        "stopGateScope": "session = Stop gate chỉ ép khi chính session này đang chạy handoff-fullstack (transcript có /ukit:handoff-fullstack hoặc resume marker); session mới mở chỉ để plan/việc khác không bị ép. project = cũ: mọi session trong repo đều bị ép khi RUN.md còn sống.",
         "stopGateMaxCrashStreaks": "Liveness breaker cho coordinator crash: sau N l\u1ea7n block li\u00ean ti\u1ebfp do infrastructure failure, gate th\u1ea3 stop k\u00e8m c\u1ea3nh b\u00e1o l\u1edbn. M\u1eb7c \u0111\u1ecbnh 3.",
         "quietScansRequired": "S\u1ed1 scan li\u00ean ti\u1ebfp kh\u00f4ng th\u1ea5y vi\u1ec7c m\u1edbi tr\u01b0\u1edbc khi handoff-fullstack \u0111\u01b0\u1ee3c ph\u00e9p \u0111\u00f3ng run. M\u1eb7c \u0111\u1ecbnh 2.",
         "idleWatchdogMin": "Kho\u1ea3ng ph\u00fat cho scheduled wakeup n\u1ebfu harness h\u1ed7 tr\u1ee3 (cron/loop). M\u1eb7c \u0111\u1ecbnh 5.",