@ngockhoale/ukit 2.3.5 → 2.3.7

package/CHANGELOG.md

@@ -2,6 +2,68 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.7 - 2026-09-10
+
+Bug-sweep wave 3: a data-loss escape in uninstall, cross-process races on shared runtime
+state, one flaky test, and one vulnerable runtime dependency — all found by verified
+reproducers and fixed with regression coverage.
+
+**P0 — uninstall could delete files outside the project root.** Tracked-path ownership
+checks were purely lexical: with `.claude` (or any parent directory) symlinked to an
+external location, uninstall's recursive remove resolved through the symlink and deleted
+whatever it pointed at — e.g. a shared dotfiles directory. Uninstall now inspects every
+directory component between the project root and each tracked entry (the entry itself may
+still be a tracked symlink, which is unlinked, never followed); entries with a symlinked
+parent are refused, warned, and reported in a new `skippedSymlinkParents` field in both
+dry-run and real results.
+
+**P1 — concurrent state mutations silently lost updates.** `appendOutputHistory` and the
+compact-pressure writers (prompt, output, plan, and the plain state write) performed
+unsynchronized read-modify-write cycles on files under `.ukit/storage/cache/`. With
+parallel subagents firing hooks in separate processes, 30 concurrent updates left a single
+surviving output-history entry (of a 25 cap) and 17 of 510 accumulated sessionTokens —
+understating context pressure and delaying compaction. All mutations now run under
+`withFileLock`, a directory-lock protocol beside each state file (atomic `mkdir`, stale
+reclaim after 10s, fail-open after 5s so a stuck lock can never freeze a hook). The lock
+ships in both `src/core/fileOps.js` and the runtime mirror `token-utils.mjs` using the
+same `<file>.lock` path, so CLI processes and hook processes serialize against each
+other; mirror state writes also became atomic (tmp + rename). An interop test runs both
+implementations against one project root to keep the protocols locked together.
+
+**Flaky test** — the `--no-outline` index-tools test queued a `getFileOutline` once-mock
+its own flag guaranteed would never be consumed; `vi.clearAllMocks()` drains no once-queues,
+so test order leaked the stale value into the next test (18/30 shuffled solo runs failed).
+The dead queue is gone; the full suite is now 3/3 green under `--sequence.shuffle`.
+
+**Dependency** — runtime dependency `yaml` 2.8.2 → 2.9.0 (GHSA-48c2-rrv3-qjmp, stack
+overflow via deeply nested YAML — UKit parses project-supplied manifests). Production
+dependency audit is now 0 findings.
+
+Full suite: 78 files, 1,359 tests green.
+
+## 2.3.6 - 2026-09-10
+
+Anti-stall coverage parity release: the compact-recovery and stop-reason directives that
+UKit hooks inject at runtime on Claude Code and omp now also reach harnesses that have no
+hook system at all.
+
+A new `## Long-Run Continuity` section ships in both `templates/CLAUDE.md` and
+`templates/AGENTS.md` (byte-identical, enforced by the per-section context-docs parity
+test). Codex and OpenCode load no hooks, so root `AGENTS.md` is their only instruction
+channel — before this release those sessions never saw the near-cap recovery order (LAND
+one thing → DEFER the rest to `docs/STATUS.md` → DELEGATE broad work to subagents → only
+then compact) or the post-compact discipline (no rereads of pre-compact context; if the
+first turn after a compact still sits at ≥60% of the cap, recover by delegating or starting
+fresh from disk state instead of burning the window again).
+
+The same session closed the long-running stall investigation with debug-log evidence: the
+observed "runs a while, then goes silent" behaviour is UNIC-gateway/network streaming
+latency (repeated 30s slow-first-byte, one 300s byte-idle abort), not UKit hooks —
+hook-error cache empty, exec ledgers healthy. When a dead stream ends a turn early, the
+existing ≥2.3.3 Stop-hook completion gate blocks the premature stop, so staying current
+(`ukit update`) plus restarting stale sessions (hook config loads at session start) is the
+full remediation available in-repo; gateway-side idle/failover fixes belong upstream.
+
 ## 2.3.5 - 2026-09-10
 
 Source-audit hardening release: the code index cannot corrupt itself, and a corrupt runtime

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.5",
+  "version": "2.3.7",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -65,7 +65,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "yaml": "^2.8.2"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "vitest": "^2"

package/src/core/compact/threshold.js

@@ -1,4 +1,4 @@
-import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import { buildCompactMachineKey, compressLine, estimateTokenCount } from '../token/index.js';
 import { compactContextBlock } from './index.js';
@@ -937,27 +937,37 @@ export async function readCompactPressureState(projectRoot, config = {}) {
   return buildCompactPressureState(await readJsonIfExists(runtimePaths.compactPressurePath), 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.
+async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const current = buildCompactPressureState(await readJsonIfExists(runtimePaths.compactPressurePath), config);
+    const next = mutator(current);
+    const normalized = buildCompactPressureState(next, config);
+    await writeJson(runtimePaths.compactPressurePath, normalized);
+    return normalized;
+  });
+}
+
 export async function writeCompactPressureState(projectRoot, state, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const normalized = buildCompactPressureState(state, config);
-  await writeJson(runtimePaths.compactPressurePath, normalized);
-  return normalized;
+  return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const normalized = buildCompactPressureState(state, config);
+    await writeJson(runtimePaths.compactPressurePath, normalized);
+    return normalized;
+  });
 }
 
 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), 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), 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), config);
 }

package/src/core/fileOps.js

@@ -131,6 +131,75 @@ export async function writeJson(filePath, data) {
   await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
 }
 
+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.
+ * Holders must keep their critical section far below staleMs; nothing refreshes
+ * the lock mtime, so a section that somehow runs longer can have its lock stolen.
+ * @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 ensureDir(path.dirname(lockPath));
+      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
+      }
+    }
+  }
+}
+
 /**
  * Create a directory symlink (macOS/Linux) or junction (Windows).
  * Junctions on Windows don't require elevated privileges.

package/src/core/output/index.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { readJsonIfExists, writeJson } from '../fileOps.js';
+import { readJsonIfExists, writeJson, withFileLock } from '../fileOps.js';
 import { recordCompaction } from '../compact/index.js';
 import { buildRuntimePaths } from '../runtimePaths.js';
 import {
@@ -1075,16 +1075,21 @@ export async function appendOutputHistory(projectRoot, entry, options = {}) {
   }
 
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const history = await readOutputHistory(projectRoot, options);
-  const normalizedKey = buildOutputHistoryDedupeKey(normalizedEntry);
-  const dedupedExistingEntries = history.entries.filter((candidate) => !(
-    buildOutputHistoryDedupeKey(candidate) === normalizedKey
-  ));
-  const nextDocument = normalizeOutputHistoryDocument({
-    entries: [normalizedEntry, ...dedupedExistingEntries],
-  }, options);
-  await writeJson(runtimePaths.outputHistoryPath, nextDocument);
-  return nextDocument;
+  // 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 history = await readOutputHistory(projectRoot, options);
+    const normalizedKey = buildOutputHistoryDedupeKey(normalizedEntry);
+    const dedupedExistingEntries = history.entries.filter((candidate) => !(
+      buildOutputHistoryDedupeKey(candidate) === normalizedKey
+    ));
+    const nextDocument = normalizeOutputHistoryDocument({
+      entries: [normalizedEntry, ...dedupedExistingEntries],
+    }, options);
+    await writeJson(runtimePaths.outputHistoryPath, nextDocument);
+    return nextDocument;
+  });
 }
 
 export function summarizeOutputHistory(rawHistory) {

package/src/core/uninstall.js

@@ -64,6 +64,37 @@ function isSameOrDescendantProjectPath(candidatePath, parentPath) {
   return candidatePath === parentPath || candidatePath.startsWith(`${parentPath}/`);
 }
 
+// A tracked path is only safe to delete when every directory between the project root
+// and the entry itself is a real directory. The prefix allowlist above is purely
+// lexical: if `.claude` (or any parent) is a symlink to somewhere outside the project,
+// `fs.rm(recursive)` resolves THROUGH it and would delete whatever it points at —
+// e.g. a shared dotfiles directory linked in as .claude. The entry itself may be a
+// symlink (tracked links are unlinked, never followed); only its parents matter.
+async function hasSymlinkedParent(projectRoot, absolutePath) {
+  const root = path.resolve(projectRoot);
+  const relative = path.relative(root, path.resolve(absolutePath));
+  if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+    // Outside the project root entirely — nothing here is safe to delete.
+    return true;
+  }
+  const segments = relative.split(path.sep);
+  segments.pop(); // the entry itself is allowed to be a symlink (removeLinkOnly unlinks it)
+  let current = root;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    let stat;
+    try {
+      stat = await fs.lstat(current);
+    } catch {
+      return false; // missing parent — nothing to resolve through
+    }
+    if (stat.isSymbolicLink()) {
+      return true;
+    }
+  }
+  return false;
+}
+
 // Hardcoded fallback for installs that predate file tracking (no 'files' field
 // in install.json). New installs always have a 'files' list, so this fallback
 // only applies when upgrading from a very old UKit version.
@@ -205,18 +236,36 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     ...linkPaths.map((abs) => ({ abs, useLink: true })),
   ];
 
+  // Never delete through a symlinked parent — see hasSymlinkedParent. Skipped entries
+  // are reported (dryRun and real run alike) so the user sees exactly what was refused.
+  const skippedSymlinkParents = [];
+  const safeEntries = [];
+  for (const entry of allEntries) {
+    if (await hasSymlinkedParent(projectRoot, entry.abs)) {
+      skippedSymlinkParents.push(entry.abs);
+    } else {
+      safeEntries.push(entry);
+    }
+  }
+  if (skippedSymlinkParents.length > 0) {
+    console.warn(
+      '[UKit] Refusing to remove paths whose parent directories are symlinks (deleting them would escape the project root):',
+      skippedSymlinkParents,
+    );
+  }
+
   if (dryRun) {
     // Use lstat (not access) so broken symlinks are included in the report.
     const wouldRemove = [];
-    for (const { abs } of allEntries) {
+    for (const { abs } of safeEntries) {
       if (await pathExistsLstat(abs)) wouldRemove.push(abs);
     }
-    return { removed: 0, attempted: allEntries.length, wasInstalled: true, wouldRemove };
+    return { removed: 0, attempted: allEntries.length, wasInstalled: true, wouldRemove, skippedSymlinkParents };
   }
 
   // Remove all paths in parallel
   const results = await Promise.all(
-    allEntries.map(({ abs, useLink }) => {
+    safeEntries.map(({ abs, useLink }) => {
       const remove = useLink ? removeLinkOnly : removeLinkOrDir;
       return remove(abs).then((didRemove) => ({ abs, didRemove }));
     }),
@@ -240,5 +289,5 @@ export async function uninstallUkit({ projectRoot, dryRun = false }) {
     await cleanupEmptyParents(removedPath, projectRoot);
   }
 
-  return { removed, attempted: allEntries.length, wasInstalled: true };
+  return { removed, attempted: allEntries.length, wasInstalled: true, skippedSymlinkParents };
 }

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;
@@ -1051,30 +1053,39 @@ 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.
+async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
+  const runtimePaths = buildRuntimePaths(projectRoot);
+  return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const current = buildCompactPressureState(await readJson(runtimePaths.compactPressurePath, null), config);
+    const next = mutator(current);
+    const normalized = buildCompactPressureState(next, config);
+    await writeJson(runtimePaths.compactPressurePath, normalized);
+    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 normalized = buildCompactPressureState(state, config);
+    await writeJson(runtimePaths.compactPressurePath, normalized);
+    return normalized;
+  });
 }
 
 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), 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), 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), config);
 }
 
 async function loadRuntimeConfig(projectRoot) {

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) {

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 = {}) {

package/templates/AGENTS.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context:

package/templates/CLAUDE.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context: