@ngockhoale/ukit 2.3.6 → 2.3.8

package/templates/.claude/ukit/index/cache-utils.mjs

@@ -1,6 +1,30 @@
 #!/usr/bin/env node
+// Cache read-modify-write cycles run in separate node processes (query/triage/route/
+// resolve-context hooks and CLI calls can fire concurrently). They must serialize on
+// withFileLock — without it, concurrent writers each append against a stale snapshot
+// and silently drop each other's entries (verified: 20 concurrent writers kept 2).
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { readJson, withFileLock } from '../runtime/token-utils.mjs';
+
+// Cache files stay single-line compact JSON (locked by tests): they sit inside .claude/
+// and pretty-printing them would turn every cache touch into a noisy multi-line diff.
+// Atomic like token-utils writeJson (tmp + rename), only compact.
+async function writeCacheJson(cachePath, value) {
+  await fs.mkdir(path.dirname(cachePath), { recursive: true });
+  const tempPath = `${cachePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    await fs.writeFile(tempPath, JSON.stringify(value), 'utf8');
+    await fs.rename(tempPath, cachePath);
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+    throw error;
+  }
+}
 
 export const DEFAULT_RECENT_CACHE_MAX_ENTRIES = 6;
 
@@ -36,14 +60,25 @@ export async function readRecentCacheEntry(
     ...entry,
     updatedAt: Date.now(),
   };
-  const entries = [
-    touchedEntry,
-    ...cache.entries.slice(0, entryIndex),
-    ...cache.entries.slice(entryIndex + 1),
-  ].slice(0, maxEntries);
-  const document = buildCacheDocument(entries, { maxEntries });
-  await writeJson(cachePath, document);
-  return document.entries[0] ?? touchedEntry;
+  return withFileLock(cachePath, async () => {
+    const locked = await readRecentCache(cachePath, { maxEntries });
+    const lockedIndex = locked.entries.findIndex((lockedEntry) => lockedEntry.requestKey === requestKey);
+    if (lockedIndex < 0) {
+      return touchedEntry;
+    }
+    const lockedEntry = {
+      ...locked.entries[lockedIndex],
+      updatedAt: touchedEntry.updatedAt,
+    };
+    const entries = [
+      lockedEntry,
+      ...locked.entries.slice(0, lockedIndex),
+      ...locked.entries.slice(lockedIndex + 1),
+    ].slice(0, maxEntries);
+    const document = buildCacheDocument(entries, { maxEntries });
+    await writeCacheJson(cachePath, document);
+    return document.entries[0] ?? lockedEntry;
+  });
 }
 
 export async function writeRecentCacheEntry(
@@ -56,14 +91,16 @@ export async function writeRecentCacheEntry(
     return readRecentCache(cachePath, { maxEntries });
   }
 
-  const cache = await readRecentCache(cachePath, { maxEntries });
-  const entries = [
-    normalizedEntry,
-    ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
-  ].slice(0, maxEntries);
-  const document = buildCacheDocument(entries, { maxEntries });
-  await writeJson(cachePath, document);
-  return document;
+  return withFileLock(cachePath, async () => {
+    const cache = await readRecentCache(cachePath, { maxEntries });
+    const entries = [
+      normalizedEntry,
+      ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
+    ].slice(0, maxEntries);
+    const document = buildCacheDocument(entries, { maxEntries });
+    await writeCacheJson(cachePath, document);
+    return document;
+  });
 }
 
 function normalizeCacheDocument(raw, { maxEntries = DEFAULT_RECENT_CACHE_MAX_ENTRIES } = {}) {
@@ -125,16 +162,3 @@ function normalizeCacheEntry(entry) {
   delete normalizedEntry.entries;
   return normalizedEntry;
 }
-
-async function readJson(filePath, fallback = null) {
-  try {
-    return JSON.parse(await fs.readFile(filePath, 'utf8'));
-  } catch {
-    return fallback;
-  }
-}
-
-async function writeJson(filePath, value) {
-  await fs.mkdir(path.dirname(typeof filePath === 'string' && filePath ? filePath : '.'), { recursive: true });
-  await fs.writeFile(filePath, JSON.stringify(value), 'utf8');
-}

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -8,6 +8,8 @@ import {
   compressLine,
   estimateTokenCount,
   readJson,
+  withFileLock,
+  writeJson,
 } from './token-utils.mjs';
 
 const DEFAULT_MAX_PROMPT_ENTRIES = 12;
@@ -666,7 +668,71 @@ export function resolveThresholdCompactBudget({
   };
 }
 
+// ---- session-scoped pressure document ---------------------------------------
+// compact-pressure.json holds ONE record per session id. A session starting must never
+// zero another live session's pressure bookkeeping (its hard-cap gate and compact
+// advisories), and a brand-new session must not inherit a sibling's totals. The newest
+// record's flat fields stay projected at the document's top level so readers that predate
+// this shape (raw JSON readers) still see a coherent state.
+const PRESSURE_SESSIONS_MAX = 8;
+
+function normalizeSessionId(value) {
+  const id = typeof value === 'string' ? value.trim() : '';
+  return id || null;
+}
+
+function readPressureDocument(raw) {
+  if (raw && typeof raw === 'object' && raw.sessions && typeof raw.sessions === 'object') {
+    const sessions = {};
+    for (const [id, record] of Object.entries(raw.sessions)) {
+      if (id && record && typeof record === 'object') {
+        sessions[id] = record;
+      }
+    }
+    return sessions;
+  }
+  // Legacy single-record file: preserve the in-flight session under a shared bucket.
+  return raw && typeof raw === 'object' ? { default: raw } : {};
+}
+
+function pickPressureSession(sessions, sessionId) {
+  if (sessionId) {
+    // A session id that has no record yet starts clean — it must not inherit another
+    // session's totals, and the other way round nothing here touches that session.
+    return { id: sessionId, record: sessions[sessionId] ?? null };
+  }
+  const entries = Object.entries(sessions);
+  if (!entries.length) {
+    return { id: 'default', record: null };
+  }
+  const newest = entries
+    .sort(([, left], [, right]) => finiteNumber(right?.updatedAt, 0) - finiteNumber(left?.updatedAt, 0))[0];
+  return { id: newest[0], record: newest[1] };
+}
+
+function resolvePressureRecord(raw, config) {
+  if (!raw || typeof raw !== 'object' || !raw.sessions || typeof raw.sessions !== 'object') {
+    return raw; // flat legacy state — normalized as-is below
+  }
+  const { record } = pickPressureSession(readPressureDocument(raw), normalizeSessionId(config?.sessionId));
+  return record;
+}
+
+function projectPressureDocument(sessions) {
+  const newestFirst = Object.entries(sessions)
+    .sort(([, left], [, right]) => finiteNumber(right?.updatedAt, 0) - finiteNumber(left?.updatedAt, 0))
+    .slice(0, PRESSURE_SESSIONS_MAX);
+  const newestRecord = newestFirst[0]?.[1] ?? null;
+  return {
+    ...(newestRecord && typeof newestRecord === 'object' ? newestRecord : {}),
+    updatedAt: finiteNumber(newestRecord?.updatedAt, Date.now()),
+    v: 2,
+    sessions: Object.fromEntries(newestFirst),
+  };
+}
+
 export function buildCompactPressureState(rawState = null, config = {}) {
+  rawState = resolvePressureRecord(rawState, config);
   const thresholds = buildCompactThresholds(config);
   const rawSoftThreshold = finiteNumber(rawState?.softThreshold, 0);
   const rawHardThreshold = finiteNumber(rawState?.hardThreshold, 0);
@@ -1051,30 +1117,64 @@ export async function readCompactPressureState(projectRoot, config = {}) {
   return buildCompactPressureState(await readJson(runtimePaths.compactPressurePath, null), config);
 }
 
+// All compact-pressure mutations share one lock on the state file: without it,
+// concurrent hook processes (parallel subagents) and same-process flows interleave
+// their read-modify-write cycles and silently drop each other's sessionTokens.
+// Mutations are session-scoped: only the calling session's record is rewritten;
+// sibling session records pass through untouched.
+async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
+    const { id, record } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
+    const current = buildCompactPressureState(record, config);
+    const next = mutator(current);
+    const normalized = buildCompactPressureState(next, config);
+    sessions[id] = { ...normalized, updatedAt: Date.now() };
+    await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
+    return normalized;
+  });
+}
+
 export async function writeCompactPressureState(projectRoot, state, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const normalized = buildCompactPressureState(state, config);
-  await fs.mkdir(path.dirname(runtimePaths.compactPressurePath), { recursive: true });
-  await fs.writeFile(runtimePaths.compactPressurePath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf8');
-  return normalized;
+  return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
+    const { id } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
+    const normalized = buildCompactPressureState(state, config);
+    sessions[id] = { ...normalized, updatedAt: Date.now() };
+    await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
+    return normalized;
+  });
+}
+
+function pressureSessionConfig(payload = {}, config = {}) {
+  const sessionId = normalizeSessionId(payload?.sessionId) ?? normalizeSessionId(config?.sessionId);
+  return sessionId ? { ...config, sessionId } : config;
 }
 
 export async function updateCompactPressureFromPrompt(projectRoot, payload, config = {}) {
-  const current = await readCompactPressureState(projectRoot, config);
-  const next = registerPromptPressure(current, payload, config);
-  return writeCompactPressureState(projectRoot, next, config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerPromptPressure(current, payload, config),
+    pressureSessionConfig(payload, config),
+  );
 }
 
 export async function updateCompactPressureFromOutput(projectRoot, payload, config = {}) {
-  const current = await readCompactPressureState(projectRoot, config);
-  const next = registerOutputPressure(current, payload, config);
-  return writeCompactPressureState(projectRoot, next, config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerOutputPressure(current, payload, config),
+    pressureSessionConfig(payload, config),
+  );
 }
 
 export async function writeThresholdCompactPlan(projectRoot, plan, config = {}) {
-  const current = await readCompactPressureState(projectRoot, config);
-  const next = registerThresholdCompactPlan(current, plan, config);
-  return writeCompactPressureState(projectRoot, next, config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerThresholdCompactPlan(current, plan, config),
+    pressureSessionConfig(plan, config),
+  );
 }
 
 async function loadRuntimeConfig(projectRoot) {
@@ -1130,6 +1230,16 @@ async function runCli() {
       return;
     }
 
+    // Session-scoped bookkeeping: every read/write in this branch targets the calling
+    // session's record, so a sibling session starting in the same project cannot zero
+    // this session's pressure history.
+    const sessionConfig = {
+      ...config,
+      sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
+        ? payload.session_id.trim()
+        : undefined,
+    };
+
     // Heal a stale counter BEFORE the phase is computed. Auto-compact paths that never
     // fire the PreCompact hook leave sessionTokens counting history that was already
     // summarised away — that phantom total is how a healthy session got hard-cap blocked.
@@ -1137,21 +1247,22 @@ async function runCli() {
     // automatic, so they are the correction signal here.
     try {
       const synced = await syncCompactPressureStateWithTranscript(
-        await readCompactPressureState(projectRoot, config),
-        config,
+        await readCompactPressureState(projectRoot, sessionConfig),
+        sessionConfig,
         payload.transcript_path,
       );
       if (synced.reset) {
-        await writeCompactPressureState(projectRoot, synced.state, config);
+        await writeCompactPressureState(projectRoot, synced.state, sessionConfig);
       }
     } catch { /* advisory healing only — never block the prompt over it */ }
 
     const nextState = await updateCompactPressureFromPrompt(projectRoot, {
       promptText,
+      sessionId: sessionConfig.sessionId,
       routingContext: routeState?.routingContext ?? {},
       previousContext: routeState?.previousContext ?? null,
       routeSummary: routeState?.routeSummary ?? null,
-    }, config);
+    }, sessionConfig);
 
     if (nextState.phase === 'hard') {
       process.stdout.write(

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { withFileLock } from './token-utils.mjs';
 
 const LEDGER_VERSION = 1;
 const RESUME_INTENT_VERSION = 1;
@@ -566,29 +567,38 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
 }
 
 export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null) {
-  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
-  // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
-  // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
-  // persist says 7) and the next request inherits a nearly exhausted budget.
-  const stale = requestKey
-    && current?.continuationRequestKey
-    && current.continuationRequestKey !== requestKey;
-  const next = {
-    ...current,
-    continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
-    ...(requestKey ? { continuationRequestKey: requestKey } : {}),
-    lastContinuationAt: Date.now(),
-    updatedAt: Date.now(),
-  };
-  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
-  return next;
+  const target = ledgerPath(projectRoot, payload);
+  // Locked re-read: parallel subagents firing Stop hooks share one ledger file, and a
+  // stale-snapshot rewrite would reset each other's continuationCount — the budget would
+  // never advance and the gate would keep issuing continuations.
+  return withFileLock(target, async () => {
+    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
+    // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
+    // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
+    // persist says 7) and the next request inherits a nearly exhausted budget.
+    const stale = requestKey
+      && current?.continuationRequestKey
+      && current.continuationRequestKey !== requestKey;
+    const next = {
+      ...current,
+      continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
+      ...(requestKey ? { continuationRequestKey: requestKey } : {}),
+      lastContinuationAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    await writeJsonAtomic(target, next);
+    return next;
+  });
 }
 
 export async function markNotified(projectRoot, payload = {}, ledger = null) {
-  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
-  const next = { ...current, notified: true, updatedAt: Date.now() };
-  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
-  return next;
+  const target = ledgerPath(projectRoot, payload);
+  return withFileLock(target, async () => {
+    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
+    const next = { ...current, notified: true, updatedAt: Date.now() };
+    await writeJsonAtomic(target, next);
+    return next;
+  });
 }
 
 async function readStdin() {

package/templates/.claude/ukit/runtime/output-compression.mjs

@@ -10,6 +10,8 @@ import {
   readJson,
   readPromptCacheEntry,
   recordCompaction,
+  withFileLock,
+  writeJson,
   writePromptCacheEntry,
 } from './token-utils.mjs';
 import { updateCompactPressureFromOutput } from './compact-threshold.mjs';
@@ -1113,26 +1115,26 @@ function normalizeOutputHistoryDocument(raw) {
   };
 }
 
-async function writeJson(filePath, value) {
-  await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-}
-
 async function appendOutputHistory(projectRoot, entry) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const current = normalizeOutputHistoryDocument(await readJson(runtimePaths.outputHistoryPath, { entries: [] }));
-  const normalizedEntry = normalizeOutputHistoryEntry(entry);
-  if (!normalizedEntry) return current;
-  const normalizedKey = buildOutputHistoryDedupeKey(normalizedEntry);
-  const dedupedExistingEntries = current.entries.filter((candidate) => !(
-    buildOutputHistoryDedupeKey(candidate) === normalizedKey
-  ));
-
-  const nextDocument = normalizeOutputHistoryDocument({
-    entries: [normalizedEntry, ...dedupedExistingEntries],
+  // The read-merge-write cycle runs under the state-file lock: concurrent tool-output
+  // captures (parallel subagents fire hooks in separate processes) otherwise read the
+  // same old history and overwrite each other, leaving only one survivor entry.
+  return withFileLock(runtimePaths.outputHistoryPath, async () => {
+    const current = normalizeOutputHistoryDocument(await readJson(runtimePaths.outputHistoryPath, { entries: [] }));
+    const normalizedEntry = normalizeOutputHistoryEntry(entry);
+    if (!normalizedEntry) return current;
+    const normalizedKey = buildOutputHistoryDedupeKey(normalizedEntry);
+    const dedupedExistingEntries = current.entries.filter((candidate) => !(
+      buildOutputHistoryDedupeKey(candidate) === normalizedKey
+    ));
+
+    const nextDocument = normalizeOutputHistoryDocument({
+      entries: [normalizedEntry, ...dedupedExistingEntries],
+    });
+    await writeJson(runtimePaths.outputHistoryPath, nextDocument);
+    return nextDocument;
   });
-  await writeJson(runtimePaths.outputHistoryPath, nextDocument);
-  return nextDocument;
 }
 
 async function findOutputHistoryEntry(projectRoot, command, summary) {
@@ -1187,6 +1189,14 @@ async function main() {
 
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // Session-scoped pressure bookkeeping: output tokens must land in the calling
+  // session's record, never a sibling session's.
+  const sessionConfig = {
+    ...config,
+    sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
+      ? payload.session_id.trim()
+      : undefined,
+  };
   if (!shouldCompress(config)) {
     process.exit(0);
     return;
@@ -1245,7 +1255,7 @@ async function main() {
         tokensAfter: cached.tokensAfter ?? 0,
         savedTokens: cached.savedTokens ?? 0,
         exitCode,
-      }, config);
+      }, sessionConfig);
       process.stdout.write(String(cached.content));
       return;
     }
@@ -1343,7 +1353,7 @@ async function main() {
     tokensAfter: result.tokensAfter,
     savedTokens: result.savedTokens,
     exitCode,
-  }, config);
+  }, sessionConfig);
 
   if (config?.tokenPipeline?.promptCache) {
     await writePromptCacheEntry(projectRoot, {

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -43,6 +43,30 @@ async function main() {
     ? process.env.CLAUDE_PROJECT_DIR
     : process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // Session-scoped pressure bookkeeping: this PreCompact run must zero ONLY the calling
+  // session's record. Reading stdin here is safe — the harness payload is modest and this
+  // process owns it exclusively.
+  const rawHookInput = await (async () => {
+    if (process.stdin.isTTY) return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    }
+    return chunks.join('');
+  })();
+  const hookPayload = (() => {
+    try {
+      return JSON.parse(rawHookInput || '{}');
+    } catch {
+      return {};
+    }
+  })();
+  const sessionConfig = {
+    ...config,
+    sessionId: typeof hookPayload.session_id === 'string' && hookPayload.session_id.trim()
+      ? hookPayload.session_id.trim()
+      : undefined,
+  };
   const state = await loadFreshRouteState(projectRoot);
   const compressEnabled = shouldCompress(config);
   const header = '=== PROJECT CONTEXT (post-compaction) ===';
@@ -67,15 +91,16 @@ async function main() {
 
   const rawBodyLines = [...rawStaticLines, ...dynamicLines];
   const bodyLines = [...staticLines, ...dynamicLines];
-  const pressureState = await readCompactPressureState(projectRoot, config);
+  const pressureState = await readCompactPressureState(projectRoot, sessionConfig);
 
   // Reset the hard-cap tracker as early as possible: this hook fires on every real
   // compaction, and it is the only signal that context actually shrank. It must happen
   // before the promptCache early-return below, otherwise a cache hit would skip it and
   // leave context-hardcap-gate.sh permanently tripped. Downstream writes
   // (writeThresholdCompactPlan) re-read from disk, so they build on the zeroed state and
-  // keep their own stats increments intact.
-  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, config), config);
+  // keep their own stats increments intact. Session-scoped: sibling sessions keep their
+  // own records.
+  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, sessionConfig), sessionConfig);
   const anchorLines = dynamicLines.filter((line) => (
     line.startsWith('- Recent routed lane:')
     || line.startsWith('- Current approach:')
@@ -153,7 +178,8 @@ async function main() {
       tokensBefore: compactedBody.tokensBefore,
       tokensAfter: compactedBody.tokensAfter,
       savedTokens: compactedBody.savedTokens,
-    }, config);
+      sessionId: sessionConfig.sessionId,
+    }, sessionConfig);
   }
 
   const compactSource = thresholdPlan.active

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

@@ -54,9 +54,90 @@ export async function readJson(filePath, fallback = null) {
   }
 }
 
-async function writeJson(filePath, value) {
+export async function writeJson(filePath, value) {
+  // tmp + rename: parallel hook processes must never observe a half-written state file.
   await fs.mkdir(path.dirname(filePath), { recursive: true });
-  await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  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);
+  } catch (error) {
+    try {
+      await fs.rm(tempPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+    throw error;
+  }
+}
+
+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));
+}
+
+/**
+ * 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.
+ * A crashed holder is reclaimed once the directory's mtime exceeds staleMs.
+ * 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), so CLI processes and hook processes serialize against each other.
+ * @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
+ */
+export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxWaitMs = LOCK_MAX_WAIT_MS } = {}) {
+  const lockPath = `${filePath}.lock`;
+  const startedAt = Date.now();
+  let locked = 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;
+      break;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+
+    // Someone holds the lock. Reclaim it when it looks abandoned; otherwise back off.
+    try {
+      const stat = await fs.stat(lockPath);
+      if (Date.now() - stat.mtimeMs > staleMs) {
+        await fs.rm(lockPath, { recursive: true, force: true });
+        continue; // the slot is free now — retry immediately
+      }
+    } catch {
+      continue; // lock vanished between mkdir and stat — retry immediately
+    }
+
+    if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
+    await sleep(lockBackoffDelayMs());
+  }
+
+  try {
+    return await fn();
+  } finally {
+    if (locked) {
+      try {
+        await fs.rm(lockPath, { recursive: true, force: true });
+      } catch {
+        // best-effort release; a stale lock is reclaimed by the next waiter
+      }
+    }
+  }
 }
 
 export function buildCompactMachineKey(prefix, payload = {}) {