@ngockhoale/ukit 2.7.8 → 2.7.9

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+
+## 2.7.9 - 2026-09-22
+
+- **User permission mode is never overwritten**: `ukit install`/`ukit update`
+  used to rewrite `.claude/settings.json` wholesale, so the template's
+  `permissions.defaultMode: "bypassPermissions"` silently clobbered a
+  user-chosen mode (e.g. `plan`) on every install. `defaultMode` is now
+  user-owned in `merge_env_overwrite_with_backup`: excluded from the drift
+  comparison and merged back into the written content. The template default
+  still applies on fresh installs or when the user never set a mode.
+  (`src/core/diffPlan.js`, +4 tests in `tests/core/diffPlan.test.js`)
+
 ## 2.7.8 - 2026-09-22
 
 Stall/hang fixes — cycle C43 (TASK-001..008): the indefinite-stall producers

package/package.json

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

package/src/core/diffPlan.js

@@ -34,6 +34,54 @@ async function checkLinkStatus(targetPath, linkTarget) {
 // template, so a template-side change to e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW still triggers
 // a real reinstall. Without this carve-out, the managed gateway keys written by the post-apply
 // step would cause a spurious "update" on every subsequent install.
+//
+// `permissions.defaultMode` is user-owned: the user picks their permission mode
+// (bypassPermissions / plan / acceptEdits / default) and UKit must never change it.
+// It is excluded from the drift comparison AND re-injected into the rendered content
+// before write (mergeSettingsJson), so an install/update can never flip the user's mode.
+// When the user has NOT set it, the template's shipped default applies on create/update.
+const USER_OWNED_PERMISSION_KEYS = new Set(['defaultMode']);
+
+function parseSettingsJson(content) {
+  if (typeof content !== 'string') return null;
+  try {
+    const parsed = JSON.parse(content);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Strip user-owned permission keys from a parsed permissions object for comparison.
+// Returns a new object; never mutates the input.
+function stripUserOwnedPermissionKeys(permissions) {
+  if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
+    return permissions;
+  }
+  const stripped = { ...permissions };
+  for (const key of USER_OWNED_PERMISSION_KEYS) delete stripped[key];
+  return stripped;
+}
+
+// Merge rendered settings.json with the user's existing file: the rendered template
+// wins every key EXCEPT user-owned permission keys (currently permissions.defaultMode),
+// which keep the value the user set. Returns the merged JSON as a string, or the
+// rendered content unchanged when either side is unparseable.
+export function mergeSettingsJson(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return renderedContent;
+  const merged = { ...rendered };
+  if (existing.permissions && typeof existing.permissions === 'object' && !Array.isArray(existing.permissions)) {
+    const mergedPermissions = { ...(rendered.permissions && typeof rendered.permissions === 'object' ? rendered.permissions : {}) };
+    for (const key of USER_OWNED_PERMISSION_KEYS) {
+      if (key in existing.permissions) mergedPermissions[key] = existing.permissions[key];
+    }
+    merged.permissions = mergedPermissions;
+  }
+  return `${JSON.stringify(merged, null, 2)}\n`;
+}
+
 function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
   if (typeof existingContent !== 'string' || typeof renderedContent !== 'string') {
     return false;
@@ -56,7 +104,13 @@ function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
   for (const key of Object.keys(parsedRendered)) {
     if (key === 'env') continue;
     if (!(key in parsedExisting)) return false;
-    if (JSON.stringify(parsedExisting[key]) !== JSON.stringify(parsedRendered[key])) {
+    const renderedValue = key === 'permissions'
+      ? stripUserOwnedPermissionKeys(parsedRendered[key])
+      : parsedRendered[key];
+    const existingValue = key === 'permissions'
+      ? stripUserOwnedPermissionKeys(parsedExisting[key])
+      : parsedExisting[key];
+    if (JSON.stringify(existingValue) !== JSON.stringify(renderedValue)) {
       return false;
     }
   }
@@ -128,7 +182,12 @@ function resolveFileAction(entry, existingContent) {
     // Settings.json: ignore UKit-managed gateway resilience env keys (post-apply written
     // and may carry user overrides). All other top-level keys — and the rest of the env
     // block — must still match the template, so genuine template updates still reinstall.
+    // User-owned permission keys (permissions.defaultMode) are excluded from the drift
+    // check AND merged back into the content that gets written, so install/update can
+    // never flip the user's chosen permission mode.
+    const merged = mergeSettingsJson(existingContent, entry.renderedContent);
     action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
+    return { ...entry, renderedContent: merged, exists, action, existingContent };
   } else if (existingContent === entry.renderedContent) {
     action = 'unchanged';
   } else if (entry.mergeStrategy === 'skip') {

package/src/core/fileOps.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 // The shipped runtime carries the single lock implementation; src and the
 // installed package always ship templates/ together (package.json files list),
 // so the protocol twin delegates instead of keeping a driftable copy.
-import { journalDroppedLockMutation, withAsyncLock } from '../../templates/.claude/ukit/runtime/async-lock.mjs';
+import { journalDroppedLockMutation, withAsyncLock, withTransientFsRetry } from '../../templates/.claude/ukit/runtime/async-lock.mjs';
 
 export async function pathExists(targetPath) {
   try {
@@ -103,21 +103,25 @@ export async function writeFileAtomic(filePath, content) {
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
   try {
+    // C44: temp write, rename, and the EXDEV copy+rm fallback each retry
+    // transient kernel errors (EAGAIN/EBUSY/EMFILE/ENFILE/ESTALE) — the same
+    // transient-open EAGAIN observed on external APFS volumes under metadata
+    // churn. Non-transient codes (EXDEV, EISDIR) throw immediately, unchanged.
     if (Buffer.isBuffer(content)) {
-      await fs.writeFile(tempPath, content);
+      await withTransientFsRetry(() => fs.writeFile(tempPath, content));
     } else {
-      await fs.writeFile(tempPath, content, 'utf8');
+      await withTransientFsRetry(() => fs.writeFile(tempPath, content, 'utf8'));
     }
     try {
-      await fs.rename(tempPath, filePath);
+      await withTransientFsRetry(() => 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 });
+      await withTransientFsRetry(() => fs.copyFile(tempPath, filePath));
+      await withTransientFsRetry(() => fs.rm(tempPath, { force: true }));
     }
   } catch (error) {
     try {

package/templates/.claude/commands/ukit/handoff-clear.md

@@ -42,6 +42,11 @@ Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archivi
 ```
 If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
 
+After writing the archive file, **verify the write** — read it back and confirm
+the `ABORTED` heading is present; on mismatch or read failure retry once, on
+second failure stop and report (same rule as handoff-fullstack's "State-file
+write verification").
+
 ## Step 4 — Reset state files
 
 ```
@@ -54,6 +59,12 @@ RUN.md   → set `Phase: done` (or delete) — a live cursor that is neither `do
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
 ```
 
+Every file rewritten above is a state file — **verify the write** on each:
+read it back and confirm the marker you just wrote (empty INDEX header,
+`_(no active cycle)_`, `Phase: done`). On mismatch or read failure retry the
+write once; on second failure STOP and report — never leave unverified state
+files behind, or the next cycle resumes from stale bytes.
+
 ## Step 5 — Report
 
 ```

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -75,6 +75,23 @@ QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 This file is the resume contract. It costs one small write per step and is what turns an
 interrupted run into a continuable one.
 
+### State-file write verification — "verify the write"
+
+Every Write/Edit to a handoff state file — `INDEX.md`, `ACTIVE.md`, `RUN.md`,
+`SPEC.md`, `PLAN.md`, `tasks/TASK-*.md` — can be silently lost to a transient
+filesystem error (the Write tool's own `open()` has been observed to fail with
+EAGAIN while the write is reported as done). After each such write:
+
+1. **Read it back** and confirm the marker you just wrote is present — the
+   `Status:` row, `Phase:`/`Cursor:` line, or section heading the write was
+   supposed to change.
+2. **On mismatch or read failure, retry the write once.**
+3. **On second failure, STOP the pipeline** and report the file plus the error —
+   never continue on unverified state. A stale `INDEX.md`/`RUN.md` is how a run
+   ships silent corruption.
+
+Wherever a step below says **verify the write**, it means this rule.
+
 ### Resume — when the run is re-invoked mid-flight
 
 If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done` or `blocked`, this is a
@@ -240,6 +257,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`. Every
    unfinished item from the Phase 0 sweep is either a row here or superseded by a
    `-R<n>` recovery row.
+   Then **verify the write** (read back the new rows).
 
 7. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
    ```
@@ -249,6 +267,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
+   Then **verify the write** (read back the `Status:` line).
 
 8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
    `needs_breakdown` tasks + reason.
@@ -444,6 +463,7 @@ already on disk (task files hold the full logs, git holds the code). Do all four
 
 2. **Update the run cursor** — rewrite `docs/AI_HANDOFF/RUN.md` with `Phase: I3`,
    `Cursor: wave <N> done`, `Next: wave <N+1>` (or `I4` if that was the last wave).
+   Then **verify the write** (read back the `Phase:`/`Cursor:` lines).
 
 3. **Collapse the wave in working memory.** From this point on, refer to the finished wave
    only by its one-line-per-task summary (`TASK-xxx PASS <files>`). Do not re-read the task
@@ -469,6 +489,7 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
    - PASS tasks → `pending_review`
    - FAIL tasks → `blocked`
    - EXECUTOR_MODEL missing → `needs_executor_report`
+   Then **verify the write** (read back the updated status column).
 
 2. Verify cleanup:
    ```bash
@@ -647,6 +668,8 @@ conventions so a future session needs no transcript to understand the cycle:
    summary in `HISTORY.md` and remove it.
 3. Reset `ACTIVE.md` to its empty template; clear `INDEX.md` rows to a fresh header;
    remove `tasks/TASK-*.md`; clear `PLAN.md`/`SPEC.md` (templates stay).
+   Then **verify the write** on each reset file (read back the empty header /
+   template marker).
 4. Commit the docs + archive changes:
    `git add -A && git commit -m "handoff: finalize + archive cycle <ID>"`
 
@@ -654,6 +677,8 @@ conventions so a future session needs no transcript to understand the cycle:
 
 Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed at the
 start, and emit the Final Report below.
+   Then **verify the write** (read back `Phase: done`) — a lost cursor write
+   leaves the next session resuming a finished run.
 
 ---
 

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;

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

@@ -94,6 +94,58 @@ function sleepWithAbort(ms, signal) {
   });
 }
 
+// Transient kernel-level fs failures worth a bounded retry (C44): observed on
+// external APFS volumes under metadata churn — `open()`/`mkdir()`/`rename()`
+// can return EAGAIN once and succeed on immediate retry. EEXIST is deliberately
+// absent: it is the lock-contend signal, not a flake.
+export const TRANSIENT_FS_CODES = new Set(['EAGAIN', 'EBUSY', 'EMFILE', 'ENFILE', 'ESTALE']);
+
+/**
+ * Retry an fs operation that can surface a transient kernel error
+ * (TRANSIENT_FS_CODES) with jittered exponential backoff. Non-transient codes
+ * throw immediately — EEXIST contention and EISDIR mapping are unaffected.
+ * The LAST error rethrows on retry exhaustion, deadline, or abort: a retry
+ * never extends the caller past `deadlineMs` and never swallows the failure.
+ * @param {() => Promise<*>} op
+ * @param {{
+ *   retries?: number,
+ *   baseDelayMs?: number,
+ *   maxDelayMs?: number,
+ *   deadlineMs?: number,
+ *   signal?: AbortSignal,
+ * }} [options]
+ * @returns {Promise<*>} op's resolved value
+ */
+export async function withTransientFsRetry(op, {
+  retries = 3,
+  baseDelayMs = 15,
+  maxDelayMs = 150,
+  deadlineMs = Infinity,
+  signal,
+} = {}) {
+  const startedAt = Date.now();
+  const maxAttempts = Number.isFinite(retries) && retries >= 0 ? Math.floor(retries) + 1 : 1;
+  let lastError = null;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    if (signal?.aborted) {
+      throw lastError ?? signal.reason ?? new Error('withTransientFsRetry aborted');
+    }
+    try {
+      return await op();
+    } catch (error) {
+      lastError = error;
+      if (!TRANSIENT_FS_CODES.has(error?.code) || attempt + 1 >= maxAttempts) throw error;
+      const remaining = deadlineMs - (Date.now() - startedAt);
+      if (remaining <= 0) throw error;
+      const backoff = Math.min(baseDelayMs * (2 ** attempt), maxDelayMs);
+      const waitMs = Math.min(backoff * (0.5 + Math.random()), remaining);
+      const sleptFully = await sleepWithAbort(Math.max(0, waitMs), signal);
+      if (!sleptFully || Date.now() - startedAt >= deadlineMs) throw error;
+    }
+  }
+  throw lastError;
+}
+
 function isPidAlive(pid) {
   try {
     process.kill(pid, 0);
@@ -153,9 +205,9 @@ function recordedProcessGone(owner) {
   return Math.abs(actual - stamped) > PID_START_TOLERANCE_MS;
 }
 
-async function readLockOwner(lockPath) {
+async function readLockOwner(lockPath, retry = withTransientFsRetry) {
   try {
-    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
+    const raw = JSON.parse(await retry(() => fs.readFile(path.join(lockPath, 'owner'), 'utf8')));
     const pid = Number(raw?.pid);
     const pstart = Number(raw?.pstart);
     return Number.isInteger(pid) && pid > 0
@@ -177,9 +229,9 @@ function sameLockOwner(left, right) {
   return left.pid === right.pid && left.token === right.token;
 }
 
-async function readReclaimOwner(lockPath) {
+async function readReclaimOwner(lockPath, retry = withTransientFsRetry) {
   try {
-    const raw = JSON.parse(await fs.readFile(path.join(lockPath, RECLAIM_FILE), 'utf8'));
+    const raw = JSON.parse(await retry(() => fs.readFile(path.join(lockPath, RECLAIM_FILE), 'utf8')));
     const pid = Number(raw?.pid);
     const pstart = Number(raw?.pstart);
     return Number.isInteger(pid) && pid > 0
@@ -194,19 +246,20 @@ async function readReclaimOwner(lockPath) {
   }
 }
 
+
 // Stale observers must claim the existing lock before removing it. The claim lives
 // inside the old generation, so a second observer cannot remove that generation while
 // the first observer is between its owner check and rm(). This closes the TOCTOU race
 // where a delayed stale observer deleted a freshly acquired successor lock.
-async function claimReclaim(lockPath, ownerToken, staleMs) {
+async function claimReclaim(lockPath, ownerToken, staleMs, retry = withTransientFsRetry) {
   const reclaimPath = path.join(lockPath, RECLAIM_FILE);
   try {
-    const handle = await fs.open(reclaimPath, 'wx');
+    const handle = await retry(() => fs.open(reclaimPath, 'wx'));
     try {
-      await handle.writeFile(
+      await retry(() => handle.writeFile(
         `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now(), pstart: PROCESS_START_MS })}\n`,
         'utf8',
-      );
+      ));
     } finally {
       await handle.close();
     }
@@ -217,11 +270,11 @@ async function claimReclaim(lockPath, ownerToken, staleMs) {
     // A killed reclaimer can leave its claim behind. Only clear an old claim whose
     // recorded process is gone; a live claim remains the exclusive reclaim authority.
     try {
-      const stat = await fs.stat(reclaimPath);
+      const stat = await retry(() => fs.stat(reclaimPath));
       if (Date.now() - stat.mtimeMs > staleMs) {
-        const claim = await readReclaimOwner(lockPath);
+        const claim = await readReclaimOwner(lockPath, retry);
         if (!claim || recordedProcessGone(claim)) {
-          await fs.rm(reclaimPath, { force: true });
+          await retry(() => fs.rm(reclaimPath, { force: true }));
         }
       }
     } catch {
@@ -231,38 +284,38 @@ async function claimReclaim(lockPath, ownerToken, staleMs) {
   }
 }
 
-async function releaseReclaimClaim(lockPath, ownerToken) {
+async function releaseReclaimClaim(lockPath, ownerToken, retry = withTransientFsRetry) {
   try {
-    const claim = await readReclaimOwner(lockPath);
+    const claim = await readReclaimOwner(lockPath, retry);
     if (claim?.token === ownerToken) {
-      await fs.rm(path.join(lockPath, RECLAIM_FILE), { force: true });
+      await retry(() => fs.rm(path.join(lockPath, RECLAIM_FILE), { force: true }));
     }
   } catch {
     // best-effort claim release; the stale-claim path handles an interrupted cleanup
   }
 }
 
-async function quarantineReclaim(lockPath, owner, ownerToken) {
+async function quarantineReclaim(lockPath, owner, ownerToken, retry = withTransientFsRetry) {
   const quarantinePath = `${lockPath}.reclaim-${ownerToken}`;
   try {
     // The claim serializes stale observers. Re-read before the atomic rename so an
     // observer never detaches a generation different from the one it validated.
-    const current = await readLockOwner(lockPath);
+    const current = await readLockOwner(lockPath, retry);
     if (!sameLockOwner(current, owner)) {
-      await releaseReclaimClaim(lockPath, ownerToken);
+      await releaseReclaimClaim(lockPath, ownerToken, retry);
       return false;
     }
     // Rename is atomic within the lock's parent directory: the old generation is
     // detached as one filesystem operation, so a successor created at lockPath can
     // never be reached by cleanup of this quarantined generation.
-    await fs.rename(lockPath, quarantinePath);
-    await fs.rm(quarantinePath, { recursive: true, force: true });
+    await retry(() => fs.rename(lockPath, quarantinePath));
+    await retry(() => fs.rm(quarantinePath, { recursive: true, force: true }));
     return true;
   } catch {
     // Never recursively remove lockPath here. If rename lost a race or failed, the
     // original path belongs to whoever currently holds it; a later poll can retry.
     try {
-      await fs.rm(quarantinePath, { recursive: true, force: true });
+      await retry(() => fs.rm(quarantinePath, { recursive: true, force: true }));
     } catch {
       // best-effort cleanup of only this acquisition's quarantine path
     }
@@ -356,20 +409,31 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
   // True only when THIS acquisition holds a lock it can prove it owns: the atomic
   // mkdir succeeded AND the owner stamp is on disk. Release is verified against it.
   let owned = false;
+  // C44: every lock-protocol fs op retries transient kernel errors (EAGAIN et
+  // al.) inside the caller's remaining acquisition budget — a kernel flake must
+  // never escape as an untyped throw while budget remains, and a retry must
+  // never extend the wait past it.
+  const retry = (op) => withTransientFsRetry(op, {
+    deadlineMs: Math.max(0, budget - (Date.now() - startedAt)),
+    signal,
+  });
+  // Post-acquisition ops (release, claim cleanup) run after the budget is spent;
+  // they get the fixed cleanup reserve instead of the acquisition slice.
+  const releaseRetry = (op) => withTransientFsRetry(op, { deadlineMs: LOCK_RESERVE_MS });
 
   while (true) {
     try {
       // The lock parent must exist before the atomic acquire — a first-ever run in a
       // fresh project would otherwise fail mkdir with ENOENT.
-      await fs.mkdir(path.dirname(lockPath), { recursive: true });
-      await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
+      await retry(() => fs.mkdir(path.dirname(lockPath), { recursive: true }));
+      await retry(() => fs.mkdir(lockPath)); // atomic acquire — EEXIST means another holder exists
       inProcessLockHolders.set(lockPath, ownerToken);
       try {
-        await fs.writeFile(
+        await retry(() => fs.writeFile(
           path.join(lockPath, 'owner'),
           `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now(), pstart: PROCESS_START_MS })}\n`,
           'utf8',
-        );
+        ));
       } catch {
         // Fail closed: an unstamped lock is not ours to enter. Running the callback
         // anyway would leave an ownerless directory, and every other process reads a
@@ -377,11 +441,11 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
         // lock mid-critical-section and letting two mutations interleave. Undo the
         // acquire and report the typed busy outcome callers already handle.
         try {
-          const current = await readLockOwner(lockPath);
+          const current = await readLockOwner(lockPath, retry);
           // Never remove a directory some other holder has since stamped (only
           // possible if this one was reclaimed in the window above).
           if (!current || current.token === ownerToken) {
-            await fs.rm(lockPath, { recursive: true, force: true });
+            await retry(() => fs.rm(lockPath, { recursive: true, force: true }));
           }
         } catch {
           // best-effort undo; a leftover dir is unheld and reclaimed by the next waiter
@@ -408,12 +472,12 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
     // (stamped pstart no longer matches the running process).
     let reclaimed = false;
     try {
-      const stat = await fs.stat(lockPath);
+      const stat = await retry(() => fs.stat(lockPath));
       const ageMs = Date.now() - stat.mtimeMs;
       const remainingMs = budget - (Date.now() - startedAt);
       const effectiveStaleMs = remainingMs > 0 ? Math.min(stale, remainingMs) : stale;
       if (ageMs > effectiveStaleMs) {
-        const owner = await readLockOwner(lockPath);
+        const owner = await readLockOwner(lockPath, retry);
         const liveInProcess = inProcessLockHolders.has(lockPath);
         // An ownerless lock may be a holder mid-stamp — only the FULL stale
         // threshold proves abandonment there. A stamped owner provably gone
@@ -424,11 +488,11 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
           : owner.pid === process.pid
             ? !liveInProcess
             : recordedProcessGone(owner);
-        if (reclaimable && await claimReclaim(lockPath, ownerToken, stale)) {
+        if (reclaimable && await claimReclaim(lockPath, ownerToken, stale, retry)) {
           // Detach and clean only the generation that was validated. The atomic rename
           // makes this safe even when another process acquires lockPath immediately
           // after the stale generation is removed.
-          reclaimed = await quarantineReclaim(lockPath, owner, ownerToken);
+          reclaimed = await quarantineReclaim(lockPath, owner, ownerToken, retry);
         }
       }
     } catch {
@@ -461,9 +525,9 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
         // 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 = await readLockOwner(lockPath);
+        const current = await readLockOwner(lockPath, releaseRetry);
         if (current && current.token === ownerToken) {
-          await fs.rm(lockPath, { recursive: true, force: true });
+          await releaseRetry(() => fs.rm(lockPath, { recursive: true, force: true }));
         }
       } catch {
         // best-effort release; a leaked dir is reclaimed by the next waiter

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

@@ -42,6 +42,7 @@ function inlineReference(payloadText, bytes) {
     path: null,
     bytes,
     cleanup() { /* nothing was staged — O(1) by construction */ },
+    async cleanupAsync() { /* nothing was staged — O(1) by construction */ },
   };
 }
 
@@ -125,8 +126,15 @@ export async function createPayloadReferenceAsync(text, {
       text: payloadText,
       path: finalPath,
       bytes,
+      // TASK-002 (OMP-4): the bridge request path awaits cleanupAsync(); the
+      // sync-named cleanup() is kept for tests/CLI but must not run a blocking
+      // fs call on the omp host loop either — it delegates to the same async
+      // removal fire-and-forget.
       cleanup() {
-        try { fs.rmSync(finalPath, { force: true }); } catch { /* best effort */ }
+        fsp.rm(finalPath, { force: true }).catch(() => { /* best effort */ });
+      },
+      async cleanupAsync() {
+        try { await fsp.rm(finalPath, { force: true }); } catch { /* best effort */ }
       },
     };
   })();
@@ -163,6 +171,72 @@ export function probePayloadIntegrity(reference) {
   }
 }
 
+// probePayloadIntegrityAsync(reference) -> Promise<null | 'missing' | 'partial'>
+//
+// TASK-002 (OMP-4): async twin of probePayloadIntegrity. The sync variant's
+// statSync runs on the CALLER's event loop — on the omp host a stalled mount
+// freezes the whole app (the socket-closed bug class). Identical verdicts.
+export async function probePayloadIntegrityAsync(reference) {
+  if (!reference || reference.mode !== 'file' || !reference.path) return null;
+  try {
+    const stats = await fsp.stat(reference.path);
+    return stats.size === reference.bytes ? null : 'partial';
+  } catch {
+    return 'missing';
+  }
+}
+
+// sweepStalePayloadsAsync(dir, {now, maxAgeMs, maxEntries}) ->
+//   Promise<{sampled, scanned, removed}>
+//
+// TASK-002 (OMP-4): async twin of sweepStalePayloads — same bounded semantics
+// through fs.promises so the omp host loop never blocks on directory work.
+export async function sweepStalePayloadsAsync(dir, {
+  now = Date.now,
+  maxAgeMs = SWEEP_MAX_AGE_MS,
+  maxEntries = SWEEP_MAX_ENTRIES,
+} = {}) {
+  let names;
+  try {
+    names = await fsp.readdir(dir);
+  } catch {
+    return { sampled: true, scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  let scanned = 0;
+  let removed = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
+    const filePath = path.join(dir, name);
+    try {
+      if ((await fsp.stat(filePath)).mtimeMs < cutoff) {
+        await fsp.rm(filePath, { force: true });
+        removed += 1;
+      }
+    } catch { /* raced away — fine */ }
+  }
+  return { sampled: true, scanned, removed };
+}
+
+// maybeSweepStalePayloadsAsync(dir, {probability, random, ...}) ->
+//   Promise<sweep report>
+//
+// TASK-002 (OMP-4): async twin of maybeSweepStalePayloads — identical sampled
+// gate, delegating to sweepStalePayloadsAsync.
+export async function maybeSweepStalePayloadsAsync(dir, {
+  probability,
+  random = Math.random,
+  now,
+  maxAgeMs,
+  maxEntries,
+} = {}) {
+  const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
+  if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
+  return sweepStalePayloadsAsync(dir, { now, maxAgeMs, maxEntries });
+}
+
 // sweepStalePayloads(dir, {now, maxAgeMs, maxEntries}) -> {sampled, scanned, removed}
 //
 // Bounded: processes at most maxEntries directory entries regardless of how many

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

@@ -20,8 +20,8 @@ import {
 import {
   PAYLOAD_INLINE_MAX_BYTES,
   createPayloadReferenceAsync,
-  maybeSweepStalePayloads,
-  probePayloadIntegrity,
+  maybeSweepStalePayloadsAsync,
+  probePayloadIntegrityAsync,
 } from '../../../.claude/ukit/runtime/hook-payload-store.mjs';
 // TASK-018 review fix round 1: the chain budget is resolved by ONE shared module,
 // so the runner's inner deadline and this bridge's outer pi.exec timeout can never
@@ -146,6 +146,17 @@ function classifyFailure(scriptName) {
 // closed (the .sh thin wrapper is still invocable as a fallback path).
 const TIMEOUT_STAYS_CLOSED = new Set(['block-dangerous.sh', 'block-dangerous.mjs']);
 
+// TASK-002 (OMP-4): a hook crash or transport failure whose stderr is a
+// transient filesystem error (EAGAIN/EBUSY/EMFILE/ENFILE/ESTALE — the
+// stalled-external-mount class) produced NO verdict, so it must degrade to a
+// loud "could not verify" warning instead of a block showing raw errno text.
+// The match is deliberately conservative: the errno code must appear in an
+// fs-syscall context (open/read/write/mkdir/stat/rename/unlink/rm), in either
+// order, or the Node "resource temporarily unavailable" phrasing — a genuine
+// block reason containing e.g. "again" in prose never downgrades. ONE pattern
+// shared by translateExecResult and runScriptChain.
+const TRANSIENT_INFRA_STDERR_RE = /\bresource temporarily unavailable\b|\b(?:EAGAIN|EBUSY|EMFILE|ENFILE|ESTALE)\b[\s\S]*?\b(?:open|read|write|mkdir|stat|rename|unlink|rm)\b|\b(?:open|read|write|mkdir|stat|rename|unlink|rm)\b[\s\S]*?\b(?:EAGAIN|EBUSY|EMFILE|ENFILE|ESTALE)\b/i;
+
 // TASK-018: the hook-chain-runner's failure taxonomy. Infrastructure outcomes
 // (overflow / timeout / signal / budget-exhausted) produced NO verdict, so their
 // captured output is untrustworthy and never reaches the model context, a block
@@ -337,6 +348,18 @@ function translateExecResult(scriptName, execResult) {
     }
     return { block: true, reason: stderr || `${scriptName} exited 2 (blocked)`, stdout, stderr };
   }
+  // TASK-002 (OMP-4): a crash whose stderr is a transient fs error produced no
+  // verdict — it is an infrastructure event, not a safety decision. Fail open
+  // loudly instead of blocking on raw errno text. TIMEOUT_STAYS_CLOSED scripts
+  // (block-dangerous .sh/.mjs) keep their never-fail-open contract.
+  if (TRANSIENT_INFRA_STDERR_RE.test(stderr) && !TIMEOUT_STAYS_CLOSED.has(scriptName)) {
+    return {
+      block: false,
+      warning: `${scriptName} exited ${code} with a transient filesystem error — treated as "could not verify", not as a block (an infrastructure event, not a verdict): ${redactDiagnosticText(stderr) || 'no stderr'}`,
+      stdout,
+      stderr,
+    };
+  }
   if (classifyFailure(scriptName) === 'closed') {
     return {
       block: true,
@@ -380,17 +403,18 @@ function hookErrorsDirFor(projectRoot) {
 }
 
 // Bounded work on THIS session's file only — identical keep-newest-half shape
-// as hook-telemetry's rotateIfNeeded.
-function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
+// as hook-telemetry's rotateIfNeeded. TASK-002 (OMP-4): async fs only — a
+// stalled mount must never freeze the omp host loop.
+async function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
   let size = 0;
   try {
-    size = fs.statSync(filePath).size;
+    size = (await fs.promises.stat(filePath)).size;
   } catch {
     return; // first row for this session
   }
   if (size + incomingBytes <= maxBytes) return;
   try {
-    const lines = fs.readFileSync(filePath, 'utf8').split('\n');
+    const lines = (await fs.promises.readFile(filePath, 'utf8')).split('\n');
     if (lines.length && lines[lines.length - 1] === '') lines.pop();
     const keepBudget = Math.floor(maxBytes / 2);
     const keep = [];
@@ -401,16 +425,17 @@ function rotateHookErrorFileIfNeeded(filePath, incomingBytes, maxBytes) {
       keep.unshift(lines[i]);
       kept += lineBytes;
     }
-    fs.writeFileSync(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
+    await fs.promises.writeFile(filePath, keep.length ? `${keep.join('\n')}\n` : '', 'utf8');
   } catch {
     // Rotation failed; drop this row rather than grow past the cap.
   }
 }
 
 // sweepHookErrorsDir(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
-//   { scanned, removed } — bounded: never scans or removes more than the caps,
-// so a pre-existing oversized dir is amortized down across sampled sweeps.
-function sweepHookErrorsDir(dir, {
+//   Promise<{ scanned, removed }> — bounded: never scans or removes more than
+// the caps, so a pre-existing oversized dir is amortized down across sampled
+// sweeps. TASK-002 (OMP-4): async fs only — host loop must never block.
+async function sweepHookErrorsDir(dir, {
   now = Date.now,
   maxAgeMs = HOOK_ERROR_MAX_AGE_MS,
   maxFiles = HOOK_ERROR_MAX_FILES,
@@ -419,7 +444,7 @@ function sweepHookErrorsDir(dir, {
 } = {}) {
   let names;
   try {
-    names = fs.readdirSync(dir);
+    names = await fs.promises.readdir(dir);
   } catch {
     return { scanned: 0, removed: 0 };
   }
@@ -435,7 +460,7 @@ function sweepHookErrorsDir(dir, {
     if (scanned >= maxEntries) break;
     scanned += 1;
     try {
-      const stats = fs.statSync(path.join(dir, name));
+      const stats = await fs.promises.stat(path.join(dir, name));
       if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
     } catch { /* raced away — fine */ }
   }
@@ -449,7 +474,7 @@ function sweepHookErrorsDir(dir, {
     if (removed >= maxRemovals) break;
     if (removed < overflow || entry.mtimeMs < cutoff) {
       try {
-        fs.rmSync(path.join(dir, entry.name), { force: true });
+        await fs.promises.rm(path.join(dir, entry.name), { force: true });
         removed += 1;
       } catch { /* raced away — fine */ }
     }
@@ -463,18 +488,18 @@ function hookErrorsSweepProbabilityFromEnv() {
   return Math.min(1, Math.max(0, raw));
 }
 
-function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic, { maxBytes = HOOK_ERROR_MAX_BYTES } = {}) {
+async function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic, { maxBytes = HOOK_ERROR_MAX_BYTES } = {}) {
   try {
     const dir = hookErrorsDirFor(projectRoot);
-    fs.mkdirSync(dir, { recursive: true });
+    await fs.promises.mkdir(dir, { recursive: true });
     const safeSession = String(sessionId || 'unknown').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 96) || 'unknown';
     const filePath = path.join(dir, `${safeSession}.jsonl`);
     const line = `${JSON.stringify(diagnostic)}\n`;
-    rotateHookErrorFileIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), maxBytes);
-    fs.appendFileSync(filePath, line, 'utf8');
+    await rotateHookErrorFileIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), maxBytes);
+    await fs.promises.appendFile(filePath, line, 'utf8');
     // Sampled bounded dir sweep — amortizes down any pre-existing oversized dir.
     if (Math.random() < hookErrorsSweepProbabilityFromEnv()) {
-      sweepHookErrorsDir(dir);
+      await sweepHookErrorsDir(dir);
     }
   } catch {
     // Diagnostics are advisory and must never block or throw.
@@ -519,11 +544,11 @@ function payloadsDirFor(projectRoot) {
 }
 
 function schedulePayloadSweep(projectRoot) {
-  // Deferred: runs after the current turn settles, never inside the chain request.
+  // Deferred: runs after the current turn settles, never inside the chain
+  // request. Async fs only — a stalled mount must not freeze the host loop.
   const timer = setTimeout(() => {
-    try {
-      maybeSweepStalePayloads(payloadsDirFor(projectRoot));
-    } catch { /* deferred sweeping is best effort */ }
+    maybeSweepStalePayloadsAsync(payloadsDirFor(projectRoot))
+      .catch(() => { /* deferred sweeping is best effort */ });
   }, 0);
   timer.unref?.();
 }
@@ -563,8 +588,8 @@ export async function runScriptChain(
     // TASK-031: verify the staged payload survived the chain intact BEFORE removing it —
     // a file that vanished or was truncated mid-flight means the scripts ran against a
     // different payload than the host captured, so their verdicts are void.
-    payloadProbe = probePayloadIntegrity(payloadReference);
-    payloadReference.cleanup();
+    payloadProbe = await probePayloadIntegrityAsync(payloadReference);
+    await payloadReference.cleanupAsync();
     if (payloadReference.mode === 'file') schedulePayloadSweep(projectRoot);
   }
   const elapsedMs = Date.now() - startedAt;
@@ -609,7 +634,7 @@ export async function runScriptChain(
       parseError: parseError?.message || null,
       wrapperError: chainResult?.wrapperError || null,
     };
-    recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    await recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
     // TASK-031: a staged payload that was lost or corrupted mid-chain voids every
     // verdict below it. Chains that must not fail open on an unverifiable verdict
     // (Edit|Write transport policy, and block-dangerous's never-fail-open rule)
@@ -640,6 +665,15 @@ export async function runScriptChain(
         + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
         + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
         + `See .ukit/storage/cache/hook-errors/.${nodePathHint}`;
+    // TASK-002 (OMP-4): a transport failure whose stderr is a transient fs
+    // error produced no verdict — an infrastructure event, not a safety
+    // decision. Even on a fail-closed chain it degrades to a loud warning
+    // instead of a block showing raw errno text. A staged-payload integrity
+    // failure (payloadProbe !== null) already returned above and stays closed.
+    if (failClosedOnTransportError && TRANSIENT_INFRA_STDERR_RE.test(diagnostic.stderrExcerpt)) {
+      pi.logger?.warn?.(`[UKit] ${reason} Transient filesystem error — treated as "could not verify", not as a block.`);
+      return { block: false, context, invoked };
+    }
     if (failClosedOnTransportError) {
       return { block: true, reason, context, invoked };
     }