@ngockhoale/ukit 3.0.10 → 3.0.11

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to UKit are documented here.
 
+## 3.0.11 - 2026-09-26
+
+- **C80 bug-sweep fix cycle — all 23 confirmed/high-confidence execution-path bugs fixed** (`docs/AI_HANDOFF/REPORT-C80-bug-sweep.md`):
+  - Index CLIs (`query-index`, `triage`, `resolve-context`, `verify-context`, `impact-context`, `route-task`): top-level try/catch error boundary — unhandled-rejection crashes become clean exit(1) (C80-01..06).
+  - `cache-utils.mjs` `readRecentCacheEntry(touch:true)`: touch-write failures degrade to in-memory entry, matching the token-utils prompt-cache contract — a full/unwritable cache can no longer reject a read (C80-02).
+  - `index-core.mjs`: new `ensureIndexFresh` — cross-process `withFileLock` build lock + staleness re-check inside the lock; artifact caches invalidated before publish writes, not after (C80-07/08).
+  - `frontend-vue` composables: `useRequest` ×3 `finally` decrement of `loading_count` (stuck spinner); `useWebSocket` retry dedup + cancellable timer + disposed guard; `useSession.getSession` corrupt-blob guard; `indexDBStore` promises now settle on transaction/clear errors (C80-09..16).
+  - Skill scripts: `with_server.py` pipe deadlock + process-group kill; `init-project-docs.sh` sed escaping + backup-instead-of-rm; `document.py` deterministic `close()`; `rearrange.py` samefile compare; `find-polluter.sh` glob/quoting fixes (C80-17..22).
+  - `supervisor.js`: listeners attach before awaited work post-spawn; liveness via injectable `probeImpl` (kill(pid,0)); `killGroup` revalidates ownership before signaling a possibly-recycled pgid (C80-23).
+
 ## 3.0.10 - 2026-09-25
 
 - Re-publish of the 3.0.9 content: npm staged-publish left 3.0.9 in limbo (E409 "previously staged version"); re-published as 3.0.10 — same tree, version bump only.

package/bin/ukit

@@ -4,6 +4,7 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runCli } from '../src/cli/index.js';
+import { resolveCliDeadlineMs } from '../src/cli/deadline.js';
 
 async function readPackageVersion(packageRoot) {
   const packageJsonPath = path.join(packageRoot, 'package.json');
@@ -15,19 +16,14 @@ async function readPackageVersion(packageRoot) {
   }
 }
 
-const DEFAULT_CLI_DEADLINE_MS = 120_000;
-
-function resolveCliDeadlineMs() {
-  const raw = Number(process.env.UKIT_CLI_DEADLINE_MS);
-  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CLI_DEADLINE_MS;
-}
-
 async function main() {
   // Overall wall-clock watchdog: individual fs/readline awaits inside runCli are
   // unbounded, so a wedged .ukit/external mount would park the CLI forever.
-  const deadlineMs = resolveCliDeadlineMs();
+  const argv = process.argv.slice(2);
+  const deadlineMs = resolveCliDeadlineMs(argv);
+  const commandLabel = argv.length > 0 ? argv.join(' ') : 'install';
   const watchdog = setTimeout(() => {
-    console.error(`[UKit] timed out after ${deadlineMs}ms — likely wedged filesystem; retry`);
+    console.error(`[UKit] 'ukit ${commandLabel}' timed out after ${deadlineMs}ms — likely wedged filesystem or slow network; retry`);
     process.exit(1);
   }, deadlineMs);
   // NOT unref'd: a hung runCli that holds no event-loop handles (e.g. a promise

package/package.json

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

package/scripts/bench/memory-baseline.mjs

@@ -520,7 +520,7 @@ async function main() {
   };
 
   try {
-    report.meta.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+    report.meta.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8', timeout: 10_000 }).trim();
   } catch { /* leave 'unknown' */ }
   try {
     report.meta.version = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version ?? 'unknown';

package/scripts/bench/memory-bench.mjs

@@ -253,7 +253,7 @@ function envBlock() {
     os: process.platform, arch: process.arch, fs: 'local',
   };
   try {
-    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8', timeout: 10_000 }).trim();
   } catch { /* leave 'unknown' */ }
   try {
     env.package = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version ?? 'unknown';

package/scripts/bench/memory-canary.mjs

@@ -91,8 +91,18 @@ function ensureCorpus(opts, workRoot) {
   const dir = path.join(workRoot, 'corpus');
   const args = [CORPUS_GEN, '--tier', opts.tier, '--out', dir];
   if (opts.seed != null) args.push('--seed', String(opts.seed));
-  const res = spawnSync(process.execPath, args, { encoding: 'utf8' });
-  if (res.status !== 0) throw new Error(`corpus generation failed: ${res.stderr || res.stdout}`);
+  // The corpus child gets an explicit lifetime bound (FR-022): a hung
+  // generator must never park the canary forever. killSignal SIGKILL, not the
+  // default SIGTERM — see src/core/update.js:18-24: a signal-ignoring child
+  // keeps spawnSync waiting past the timeout under SIGTERM; SIGKILL returns
+  // ~immediately. UKIT_CANARY_CORPUS_TIMEOUT_MS lets tests shrink the bound.
+  const corpusTimeoutMs = Number(process.env.UKIT_CANARY_CORPUS_TIMEOUT_MS) || 120_000;
+  const res = spawnSync(process.execPath, args, {
+    encoding: 'utf8', timeout: corpusTimeoutMs, killSignal: 'SIGKILL',
+  });
+  if (res.status !== 0 || res.error) {
+    throw new Error(`corpus generation failed: ${res.error?.message ?? res.stderr ?? res.stdout ?? 'unknown error'}`);
+  }
   return {
     recordsPath: path.join(dir, 'records.json'),
     manifest: JSON.parse(fs.readFileSync(path.join(dir, 'manifest.json'), 'utf8')),

package/scripts/bench/recorder-overhead.mjs

@@ -77,7 +77,7 @@ function dirBytes(dir) {
 
 function gitRevision() {
   try {
-    return execSync('git rev-parse --short HEAD', { cwd: repoRoot, encoding: 'utf8' }).trim();
+    return execSync('git rev-parse --short HEAD', { cwd: repoRoot, encoding: 'utf8', timeout: 10_000 }).trim();
   } catch {
     return 'unknown';
   }

package/scripts/bench/sqlite-spike.mjs

@@ -391,7 +391,7 @@ async function main() {
     walDir,
   };
   try {
-    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+    env.sha = execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8', timeout: 10_000 }).trim();
   } catch { /* leave 'unknown' */ }
   try {
     env.package = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8')).version ?? 'unknown';

package/scripts/measure-decision-gateway.mjs

@@ -165,7 +165,7 @@ export function writeMeasurementArtifacts(artifact, outDir) {
 
 function gitSha() {
   try {
-    return execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8' }).trim();
+    return execSync('git rev-parse HEAD', { cwd: REPO_ROOT, encoding: 'utf8', timeout: 10_000 }).trim();
   } catch {
     return null;
   }

package/src/cli/commands/memory.js

@@ -195,6 +195,9 @@ async function runMemoryV2(projectRoot, args) {
             type: 'project_rule',
             scope: 'repo',
             provenance: `${record.provenance ?? 'manual'};promoted-from:${record.id}`,
+            // FR-018: episodes carry a ~90d valid_until — a promoted rule must
+            // not inherit it or it silently expires from recall.
+            valid_until: null,
           },
         },
         expectedRevision: record.revision,

package/src/cli/deadline.js

@@ -0,0 +1,19 @@
+// C79-07: per-subcommand CLI watchdog budgets. `ukit update` shells out to
+// `npm install -g` whose own budget (NPM_INSTALL_TIMEOUT_MS in
+// src/core/update.js) is 10 minutes — killing the CLI at the flat 120s used to
+// fire mid-install, printing a false "wedged filesystem" diagnostic and
+// orphaning the npm child. `update` therefore gets a deadline aligned with
+// that budget; every other command keeps 120s. The constant is duplicated
+// inline (mirrored value) instead of importing update.js so this module stays
+// dependency-free — audit fixtures lift bin/ukit into stub package roots that
+// carry only src/cli/*.
+
+export const DEFAULT_CLI_DEADLINE_MS = 120_000;
+export const UPDATE_CLI_DEADLINE_MS = 10 * 60 * 1000; // mirrors NPM_INSTALL_TIMEOUT_MS
+
+export function resolveCliDeadlineMs(argv = []) {
+  const raw = Number(process.env.UKIT_CLI_DEADLINE_MS);
+  if (Number.isFinite(raw) && raw > 0) return raw;
+  const command = (argv[0] ?? '').toLowerCase();
+  return command === 'update' ? UPDATE_CLI_DEADLINE_MS : DEFAULT_CLI_DEADLINE_MS;
+}

package/src/core/agentRuntime/eventStore.js

@@ -29,6 +29,8 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 
+import { withFileLock } from '../fileOps.js';
+
 import {
   CONTRACT_VERSION,
   validateSemanticEvent,
@@ -156,27 +158,53 @@ async function loadCursor(dir, operationId) {
 
 /**
  * Append a validated SemanticEvent to the operation journal. Envelope and
- * ordering are validated against contract.js; duplicate eventId/seq is an
- * idempotent no-op; a future seq rejects out_of_order. The line is fsync'd
+ * ordering are validated against contract.js; duplicate eventId is an
+ * idempotent no-op; a seq collision with a DIFFERENT eventId rejects
+ * out_of_order; a future seq rejects out_of_order. The line is fsync'd
  * before returning — once this resolves, the event survives a crash.
  *
+ * The loadCursor→appendLine pair runs under a per-journal `withFileLock`:
+ * without it two writers can both validate against the same cursor and
+ * commit two records at one seq, permanently corrupting the journal.
+ * Lock-wait expiry fails closed with `journal_lock_timeout` — the append is
+ * never run unlocked.
+ *
  * @param {string} dir store root
  * @param {object} event SemanticEvent (contract v1)
- * @param {object} [opts] `{ hooks: { afterAppend } }` — test fault injection
+ * @param {object} [opts] `{ hooks: { afterAppend }, lockStaleMs, lockMaxWaitMs }`
+ *   — hooks for test fault injection; lock knobs default to fileOps policy
  * @returns {Promise<{seq:number, duplicate?:boolean}>}
  */
 export async function appendEvent(dir, event, opts = {}) {
   const shape = validateSemanticEvent(event);
   if (!shape.ok) throw new EventStoreError(shape.code, shape.code);
 
-  const cursor = await loadCursor(dir, event.operationId);
-  const order = validateEventOrder(event, cursor);
-  if (!order.ok) throw new EventStoreError(order.code, order.code);
-  if (order.duplicate) return { seq: event.seq, duplicate: true };
+  const jPath = journalPath(dir, event.operationId);
+  const result = await withFileLock(jPath, async () => {
+    const cursor = await loadCursor(dir, event.operationId);
+    const order = validateEventOrder(event, cursor);
+    if (!order.ok) throw new EventStoreError(order.code, order.code);
+    if (order.duplicate) {
+      // contract.js pins `seq <= lastSeq` → duplicate for journal replay, but
+      // for appends a seq collision with an UNSEEN eventId is a conflicting
+      // write, not an idempotent re-delivery — reject it instead of letting
+      // a second writer believe its (uncommitted) event landed
+      if (!cursor.seenEventIds.has(event.eventId)) {
+        throw new EventStoreError('out_of_order', `seq ${event.seq} already committed`);
+      }
+      return { seq: event.seq, duplicate: true };
+    }
 
-  await appendLine(journalPath(dir, event.operationId), event);
-  await opts.hooks?.afterAppend?.(event);
-  return { seq: event.seq };
+    await appendLine(jPath, event);
+    return { seq: event.seq };
+  }, { staleMs: opts.lockStaleMs, maxWaitMs: opts.lockMaxWaitMs });
+  if (result === undefined) {
+    // withFileLock fail-closed: the wait expired and the append was skipped —
+    // surface it typed so callers never mistake a dropped write for success
+    throw new EventStoreError('journal_lock_timeout', event.operationId);
+  }
+  if (!result.duplicate) await opts.hooks?.afterAppend?.(event);
+  return result;
 }
 
 /**

package/src/core/agentRuntime/supervisor.js

@@ -63,6 +63,11 @@ const defaultFsyncImpl = async (handle) => {
 
 const defaultSpawnImpl = (argv, opts) => spawn(argv[0], argv.slice(1), opts);
 const defaultKillImpl = (signal, target) => process.kill(target, signal);
+// Liveness probe — separate injectable from killImpl so sig-0 checks never
+// count as kill calls (C80-23).
+const defaultProbeImpl = (pid) => {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+};
 
 function specIsValid(spec) {
   if (spec === null || typeof spec !== 'object') return false;
@@ -86,6 +91,7 @@ function specIsValid(spec) {
  * @param {number} [opts.ownerEpoch] epoch floor for transition validation
  * @param {object} [opts.limits] {pollIntervalMs,killGraceMs,closeWaitMs,artifact caps}
  * @param {Function} [opts.spawnImpl] (argv, spawnOpts) → child-like proc
+ * @param {Function} [opts.probeImpl] (pid) → boolean — liveness probe (kill(pid,0))
  * @param {Function} [opts.killImpl] (signal, target) → void (target = -pgid)
  * @param {Function} [opts.fsyncImpl] artifact fsync
  * @param {Function} [opts.appendEventImpl] journal append (test injection)
@@ -147,6 +153,7 @@ export function createSupervisor(opts = {}) {
 
   const spawnImpl = opts.spawnImpl ?? defaultSpawnImpl;
   const killImpl = opts.killImpl ?? defaultKillImpl;
+  const probeImpl = opts.probeImpl ?? defaultProbeImpl;
   const append = opts.appendEventImpl ?? appendEvent;
   const clock = opts.clock && typeof opts.clock.setTimeout === 'function'
     ? opts.clock
@@ -226,7 +233,21 @@ export function createSupervisor(opts = {}) {
     emitEvent(op, 'operation.observation', { class: cls });
   }
 
+  // C80-23: probe the real pid — liveness must come from the OS, not the
+  // exited flag (a missed 'exit' event used to look alive forever).
+  function procAlive(op) {
+    if (op.exited) return false;
+    const pid = op.proc?.pid ?? op.pgid;
+    if (pid == null) return false;
+    return probeImpl(pid) === true;
+  }
+
   function killGroup(op, signal) {
+    // Revalidate ownership: if we believe the child already exited, do not
+    // signal a possibly-recycled pgid we no longer own.
+    if (op.exited || signal === 0) {
+      return;
+    }
     try {
       killImpl(signal, -op.pgid);
     } catch {
@@ -272,8 +293,16 @@ export function createSupervisor(opts = {}) {
   function tick(op) {
     if (op.exited || isTerminal(op.state)) return;
     const now = nowMs();
+    const alive = procAlive(op);
+    if (!alive && !op.exited) {
+      // C80-23: the 'exit' event was missed (or libuv dropped it) but the OS
+      // says the pid is gone — resolve as exited so op state, timers, and any
+      // later killGroup() see the truth instead of wall-timing a dead child.
+      onExit(op, op.proc?.exitCode ?? 1, null);
+      return;
+    }
     const sample = {
-      processAlive: !op.exited,
+      processAlive: alive,
       bytesWritten: op.bytesWritten,
       lastOutputAt: op.lastOutputAt,
       startedAt: op.startedAt,
@@ -447,14 +476,9 @@ export function createSupervisor(opts = {}) {
       op.pgid = proc.pid;
       op.lastOutputAt = nowMs();
 
-      if (artifactWriter) {
-        try {
-          op.artifacts = artifactWriter.open(op.id);
-        } catch {
-          op.artifacts = null;
-        }
-      }
-
+      // C80-23: attach exit/error listeners BEFORE any other work — a fast-
+      // exiting child must never miss its terminal handler and leave
+      // op.exited false until the wall-timeout kill.
       const onData = (stream) => (chunk) => {
         op.bytesWritten += chunk?.length ?? 0;
         op.lastOutputAt = nowMs();
@@ -469,6 +493,14 @@ export function createSupervisor(opts = {}) {
       proc.on?.('error', () => onExit(op, proc.exitCode ?? 1, null));
       proc.on?.('exit', (code, signal) => onExit(op, code, signal));
 
+      if (artifactWriter) {
+        try {
+          op.artifacts = artifactWriter.open(op.id);
+        } catch {
+          op.artifacts = null;
+        }
+      }
+
       await transition(op, 'running', { pid: proc.pid ?? null });
       if (!op.exited) scheduleTick(op);
 

package/src/core/agentRuntime/vmEngine.js

@@ -116,7 +116,13 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
   }
 
   async function appendTransition(inst, nodeId, to, payload) {
-    const seq = ++inst.cursors[nodeId].lastSeq;
+    // seq allocation follows the JOURNAL cursor (journalSeq), not the
+    // deliver-check cursor: a rehydrated instance's deliver cursor is
+    // deliberately un-replayed, but transitions must number after the last
+    // committed journal record
+    const seq = (inst.journalSeq[nodeId] ?? inst.cursors[nodeId].lastSeq) + 1;
+    inst.journalSeq[nodeId] = seq;
+    inst.cursors[nodeId].lastSeq = Math.max(inst.cursors[nodeId].lastSeq, seq);
     const event = transitionRecord(nodeId, to, seq, { pi: inst.planInstanceId, payload });
     await appendEvent(dir, event, { hooks: { afterAppend: hooks?.afterEventAppend } });
     return event;
@@ -373,6 +379,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       entryNodes: plan.entryNodes,
       nodes: {},
       cursors: {},
+      journalSeq: {},
       continuations: {},
       recoveryReason: null,
       forcedStatus: null,
@@ -380,6 +387,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
     for (const [id] of nodes) {
       inst.nodes[id] = { state: 'queued', attempt: 0, lastEventSeq: 0 };
       inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
+      inst.journalSeq[id] = 0;
     }
     instances.set(planInstanceId, inst);
 
@@ -435,6 +443,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       entryNodes: raw.plan?.entryNodes ?? [],
       nodes: {},
       cursors: {},
+      journalSeq: {},
       continuations: {},
       recoveryReason: raw.recoveryReason ?? null,
       forcedStatus: null,
@@ -447,6 +456,17 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
         lastEventSeq: seed.lastEventSeq ?? 0,
       };
       inst.cursors[id] = { lastSeq: 0, seenEventIds: new Set() };
+      inst.journalSeq[id] = 0;
+    }
+    // Seed transition seq allocation from the journal tail (journal is truth):
+    // the deliver-check cursor stays memory-only — replaying it would break
+    // journaled-but-unconsumed redelivery — but appendTransition MUST continue
+    // numbering where the journal ended or every post-crash transition lands
+    // on an already-committed seq
+    for (const [id] of nodeMap) {
+      for await (const ev of readJournal(dir, opId(planInstanceId, id))) {
+        inst.journalSeq[id] = ev.seq;
+      }
     }
     // continuation registration survived the crash on disk — recover the ids
     try {
@@ -460,7 +480,13 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
           ? c.operationId.slice(planInstanceId.length + 1) : null;
         if (nid && inst.nodeMap.has(nid)) inst.continuations[nid] = c.continuationId;
       }
-    } catch { /* no continuations file — nothing registered yet */ }
+    } catch (err) {
+      // ENOENT == never registered — hydrate with zero continuations. Any
+      // other fs fault (EACCES/EMFILE/corrupt read) must surface: swallowing
+      // it would silently drop every durable registration and chain into the
+      // journal/consume divergence below
+      if (err?.code !== 'ENOENT') throw err;
+    }
     instances.set(planInstanceId, inst);
     return inst;
   }
@@ -503,6 +529,10 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
       }
     }
     if (!targetMatched) return escalateUnclassified(inst, event);
+    // routed-but-unregistered node: escalating BEFORE appendEvent keeps the
+    // journal honest — a journaled event whose continuation lookup then throws
+    // leaves disk claiming a delivery memory rejected (divergence on resume)
+    if (inst.continuations[nodeId] == null) return escalateUnclassified(inst, event);
 
     // journal the delivered event BEFORE consumption record: a crash between
     // the two leaves a journal event replay will re-apply idempotently;
@@ -515,6 +545,7 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
     }
     cursor.lastSeq = event.seq;
     cursor.seenEventIds.add(event.eventId);
+    inst.journalSeq[nodeId] = event.seq; // committed delivered event is also the journal tail
 
     const cont = await consumeContinuation(dir, inst.continuations[nodeId], event);
     if (!cont.consumed && cont.duplicate) {

package/src/core/codeintel/freshness.js

@@ -56,17 +56,21 @@ export function getBranchKey(rootDir) {
   return 'nogit';
 }
 
+// Porcelain v1 -z records are NUL-separated: `XY<space>path\0`. With
+// `-c core.quotePath=false` paths arrive as literal UTF-8 (no quoting, no
+// octal escapes, no `->` arrows). For rename/copy (R/C in XY) the NEXT NUL
+// field carries the ORIG path — the record's own path is already the new
+// path — so it is consumed without being emitted.
 function parsePorcelainPaths(output) {
   const paths = [];
-  for (const line of output.split('\n')) {
-    if (!line.trim()) continue;
-    let p = line.slice(3);
-    // rename entries: "old -> new" — track the new path
-    const arrow = p.indexOf(' -> ');
-    if (arrow !== -1) p = p.slice(arrow + 4);
-    p = p.trim();
-    if (p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);
+  const fields = output.split('\0');
+  for (let i = 0; i < fields.length; i++) {
+    const record = fields[i];
+    if (!record) continue;
+    const xy = record.slice(0, 2);
+    const p = record.slice(3);
     if (p) paths.push(p);
+    if (xy.includes('R') || xy.includes('C')) i++;
   }
   return paths;
 }
@@ -171,7 +175,7 @@ function hashEntries(entries) {
 async function computeOverlayEntries(rootDir, headSha, { incremental = true, snapshot } = {}) {
   const dirty = await readDirtySet(rootDir);
   if (headSha !== 'nogit') {
-    const status = runGit(rootDir, ['status', '--porcelain']);
+    const status = runGit(rootDir, ['-c', 'core.quotePath=false', 'status', '--porcelain', '-z']);
     if (status !== null) {
       // Git mode: porcelain output IS the diff — dirty.json unioned defensively.
       const extra = dirty && !dirty.saturated ? dirty.paths : [];

package/src/core/codeintel/retriever.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs/promises';
-import fsSync from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 
+import { withFileLock } from '../fileOps.js';
 import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from '../../index/paths.js';
 import { loadRuntimeConfig } from '../runtimeConfig.js';
 import { createEdge, getSemanticProvider, IndexFileSyntaxProvider } from './providers.js';
@@ -262,15 +262,18 @@ function concatMerge(lanes) {
   return merged;
 }
 
-// FR-202b (TASK-228): fire-and-forget lane telemetry. One JSONL line per
-// retrieval at .ukit/storage/cache/retriever-lanes.jsonl; query persisted as
-// sha256 only (no raw prompts on disk). Failures are swallowed — telemetry
-// must never break retrieve(). Sync writes keep the fire-and-forget contract
-// deterministic for callers/tests.
+// FR-202b (TASK-228): lane telemetry, awaited before retrieve() resolves so
+// the write is durable for callers/tests — failures still never propagate.
+// One JSONL line per retrieval at .ukit/storage/cache/retriever-lanes.jsonl;
+// query persisted as sha256 only (no raw prompts on disk).
+// C79-14 (TASK-011): stat→read→truncate→append used to run unlocked, so an
+// append landing between a sibling process's snapshot-read and its truncating
+// writeFile was silently destroyed. The mutation now runs under withFileLock;
+// an expired lock wait drops this event whole (journaled), never torn.
 const RETRIEVER_LANES_MAX_BYTES = 256 * 1024;
 const RETRIEVER_LANES_KEEP_LINES = 2000;
 
-function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, mergedPaths, merge, weights }) {
+async function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, mergedPaths, merge, weights }) {
   try {
     const laneStats = {};
     for (const laneName of LANE_ORDER) {
@@ -293,19 +296,21 @@ function emitRetrieverLaneTelemetry(rootDir, { query, mode, lanes, omitted, merg
       merge,
     };
     const filePath = path.join(rootDir, '.ukit', 'storage', 'cache', 'retriever-lanes.jsonl');
-    fsSync.mkdirSync(path.dirname(filePath), { recursive: true });
-    // Best-effort cap: past 256 KiB keep only the newest ~2000 lines.
-    try {
-      const st = fsSync.statSync(filePath);
-      if (st.size > RETRIEVER_LANES_MAX_BYTES) {
-        const kept = fsSync.readFileSync(filePath, 'utf8').split('\n').filter(Boolean)
-          .slice(-RETRIEVER_LANES_KEEP_LINES);
-        fsSync.writeFileSync(filePath, kept.length ? `${kept.join('\n')}\n` : '');
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await withFileLock(filePath, async () => {
+      // Best-effort cap: past 256 KiB keep only the newest ~2000 lines.
+      try {
+        const st = await fs.stat(filePath);
+        if (st.size > RETRIEVER_LANES_MAX_BYTES) {
+          const kept = (await fs.readFile(filePath, 'utf8')).split('\n').filter(Boolean)
+            .slice(-RETRIEVER_LANES_KEEP_LINES);
+          await fs.writeFile(filePath, kept.length ? `${kept.join('\n')}\n` : '', 'utf8');
+        }
+      } catch {
+        // Missing/unreadable file is fine — append below recreates it.
       }
-    } catch {
-      // Missing/unreadable file is fine — append below recreates it.
-    }
-    fsSync.appendFileSync(filePath, `${JSON.stringify(event)}\n`);
+      await fs.appendFile(filePath, `${JSON.stringify(event)}\n`, 'utf8');
+    });
   } catch {
     // Telemetry is advisory; never propagate.
   }
@@ -438,7 +443,7 @@ export async function retrieve(projectRoot, query, { mode = 'search', limit, sna
   // FR-202b: emit lane telemetry only when a merge result exists — skipped
   // entirely on the early no-index return and on empty merges.
   if (merged.length > 0) {
-    emitRetrieverLaneTelemetry(rootDir, {
+    await emitRetrieverLaneTelemetry(rootDir, {
       query: normalizedQuery,
       mode,
       lanes,

package/src/core/fileOps.js

@@ -141,11 +141,26 @@ export async function writeFileAtomic(filePath, content, { fsync = false } = {})
       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.
+      // mounts, per-dir bind mounts, tmpfs overlays), so rename cannot link
+      // them. The payload is already fully written — copy it UP to a sibling
+      // temp on the destination's mount and publish with a second, same-layer
+      // rename. A direct copy onto the live target is the last resort only:
+      // it is non-atomic, and a crash mid-copy truncates the live file.
       if (renameError?.code !== 'EXDEV') throw renameError;
-      await withTransientFsRetry(() => fs.copyFile(tempPath, filePath));
+      const exdevPath = `${filePath}.exdev-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+      try {
+        await withTransientFsRetry(() => fs.copyFile(tempPath, exdevPath));
+        try {
+          await withTransientFsRetry(() => fs.rename(exdevPath, filePath));
+        } catch (secondRenameError) {
+          // Union/bind mount where even same-dir rename is refused: the direct
+          // copy below is non-atomic, but the update must not be silently lost.
+          if (secondRenameError?.code !== 'EXDEV') throw secondRenameError;
+          await withTransientFsRetry(() => fs.copyFile(tempPath, filePath));
+        }
+      } finally {
+        await withTransientFsRetry(() => fs.rm(exdevPath, { force: true })).catch(() => {});
+      }
       await withTransientFsRetry(() => fs.rm(tempPath, { force: true }));
     }
   } catch (error) {

package/src/core/memory/memoryFlags.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { withFileLock } from '../fileOps.js';
 import { resolveConfigStage } from '../runtimeConfig.js';
 
 export const MEMORY_PLANES = Object.freeze(['eligibility', 'writer', 'index', 'decision']);
@@ -71,12 +72,19 @@ export async function appendRolloutReceipt(root, receipt = {}) {
     const dir = path.join(root, '.ukit', 'storage', 'memory');
     const file = path.join(dir, 'rollout-receipts.jsonl');
     await fs.mkdir(dir, { recursive: true });
-    await fs.appendFile(file, `${JSON.stringify(line)}\n`, 'utf8');
-    const stat = await fs.stat(file);
-    if (stat.size > RECEIPT_MAX_BYTES) {
-      const lines = (await fs.readFile(file, 'utf8')).split('\n').filter(Boolean);
-      await fs.writeFile(file, `${lines.slice(-RECEIPT_KEEP_LINES).join('\n')}\n`, 'utf8');
-    }
+    // C79-13: append→stat→rotate is one read-modify-write mutation. Unlocked,
+    // a concurrent writer's truncating rewrite silently ate sibling appends
+    // and a mid-rotation death left a torn JSONL. withFileLock serializes the
+    // whole mutation across processes and async flows; an expired wait drops
+    // THIS receipt whole (journaled) — never a torn file.
+    await withFileLock(file, async () => {
+      await fs.appendFile(file, `${JSON.stringify(line)}\n`, 'utf8');
+      const stat = await fs.stat(file);
+      if (stat.size > RECEIPT_MAX_BYTES) {
+        const lines = (await fs.readFile(file, 'utf8')).split('\n').filter(Boolean);
+        await fs.writeFile(file, `${lines.slice(-RECEIPT_KEEP_LINES).join('\n')}\n`, 'utf8');
+      }
+    });
   } catch {
     // EACCES / ENOSPC / vanished dir — swallowed by contract.
   }