@ngockhoale/ukit 2.7.6 → 2.7.8

package/templates/.claude/ukit/runtime/hook-payload-store.mjs

@@ -16,6 +16,7 @@
 // Readers (hook-chain-runner.mjs) keep accepting the `@path` argv form unchanged.
 
 import fs from 'node:fs';
+import fsp from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
 
@@ -90,6 +91,62 @@ export function createPayloadReference(text, {
   }
 }
 
+// createPayloadReferenceAsync(text, {maxBytes, deadlineMs, dir}) -> Promise<reference>
+//
+// TASK-008 (SPEC §S8, OMP-6): the sync variant's mkdirSync/writeFileSync/renameSync
+// run deadline-free on the CALLER's event loop — on the omp host a stalled mount
+// freezes the whole app, and the deadlineMs check at t≈0 is decorative because a
+// stalled sync call never returns to re-check it. This variant does the same
+// atomic staging through async fs raced against a real deadline; on expiry or
+// any failure it degrades to inline transport exactly like the sync path.
+// The losing fs promise is left to settle in the background — it is unref'd by
+// the race and its result discarded; worst case it completes a tmp write that
+// the sampled sweep later reclaims.
+export async function createPayloadReferenceAsync(text, {
+  maxBytes = PAYLOAD_INLINE_MAX_BYTES,
+  deadlineMs = 250,
+  dir,
+} = {}) {
+  const payloadText = String(text ?? '');
+  const bytes = Buffer.byteLength(payloadText, 'utf8');
+  if (bytes <= maxBytes) return inlineReference(payloadText, bytes);
+  if (!(deadlineMs > 0) || !dir) return inlineReference(payloadText, bytes);
+
+  const stage = (async () => {
+    await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+    const name = `${Date.now().toString(36)}-${process.pid}-${crypto.randomBytes(6).toString('hex')}.json`;
+    const finalPath = path.join(dir, name);
+    const tmpPath = path.join(dir, `.${name}.tmp`);
+    await fsp.writeFile(tmpPath, payloadText, { encoding: 'utf8', mode: 0o600 });
+    await fsp.rename(tmpPath, finalPath);
+    return {
+      mode: 'file',
+      arg: `@${finalPath}`,
+      text: payloadText,
+      path: finalPath,
+      bytes,
+      cleanup() {
+        try { fs.rmSync(finalPath, { force: true }); } catch { /* best effort */ }
+      },
+    };
+  })();
+  // Fail-open contract (TASK-008 fix): the race must resolve to inline on ANY
+  // staging outcome that is not a completed file — deadline expiry AND fs
+  // rejection (ENOTDIR/EACCES/EROFS on a read-only or wedged mount). Racing the
+  // raw stage promise let a fast rejection propagate through runScriptChain and
+  // skip the whole hook chain; .catch(() => null) consumes it so the winner is
+  // always a reference or null. The same catch also swallows a rejection that
+  // lands after the deadline already won, so no unhandled rejection escapes.
+  let timer;
+  const deadline = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), deadlineMs);
+    timer.unref?.();
+  });
+  const winner = await Promise.race([stage.catch(() => null), deadline]);
+  clearTimeout(timer);
+  return winner ?? inlineReference(payloadText, bytes);
+}
+
 // probePayloadIntegrity(reference) -> null | 'missing' | 'partial'
 //
 // O(1): one stat of the file this bridge staged. Called by the bridge after the

package/templates/.claude/ukit/runtime/hook-telemetry.mjs

@@ -69,7 +69,13 @@ function normalizeElapsedMs(value) {
 // Allowlist builder — the ONLY place row fields are chosen. `elapsedMs` may be
 // null when the caller genuinely could not measure it (e.g. the hook exited
 // before its stdin envelope was staged); unknown stays unknown, never zero.
+//
+// O3 (SPEC §FR-009): `stageMs` splits that elapsed window into the part the hook
+// spent waiting on stdin staging and the part it spent executing. It is OPTIONAL
+// — omitted entirely when unmeasurable — so a v1 reader's key set is unchanged
+// for a row that has no stage data, and `TELEMETRY_VERSION` stays 1.
 export function buildTimingRow(entry = {}) {
+  const stageMs = normalizeElapsedMs(entry.stageMs);
   return {
     v: TELEMETRY_VERSION,
     ts: Number.isFinite(entry.ts) ? entry.ts : Date.now(),
@@ -79,6 +85,7 @@ export function buildTimingRow(entry = {}) {
     hook: shortString(entry.hook, 128),
     elapsedMs: normalizeElapsedMs(entry.elapsedMs),
     outcome: shortString(entry.outcome, 32) || 'ok',
+    ...(stageMs === null ? {} : { stageMs }),
   };
 }
 
@@ -242,13 +249,14 @@ export function recordHookTiming({
   tool,
   hook,
   elapsedMs,
+  stageMs,
   outcome,
   toolUseId,
   ts,
   projectRoot,
   maxBytes,
 } = {}) {
-  const row = buildTimingRow({ ts, event, tool, toolUseId, hook, elapsedMs, outcome });
+  const row = buildTimingRow({ ts, event, tool, toolUseId, hook, elapsedMs, outcome, stageMs });
   const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
   return appendTelemetryRow(root, sessionId, row, { maxBytes });
 }
@@ -256,6 +264,13 @@ export function recordHookTiming({
 // --- `--finish` CLI: one short-lived node process per direct hook exit ------
 // Invoked by ukit_hook_telemetry_finish (hook-telemetry.sh) from the shared
 // cleanup path in hook-input.sh, while the staged payload file still exists.
+//
+// O1 (TASK-008): the same CLI serves hooks that deliberately never stage stdin
+// (gate-first fast paths). Those have no payload mtime to measure from, so the
+// arm helper hands over an explicit start plus the envelope's identifying
+// fields: UKIT_TEL_START_MS (epoch ms), UKIT_TEL_SESSION_ID, UKIT_TEL_EVENT.
+// Every override is optional and falsy-safe, so the 18 staging hooks that set
+// none of them keep byte-for-byte today's behaviour.
 
 const FINISH_PARSE_LIMIT = 2 * 1024 * 1024; // all hooks except record-execution stage <= 2 MiB
 const FINISH_HEAD_BYTES = 256 * 1024; // bounded head scan for oversized payloads
@@ -318,32 +333,89 @@ function readEnvelope(inputFile) {
   }
 }
 
+// Explicit arm start. Non-finite, zero, or negative values are ignored: a
+// malformed marker must degrade to the staged-payload mtime (or to the honest
+// null), never to a bogus "0ms" measurement.
+function explicitStartMs(raw) {
+  const parsed = Number.parseInt(String(raw ?? ''), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return null;
+  return parsed;
+}
+
+// Start reference, most explicit first: the arm helper's epoch-ms reading, the
+// arm marker's mtime (the shell could not express sub-second precision on this
+// host), then the staged payload's mtime. None present stays null — an armed
+// hook that lost its marker must not be reported as a zero-millisecond hook.
+//
+// O3 (SPEC §FR-009) needs the two ends SEPARATELY, not just their difference:
+// when the payload's own mtime is the start, `elapsedMs` already begins where
+// staging ended, so `source` is what tells the stage split that no window is
+// left to measure.
+function resolveStartRef() {
+  const explicit = explicitStartMs(process.env.UKIT_TEL_START_MS);
+  if (explicit !== null) return { startMs: explicit, source: 'explicit' };
+  const marker = process.env.UKIT_TEL_START_FILE || '';
+  if (marker) {
+    try {
+      return { startMs: fs.statSync(marker).mtimeMs, source: 'marker' };
+    } catch {
+      // Marker already reaped — fall through to the staged payload.
+    }
+  }
+  const inputFile = process.env.UKIT_INPUT_FILE || '';
+  if (!inputFile) return { startMs: null, source: null };
+  try {
+    return { startMs: fs.statSync(inputFile).mtimeMs, source: 'payload' };
+  } catch {
+    return { startMs: null, source: null }; // never staged (refuse path) — unknown, not zero
+  }
+}
+
+// O3 (SPEC §FR-009): the stage window = the staged payload's mtime minus the arm
+// start, and only the two ARM sources qualify. A hook that deliberately skips
+// stdin staging (gate-first fast paths, SPEC §14) has no payload at all, and an
+// unarmed hook's start IS the payload mtime — reporting a stage from either
+// would invent a window that never existed, so unmeasurable stays ABSENT.
+// Clamped to the row's own elapsed window: the split attributes time inside that
+// whole, it never exceeds it.
+function resolveStageMs(startRef, elapsedMs) {
+  if (startRef.source !== 'explicit' && startRef.source !== 'marker') return null;
+  const inputFile = process.env.UKIT_INPUT_FILE || '';
+  if (!inputFile) return null;
+  let stagedAt;
+  try {
+    stagedAt = fs.statSync(inputFile).mtimeMs;
+  } catch {
+    return null;
+  }
+  const raw = stagedAt - startRef.startMs;
+  if (!Number.isFinite(raw) || raw < 0) return null;
+  return Math.min(raw, normalizeElapsedMs(elapsedMs) ?? raw);
+}
+
 function finishMain() {
   try {
     // process.uptime() covers this spawn itself so the row measures the hook,
     // not the telemetry process startup.
     const spawnOverheadMs = process.uptime() * 1000;
     const inputFile = process.env.UKIT_INPUT_FILE || '';
-    let startMs = null;
-    if (inputFile) {
-      try {
-        startMs = fs.statSync(inputFile).mtimeMs;
-      } catch {
-        startMs = null; // envelope never staged (refuse path) — unknown, not zero
-      }
-    }
+    const startRef = resolveStartRef();
+    const elapsedMs = startRef.startMs === null
+      ? null
+      : Date.now() - startRef.startMs - spawnOverheadMs;
     const envelope = inputFile ? readEnvelope(inputFile) : {};
     const rc = Number.parseInt(process.env.UKIT_TEL_RC ?? '', 10);
     // The wrapper resolves PROJECT_ROOT before arming; fall back to the hook
     // env's CLAUDE_PROJECT_DIR, then cwd (same resolution as the wrappers).
     recordHookTiming({
       projectRoot: process.env.PROJECT_ROOT || process.env.CLAUDE_PROJECT_DIR || undefined,
-      sessionId: envelope.session_id,
-      event: envelope.hook_event_name,
+      sessionId: process.env.UKIT_TEL_SESSION_ID || envelope.session_id,
+      event: process.env.UKIT_TEL_EVENT || envelope.hook_event_name,
       tool: envelope.tool_name,
       toolUseId: envelope.tool_use_id,
       hook: process.env.UKIT_TEL_HOOK,
-      elapsedMs: startMs === null ? null : Date.now() - startMs - spawnOverheadMs,
+      elapsedMs,
+      stageMs: resolveStageMs(startRef, elapsedMs),
       // Direct rows reuse the chain taxonomy (TASK-018): a non-zero exit is a
       // verdict ('exit-code'), not a guess. Timeout/overflow kills bypass the
       // EXIT trap, so those kinds stay chain-runner-reported.

package/templates/.claude/ukit/runtime/hook-telemetry.sh

@@ -11,12 +11,54 @@
 # payload. Finish spawns at most one bounded node process, discards all output,
 # and never changes the hook's exit status or verdict.
 #
+# O1 (TASK-008): hooks that never stage stdin (the gate-first fast paths wired
+# in TASK-009) have no payload mtime to measure from. They call
+# ukit_hook_telemetry_arm instead, which creates the same kind of start marker
+# without adding a node spawn to the hot path — and trap
+# ukit_hook_telemetry_finish on EXIT themselves.
+#
 # Missing runtime (pre-install tree) simply leaves telemetry off: wrappers
 # source this file with `|| true` and the armed flag stays unset.
 
 UKIT_TEL_ARMED=1
 UKIT_TEL_HOOK="$(basename "${BASH_SOURCE[1]:-$0}")"
 UKIT_TEL_RUNTIME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+UKIT_TEL_START_FILE=""
+UKIT_TEL_START_MS=""
+
+# Epoch milliseconds from a file's mtime, or empty when this host's stat cannot
+# express sub-second precision. GNU coreutils is probed first: it rejects the
+# BSD format string outright, while BSD stat would read a GNU format string as
+# a list of directives and print something plausible-but-wrong.
+ukit_tel_file_ms() {
+  local raw seconds frac
+  raw="$(/usr/bin/stat -c '%.3Y' "$1" 2>/dev/null)" || raw=""
+  case "$raw" in
+    ''|*[!0-9.]*) raw="$(/usr/bin/stat -f '%Fm' "$1" 2>/dev/null)" || raw="" ;;
+  esac
+  case "$raw" in
+    *.*) seconds="${raw%%.*}"; frac="${raw#*.}" ;;
+    *) seconds="$raw"; frac="" ;;
+  esac
+  # Unknown stays unknown: an unparseable mtime yields empty, never a bogus 0.
+  case "$seconds" in
+    ''|*[!0-9]*) return 0 ;;
+  esac
+  frac="${frac}000"
+  printf '%s' "$(( seconds * 1000 + 10#${frac:0:3} ))"
+}
+
+# No-staging arm path. A marker file whose mtime is the start reference costs
+# one mktemp; a `node -e` clock read would cost ~30ms to measure milliseconds.
+# Always returns 0 — an unarmed hook must behave exactly like an unmeasured one.
+ukit_hook_telemetry_arm() {
+  UKIT_TEL_START_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-tel-start.XXXXXX" 2>/dev/null)" || {
+    UKIT_TEL_START_FILE=""
+    return 0
+  }
+  UKIT_TEL_START_MS="$(ukit_tel_file_ms "$UKIT_TEL_START_FILE")"
+  return 0
+}
 
 ukit_hook_telemetry_finish() {
   # The hook's exit status arrives via UKIT_TEL_RC (ukit_cleanup_hook_input
@@ -44,6 +86,8 @@ ukit_hook_telemetry_finish() {
 
   UKIT_TEL_RC="$rc" \
   UKIT_TEL_HOOK="$UKIT_TEL_HOOK" \
+  UKIT_TEL_START_MS="${UKIT_TEL_START_MS:-}" \
+  UKIT_TEL_START_FILE="${UKIT_TEL_START_FILE:-}" \
   UKIT_INPUT_FILE="${UKIT_INPUT_FILE:-}" \
   PROJECT_ROOT="${PROJECT_ROOT:-${CLAUDE_PROJECT_DIR:-}}" \
     node "$UKIT_TEL_RUNTIME_DIR/hook-telemetry.mjs" --finish </dev/null >/dev/null 2>&1 &
@@ -56,5 +100,11 @@ ukit_hook_telemetry_finish() {
   if wait "$child" 2>/dev/null; then :; fi
   kill "$watchdog" 2>/dev/null || true
   if wait "$watchdog" 2>/dev/null; then :; fi
+  # The marker existed only to be stat'd by the child above; dropping it here
+  # keeps a long session from accumulating one temp file per hooked event.
+  if [ -n "${UKIT_TEL_START_FILE:-}" ]; then
+    rm -f "$UKIT_TEL_START_FILE" 2>/dev/null || true
+    UKIT_TEL_START_FILE=""
+  fi
   return 0
 }

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

@@ -168,7 +168,7 @@ export const DEDUPE_WINDOW_MS = 2000;
 // Fixed budget slices inside the default 3000ms hook deadline: the ledger child
 // gets the larger slice, each watchdog lock acquisition gets a short one.
 const LEDGER_BUDGET_MS = 1500;
-const LOCK_BUDGET_MS = 600;
+export const LOCK_BUDGET_MS = 600;
 
 const WATCHDOG_PROVENANCE_PREFIX = '[ukit-stop-coordinator] task-watchdog also requested a block: ';
 const WATCHDOG_FAILURE_PREFIX = '[ukit-stop-coordinator] task-watchdog evaluator failed (advisory lane, reported verbatim): ';
@@ -453,28 +453,43 @@ function parseRunCursor(text) {
 /**
  * Mutate `.ukit/storage/cache/stop-coordinator/state.json`'s `handoff` slot:
  * { signature, count }. Same signature as last time → count+1; a moved cursor
- * resets the streak. Returns the committed streak count; a lock-timeout or any
- * I/O failure returns null (fail-open — never decides the stop).
+ * resets the streak. Returns the committed streak count.
+ *
+ * RC-4: a lock-busy acquisition used to return null, and the release branch
+ * required `streak !== null` — so a leaked state lock froze the
+ * stopGateMaxStalledBlocks breaker forever and the handoff-cursor lane became an
+ * unbounded bounce loop. The breaker must ALWAYS advance: on lock-busy (or any
+ * lock error) the same read-modify-write runs best-effort unlocked. A lost tick
+ * under a racing writer only delays the cap by one stop; a frozen breaker loops
+ * forever. Only a genuinely unwritable state file still returns null.
  */
 async function bumpHandoffStallCount({ projectRoot, signature, lockBudgetMs }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
+  const bump = async () => {
+    let current = {};
+    try {
+      current = JSON.parse(await fs.readFile(statePath, 'utf8')) || {};
+    } catch {}
+    const prev = current.handoff || {};
+    const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
+    await fs.mkdir(path.dirname(statePath), { recursive: true });
+    await fs.writeFile(
+      statePath,
+      `${JSON.stringify({ ...current, handoff: { signature, count } }, null, 1)}\n`,
+      'utf8',
+    );
+    return count;
+  };
   try {
-    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {
-      let current = {};
-      try {
-        current = JSON.parse(await fs.readFile(statePath, 'utf8')) || {};
-      } catch {}
-      const prev = current.handoff || {};
-      const count = prev.signature === signature ? (Number(prev.count) || 0) + 1 : 1;
-      await fs.mkdir(path.dirname(statePath), { recursive: true });
-      await fs.writeFile(
-        statePath,
-        `${JSON.stringify({ ...current, handoff: { signature, count } }, null, 1)}\n`,
-        'utf8',
-      );
-      return count;
-    });
-    return outcome.ok ? outcome.value : null;
+    const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, bump);
+    if (outcome.ok) return outcome.value;
+  } catch {
+    // fall through to the best-effort tick below
+  }
+  try {
+    // Lock-busy: count the stop as a stall tick anyway so the liveness breaker
+    // keeps advancing behind a wedged or leaked lock.
+    return await bump();
   } catch {
     return null;
   }
@@ -547,7 +562,7 @@ export async function evaluateHandoffCursor({ projectRoot, now = Date.now(), loc
  * invocation is a same-session duplicate inside the window. Fail-open — an
  * unreadable/unlockable dedupe state must never disable the Stop coordinator.
  */
-async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs }) {
+export async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupeWindowMs, lockBudgetMs }) {
   const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'stop-coordinator', 'state.json');
   try {
     const outcome = await withAsyncLock(statePath, { deadlineMs: lockBudgetMs }, async () => {

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: