@ngockhoale/ukit 2.7.7 → 2.7.9

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

@@ -151,6 +151,13 @@ process.stdin.on("end", () => {
     }
   })();
   const sessionId = typeof payload.session_id === "string" ? payload.session_id.trim() : "";
+  // TASK-008 fix round: the pressure writer keys records by payload.session_id,
+  // and hosts that omit session_id on prompt/tool events (omp) now send the
+  // transcript path as the session key. When session_start DOES carry a real id
+  // but the writers did not, the record lives under the transcript key — delete
+  // both so the targeted reset cannot silently miss. Transcript paths are
+  // unique per session, so this can never touch a sibling record.
+  const transcriptKey = typeof payload.transcript_path === "string" ? payload.transcript_path.trim() : "";
   const pressurePath = process.argv[1];
 
   withLock(`${pressurePath}.lock`, async () => {
@@ -179,6 +186,9 @@ process.stdin.on("end", () => {
 
     const sessions = { ...raw.sessions };
     delete sessions[sessionId];
+    if (transcriptKey && transcriptKey !== sessionId) {
+      delete sessions[transcriptKey];
+    }
     const newest = Object.entries(sessions)
       .sort(([, a], [, b]) => (b?.updatedAt ?? 0) - (a?.updatedAt ?? 0))[0]?.[1] ?? null;
     const tempPath = `${pressurePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;

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

@@ -2523,6 +2523,10 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
     if (!entry || typeof entry !== 'object') {
       return;
     }
+    // The sandbox starts without .ukit/storage/cache. Create it before the
+    // sidecar append and lock acquisition; otherwise both operations fail with
+    // ENOENT and withStateLock falls through to an unlocked read-modify-write.
+    await ensureDir(filePath);
 
     // BUG-C23-15: the entry is STAGED to an append-only sidecar before the lock is
     // attempted (small appendFile is atomic — no read-modify-write, so no lost
@@ -2605,14 +2609,17 @@ setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
           if (!error || error.code !== 'EEXIST') return;
           try {
             const stat = fsSync.statSync(lockPath);
-            if (Date.now() - stat.mtimeMs > 10000) {
-              try {
-                const owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
-                if (!owner || !Number.isInteger(owner.pid) || !isPidAlive(owner.pid)) {
-                  fsSync.rmSync(lockPath, { recursive: true, force: true });
-                  continue;
-                }
-              } catch {
+            let owner = null;
+            try {
+              owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
+            } catch {}
+            // The watchdog may call process.exit while this process is in the
+            // async merge. Its finally block cannot run after that synchronous
+            // exit, so the exit fold must reclaim its own abandoned lock before
+            // folding the staged sidecar. A live foreign owner remains protected.
+            const ownInterruptedLock = owner?.pid === process.pid;
+            if (ownInterruptedLock || Date.now() - stat.mtimeMs > 10000) {
+              if (ownInterruptedLock || !owner || !isPidAlive(owner.pid)) {
                 fsSync.rmSync(lockPath, { recursive: true, force: true });
                 continue;
               }

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

@@ -215,6 +215,9 @@ function isVerificationCommand(command) {
   ].some((pattern) => pattern.test(command));
 }
 
+// F-15: execution-ledger.mjs mirrors this list in its own
+// isExplicitBroadVerificationRequest — the completion gate honors the same
+// explicit-broad signal when classifying a scope='broad' receipt. Keep both in sync.
 function isExplicitBroadVerificationRequest(promptText) {
   const text = String(promptText || '').toLowerCase();
   return [

package/templates/.claude/ukit/index/route-task.mjs

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
-import { realpathSync } from 'node:fs';
+// `fsSync` aliases the SAME fs module — used ONLY by the process.on('exit')
+// audit-sidecar fold below (event loop is gone; async cannot run) and by the
+// module-bottom direct-CLI check. Normal-path fs stays async.
+import * as fsSync from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
@@ -13,6 +16,7 @@ import {
 } from './cache-utils.mjs';
 import { ROUTE_CATALOG } from './route-catalog.mjs';
 import { detectUnicGateway } from './unic-gateway.mjs';
+import { withAsyncLock } from '../runtime/async-lock.mjs';
 
 const {
   resolveContext,
@@ -946,7 +950,7 @@ async function main() {
     };
     sharedState.fingerprint = buildRouteStateFingerprint(sharedState);
     if (canPersistCachedRouteState) {
-      await writeJson(sharedStatePath, sharedState);
+      await persistSharedRouteState(sharedStatePath, sharedState);
       await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
         state: sharedState,
       }));
@@ -991,7 +995,7 @@ async function main() {
     sessionId,
   });
   if (canPersistRouteState) {
-    await writeJson(sharedStatePath, sharedState);
+    await persistSharedRouteState(sharedStatePath, sharedState);
     await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
       route,
       state: sharedState,
@@ -3816,35 +3820,241 @@ function buildRouteAuditEntry({ route = null, state = null } = {}) {
   };
 }
 
-async function appendRouteAuditEntry(filePath, entry) {
+// CX-8: the shared route-state/audit writes must obey the same protocol as the
+// claude/omp writers (skill-router.sh + token-utils withFileLock): tmp+rename
+// atomicity AND the owner-token `<file>.lock` serialization. The pre-fix bare
+// fs.writeFile raced the locked writers — a torn skill-router-state.json parses
+// as `{}` downstream and releases a premature Stop; the unlocked audit
+// read-modify-write lost entries under concurrent routers.
+export async function writeJsonAtomic(filePath, value) {
+  // tmp+rename: readers see old-or-new, never a torn/half file.
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  try {
+    await fs.writeFile(tempPath, JSON.stringify(value), 'utf8');
+    await fs.rename(tempPath, filePath);
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+    throw error;
+  }
+}
+
+// The state write is a pure overwrite, but it must still serialize under the
+// owner-token lock so a codex writer cannot interleave with a locked claude/omp
+// writer mid-flight. Fail-closed (CX-8): a busy lock skips the write — the next
+// route recomputes and overwrites the whole document anyway, so a skipped
+// overwrite loses nothing; an unlocked one can interleave with a live holder.
+export async function persistSharedRouteState(filePath, state) {
+  const result = await withAsyncLock(filePath, {}, () => writeJsonAtomic(filePath, state));
+  if (!result.ok) {
+    console.error(`route-task: skill-router-state lock ${result.reason} after ${result.waitedMs}ms — state write skipped (fail-closed)`);
+  }
+  return result;
+}
+
+// Ported from skill-router.sh entryDedupeKey — `|| null` (not `?? null`) so
+// falsy fields like repeatCount: 0 produce the same digest in both engines and
+// cross-engine dedupe of the shared route-audit.json cannot duplicate entries.
+function routeAuditEntryDedupeKey(item) {
+  return stableMachineDigest({
+    requestKey: item?.requestKey || null,
+    executionMode: item?.executionMode || null,
+    nextActionType: item?.nextActionType || null,
+    nextMilestone: item?.nextMilestone || null,
+    repeatCount: item?.repeatCount || null,
+    rescueMode: item?.rescueMode || null,
+  });
+}
+
+// Merge order: the fresh entry first, then staged sidecar lines, then the
+// existing file. A staged/existing row with the new entry's dedupe key is
+// replaced by the fresh entry; every other key keeps its first occurrence.
+function mergeRouteAuditEntries(staged, parsed, newEntry) {
+  const dedupeKey = newEntry ? routeAuditEntryDedupeKey(newEntry) : null;
+  const merged = [];
+  const seen = new Set();
+  for (const item of [newEntry, ...staged, ...(Array.isArray(parsed?.entries) ? parsed.entries : [])]) {
+    if (!item || typeof item !== 'object') continue;
+    const key = routeAuditEntryDedupeKey(item);
+    if (dedupeKey && key === dedupeKey && item !== newEntry) continue;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(item);
+  }
+  return merged.slice(0, 40);
+}
+
+function parseRouteAuditSidecar(raw) {
+  const recovered = [];
+  for (const line of String(raw || '').split('\n')) {
+    if (!line.trim()) continue;
+    try {
+      const item = JSON.parse(line);
+      if (item && typeof item === 'object') recovered.push(item);
+    } catch {
+      // skip unparseable sidecar lines
+    }
+  }
+  return recovered;
+}
+
+function isPidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM: the process exists but belongs to another user — still alive.
+    return error?.code === 'EPERM';
+  }
+}
+
+// Synchronous last-chance fold for the process-exit path: process.on('exit')
+// handlers run without the event loop, so sync fs is legal here (fsSync alias).
+// Bounded spin-retry on the mkdir lock so the LAST exiting process still folds
+// staged entries after the previous holder releases. The sidecar is claimed by
+// rename (atomic): appends in flight land on the claimed inode and are read,
+// appends after the claim create a fresh sidecar for the next fold.
+function foldRouteAuditSidecarSync(filePath) {
+  const sidecarPath = `${filePath}.unlocked.jsonl`;
+  const lockPath = `${filePath}.lock`;
+  const deadline = Date.now() + 300;
+  let held = false;
+  while (!held && Date.now() < deadline) {
+    try {
+      fsSync.mkdirSync(lockPath);
+      held = true;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') return;
+      try {
+        const stat = fsSync.statSync(lockPath);
+        let owner = null;
+        try {
+          owner = JSON.parse(fsSync.readFileSync(path.join(lockPath, 'owner'), 'utf8'));
+        } catch {
+          // unreadable owner — treated as no owner below
+        }
+        // An exit during our own async merge abandons our lock; reclaim it. A
+        // live foreign owner stays protected; a dead/stale one is reclaimed.
+        const ownInterruptedLock = owner?.pid === process.pid;
+        if (ownInterruptedLock || Date.now() - stat.mtimeMs > 10000) {
+          if (ownInterruptedLock || !owner || !isPidAlive(owner.pid)) {
+            fsSync.rmSync(lockPath, { recursive: true, force: true });
+            continue;
+          }
+        }
+      } catch {
+        // stat failed — fall through to the bounded spin
+      }
+      const until = Date.now() + 5;
+      while (Date.now() < until) { /* bounded spin */ }
+    }
+  }
+  if (!held) return;
+  try {
+    const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+    try {
+      fsSync.renameSync(sidecarPath, claimedPath);
+    } catch {
+      return; // no staged sidecar — nothing to fold
+    }
+    let staged = [];
+    try {
+      staged = parseRouteAuditSidecar(fsSync.readFileSync(claimedPath, 'utf8'));
+    } catch {
+      // unreadable claim — treated as empty below
+    }
+    try {
+      fsSync.rmSync(claimedPath, { force: true });
+    } catch {
+      // best-effort cleanup
+    }
+    if (!staged.length) return;
+    let parsed = { entries: [] };
+    try {
+      parsed = JSON.parse(fsSync.readFileSync(filePath, 'utf8'));
+    } catch {
+      parsed = { entries: [] };
+    }
+    const tmpPath = `${filePath}.exitfold-${process.pid}`;
+    fsSync.writeFileSync(tmpPath, JSON.stringify({
+      entries: mergeRouteAuditEntries(staged, parsed, null),
+    }));
+    fsSync.renameSync(tmpPath, filePath);
+  } finally {
+    try {
+      fsSync.rmSync(lockPath, { recursive: true, force: true });
+    } catch {
+      // best-effort release
+    }
+  }
+}
+
+const armedRouteAuditFolds = new Set();
+
+export async function appendRouteAuditEntry(filePath, entry) {
   if (!entry || typeof entry !== 'object') {
     return;
   }
+  // The sandbox starts without .ukit/storage/cache. Create it before the
+  // sidecar append and lock acquisition; otherwise both fail with ENOENT.
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
 
-  const existing = await readJson(filePath, { entries: [] });
-  const entries = Array.isArray(existing?.entries) ? existing.entries : [];
-  const dedupeKey = stableMachineDigest({
-    requestKey: entry.requestKey,
-    executionMode: entry.executionMode,
-    nextActionType: entry.nextActionType,
-    nextMilestone: entry.nextMilestone,
-    repeatCount: entry.repeatCount,
-    rescueMode: entry.rescueMode,
-  });
-  const filtered = entries.filter((item) => {
-    const itemKey = stableMachineDigest({
-      requestKey: item?.requestKey ?? null,
-      executionMode: item?.executionMode ?? null,
-      nextActionType: item?.nextActionType ?? null,
-      nextMilestone: item?.nextMilestone ?? null,
-      repeatCount: item?.repeatCount ?? null,
-      rescueMode: item?.rescueMode ?? null,
+  // The entry is STAGED to an append-only sidecar before the lock is attempted
+  // (small appendFile is atomic — no read-modify-write, so no lost updates even
+  // under full contention). Every lock holder folds all staged entries into
+  // route-audit.json inside its merge; a synchronous last-chance fold is also
+  // armed on process exit — whichever process exits last folds every staged
+  // entry. The audit entry can never be silently dropped.
+  const sidecarPath = `${filePath}.unlocked.jsonl`;
+  try {
+    await fs.appendFile(sidecarPath, `${JSON.stringify(entry)}\n`);
+  } catch {
+    // staging failed — still attempt the locked merge so the entry is not lost
+  }
+  if (!armedRouteAuditFolds.has(filePath)) {
+    armedRouteAuditFolds.add(filePath);
+    process.on('exit', () => foldRouteAuditSidecarSync(filePath));
+  }
+
+  const result = await withAsyncLock(filePath, {}, async () => {
+    // Claim staged lines atomically inside the lock: rename detaches the inode,
+    // so lines appended during the fold land in a fresh sidecar for the next
+    // pass instead of being deleted unread.
+    const claimedPath = `${sidecarPath}.claim-${process.pid}-${Date.now()}`;
+    let claimed = false;
+    try {
+      await fs.rename(sidecarPath, claimedPath);
+      claimed = true;
+    } catch {
+      // no sidecar — nothing staged
+    }
+    const sidecarEntries = claimed
+      ? parseRouteAuditSidecar(await fs.readFile(claimedPath, 'utf8').catch(() => ''))
+      : [];
+    if (claimed) {
+      try {
+        await fs.rm(claimedPath, { force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+
+    const parsed = await readJson(filePath, { entries: [] });
+    await writeJsonAtomic(filePath, {
+      entries: mergeRouteAuditEntries(sidecarEntries, parsed, entry),
     });
-    return itemKey !== dedupeKey;
-  });
-  await writeJson(filePath, {
-    entries: [entry, ...filtered].slice(0, 40),
   });
+  if (!result.ok) {
+    // Fail-closed on the merge (CX-8): the entry stays staged in the sidecar —
+    // the next locked merge or the exit fold picks it up.
+    console.error(`route-task: route-audit lock ${result.reason} after ${result.waitedMs}ms — audit entry staged to the append-only sidecar`);
+  }
+  return result;
 }
 
 async function readJson(filePath, fallback = null) {
@@ -3855,11 +4065,6 @@ async function readJson(filePath, fallback = null) {
   }
 }
 
-async function writeJson(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(value), 'utf8');
-}
-
 function normalize(text) {
   return String(text ?? '')
     .toLowerCase()
@@ -4233,7 +4438,7 @@ function isDirectCliInvocation() {
     if (import.meta.url === pathToFileURL(entry).href) {
       return true;
     }
-    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+    return import.meta.url === pathToFileURL(fsSync.realpathSync(entry)).href;
   } catch {
     return false;
   }

package/templates/.claude/ukit/index/stale-spec-check.mjs

@@ -1,6 +1,8 @@
 import { analyzeTextFile, publicTextProfile } from '../runtime/text-profile.mjs';
+import { TRANSIENT_FS_CODES, withTransientFsRetry } from '../runtime/async-lock.mjs';
 import { fileURLToPath } from 'node:url';
 import fsSync from 'node:fs';
+import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
   classifySafePatchRisk,
@@ -8,7 +10,6 @@ import {
   isSafePatchAdvisoryOnly,
   lineNumberForIndex,
   parseJsonInput,
-  pathExists,
   readRuntimeSafePatchConfig,
   resolveProjectFile,
   summarizeSnippet,
@@ -40,6 +41,34 @@ if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
   }, HOOK_DEADLINE_MS).unref();
 }
 
+// C44: the target reads below can surface a transient kernel EAGAIN on external
+// volumes. Retry them inside a bounded slice of the hook deadline; on final
+// failure rethrow with a transient-fs classification so the crash handler's
+// stderr is identifiable (and the bridge's fail-open translation can match it).
+const TRANSIENT_READ_DEADLINE_MS = 800;
+
+function classifyTransientFsError(error) {
+  if (TRANSIENT_FS_CODES.has(error?.code)) {
+    throw new Error(`transient-fs ${error.code} on target read: ${error.message}`);
+  }
+  throw error;
+}
+
+// Existence probe that surfaces transient codes to the retry wrapper. The
+// shared pathExists() helper swallows every error into `false`, which would
+// silently degrade a transient EAGAIN into "new file" and skip the stale-spec
+// check on a file that is actually there — non-transient misses keep that
+// same false mapping here.
+async function probeExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    if (TRANSIENT_FS_CODES.has(error?.code)) throw error;
+    return false;
+  }
+}
+
 function getToolName(payload = {}) {
   return String(payload.tool_name || payload.tool || payload.name || '').trim();
 }
@@ -66,12 +95,18 @@ export async function checkStaleSpec({ projectRoot = process.cwd(), payload = {}
   const filePath = getFilePath(payload);
   if (!filePath) return { status: 'skipped', reason: 'no-file' };
   const resolved = resolveProjectFile(projectRoot, filePath);
-  const exists = await pathExists(resolved.absolute);
+  const exists = await withTransientFsRetry(
+    () => probeExists(resolved.absolute),
+    { deadlineMs: TRANSIENT_READ_DEADLINE_MS },
+  ).catch(classifyTransientFsError);
 
   let profile = null;
   let risk = classifySafePatchRisk(resolved.relative, null, config);
   if (exists) {
-    profile = await analyzeTextFile(resolved.absolute);
+    profile = await withTransientFsRetry(
+      () => analyzeTextFile(resolved.absolute),
+      { deadlineMs: TRANSIENT_READ_DEADLINE_MS },
+    ).catch(classifyTransientFsError);
     risk = classifySafePatchRisk(resolved.relative, profile, config);
   }
   const strict = Boolean(config.strictSharedRisk) && risk.strict;