@ngockhoale/ukit 3.0.9 → 3.0.11

package/template_project/.claude/ukit/index/triage.mjs

@@ -22,7 +22,7 @@ const signature = collectPositionalArgs(args, ['--root']);
 if (!signature) {
   console.error('Usage: node .claude/ukit/index/triage.mjs "<error signature>"');
   process.exitCode = 1;
-} else {
+} else try {
   const indexGeneratedAtMs = await ensureFreshIndex({ rootDir, logPrefix: 'bug:triage' });
   const cachePath = path.join(rootDir, '.claude', 'ukit', 'triage-cache.json');
   const requestKey = buildTriageRequestKey({
@@ -55,7 +55,15 @@ if (!signature) {
   console.log(`test: ${result.recommendedTestCommand}`);
 }
 
+catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}
+
 async function ensureFreshIndex({ rootDir, logPrefix }) {
+  if (typeof indexCore.ensureIndexFresh === 'function') {
+    return indexCore.ensureIndexFresh({ rootDir, logPrefix });
+  }
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = lastRefreshMs === null
     ? true
@@ -67,17 +75,10 @@ async function ensureFreshIndex({ rootDir, logPrefix }) {
           generatedAtMs: lastRefreshMs,
         })
       : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
-
-  if (!stale) {
-    return lastRefreshMs;
-  }
-
+  if (!stale) return lastRefreshMs;
   const summary = await buildCodeIndex({ rootDir });
-  if (lastRefreshMs !== null) {
-    console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
-  } else {
-    console.log(`[ukit:${logPrefix}] stale index refreshed (no previous cache timestamp)`);
-  }
+  // Prefer the build's own generatedAtMs; only re-read when the stubbed
+  // build didn't report one (keeps generatedAt call count at 1).
   return Number.isFinite(summary?.generatedAtMs)
     ? summary.generatedAtMs
     : getIndexArtifactGeneratedAt({ rootDir });

package/template_project/.claude/ukit/index/verify-context.mjs

@@ -30,7 +30,7 @@ const effectiveIntent = deriveHelperIntent({ intent, targetFile });
 if (!intent && !targetFile) {
   console.error('Usage: node .claude/ukit/index/verify-context.mjs "<intent>" [--target <file>] [--type trivial|simple|non-trivial]');
   process.exitCode = 1;
-} else {
+} else try {
   const indexGeneratedAtMs = await ensureFreshIndex({
     rootDir,
     logPrefix: 'verify',
@@ -89,7 +89,15 @@ if (!intent && !targetFile) {
   printVerificationPlan(plan);
 }
 
+catch (error) {
+  console.error(error && error.message ? error.message : error);
+  process.exit(1);
+}
+
 async function ensureFreshIndex({ rootDir, logPrefix }) {
+  if (typeof indexCore.ensureIndexFresh === 'function') {
+    return indexCore.ensureIndexFresh({ rootDir, logPrefix });
+  }
   const lastRefreshMs = await getIndexArtifactGeneratedAt({ rootDir });
   const stale = lastRefreshMs === null
     ? true
@@ -101,17 +109,10 @@ async function ensureFreshIndex({ rootDir, logPrefix }) {
           generatedAtMs: lastRefreshMs,
         })
       : (Date.now() - lastRefreshMs) > DEFAULT_INDEX_CACHE_MAX_AGE_MS;
-
-  if (!stale) {
-    return lastRefreshMs;
-  }
-
+  if (!stale) return lastRefreshMs;
   const summary = await buildCodeIndex({ rootDir });
-  if (lastRefreshMs !== null) {
-    console.log(`[ukit:${logPrefix}] stale index refreshed (last=${new Date(lastRefreshMs).toISOString()})`);
-  } else {
-    console.log(`[ukit:${logPrefix}] stale index refreshed (no previous cache timestamp)`);
-  }
+  // Prefer the build's own generatedAtMs; only re-read when the stubbed
+  // build didn't report one (keeps generatedAt call count at 1).
   return Number.isFinite(summary?.generatedAtMs)
     ? summary.generatedAtMs
     : getIndexArtifactGeneratedAt({ rootDir });

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

@@ -323,6 +323,36 @@ async function quarantineReclaim(lockPath, owner, ownerToken, retry = withTransi
   }
 }
 
+// C79-21: a process dying between quarantineReclaim's rename and rm strands a
+// `<lock>.reclaim-<token>` sibling dir forever — the quarantine path carries no
+// staleness record of its own, so nothing reclaims it later. Every acquire
+// therefore sweeps THIS lock's orphaned quarantine dirs: one bounded readdir on
+// the lock's parent dir removes `<basename>.reclaim-*` dirs older than staleMs.
+// Fresh dirs are left alone — a live reaper may be between rename and rm on them.
+// Best-effort: every failure is swallowed; the next acquire retries the sweep.
+async function sweepStaleReclaims(lockPath, staleMs) {
+  const parentDir = path.dirname(lockPath);
+  const prefix = `${path.basename(lockPath)}.reclaim-`;
+  let entries;
+  try {
+    entries = await fs.readdir(parentDir, { withFileTypes: true });
+  } catch {
+    return; // missing or unreadable parent — nothing to sweep
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
+    const orphanPath = path.join(parentDir, entry.name);
+    try {
+      const stat = await fs.stat(orphanPath);
+      if (Date.now() - stat.mtimeMs <= staleMs) continue;
+      await fs.rm(orphanPath, { recursive: true, force: true });
+    } catch {
+      // entry raced away or is unreapable — leave it for the next acquire
+    }
+  }
+}
+
+
 // In-process holder registry: same-pid holders are parallel async flows whose liveness
 // a pid probe cannot prove, so the module tracks them itself (same as withFileLock).
 const inProcessLockHolders = new Map();
@@ -422,6 +452,9 @@ export async function withAsyncLock(filePath, { signal, deadlineMs = LOCK_MAX_SL
   const releaseRetry = (op) => withTransientFsRetry(op, { deadlineMs: LOCK_RESERVE_MS });
 
   while (true) {
+    // Reap stale `*.reclaim-*` quarantine dirs stranded by dead reapers. Cheap:
+    // one readdir per attempt, all failures swallowed (C79-21).
+    await sweepStaleReclaims(lockPath, stale);
     try {
       // The lock parent must exist before the atomic acquire — a first-ever run in a
       // fresh project would otherwise fail mkdir with ENOENT.

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

@@ -536,8 +536,15 @@ async function persistRawOutput(projectRoot, {
     exitCode,
   });
 
-  await fs.mkdir(teeCacheDir, { recursive: true });
-  await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+  try {
+    await fs.mkdir(teeCacheDir, { recursive: true });
+    await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+  } catch {
+    // TASK-003 / FR-006: an unwritable tee dir (EACCES, ENOSPC, EEXIST on a
+    // non-dir, …) must degrade to "no raw file" — never reject the caller's
+    // compression result.
+    return { rawSaved: false, rawPath: '', rawBytes: 0 };
+  }
   // Bounded, sampled tee/ prune (BUG-C21-07): advisory only — a sweep failure
   // must never lose the preserved output this call just wrote. BUG-C23-10: a
   // persistent failure (EACCES/ENOSPC) still surfaces as a bounded degrade.

package/template_project/.claude/ukit/runtime/resumable-run.mjs

@@ -266,9 +266,25 @@ async function writeJsonAtomic(filePath, value) {
     try {
       await fs.rename(tempPath, filePath);
     } catch (renameError) {
-      // EXDEV: tmp and destination on different mounts — copy over and unlink.
+      // EXDEV: tmp and destination on different mounts — copy UP to a sibling
+      // temp on the destination's mount and publish with a second, same-layer
+      // rename. A direct copy onto the live record is the last resort only:
+      // it is non-atomic, and a crash mid-copy truncates the live record.
       if (renameError?.code !== 'EXDEV') throw renameError;
-      await fs.copyFile(tempPath, filePath);
+      const exdevPath = `${filePath}.exdev-${process.pid}-${Date.now()}-${atomicWriteCounter++}`;
+      try {
+        await fs.copyFile(tempPath, exdevPath);
+        try {
+          await 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 record must not be silently lost.
+          if (secondRenameError?.code !== 'EXDEV') throw secondRenameError;
+          await fs.copyFile(tempPath, filePath);
+        }
+      } finally {
+        await fs.rm(exdevPath, { force: true }).catch(() => {});
+      }
       await fs.rm(tempPath, { force: true });
     }
   } catch (error) {

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

@@ -482,15 +482,49 @@ export async function readPromptCacheEntry(projectRoot, requestKey, { maxEntries
     lastHitAt: Date.now(),
     hitCount: (entry.hitCount ?? 0) + 1,
   };
-  const nextDocument = normalizePromptCacheDocument({
-    entries: [
-      touchedEntry,
-      ...cache.entries.slice(0, entryIndex),
-      ...cache.entries.slice(entryIndex + 1),
-    ],
-  }, { maxEntries });
-  await writeJson(runtimePaths.promptCachePath, nextDocument);
-  return nextDocument.entries[0] ?? touchedEntry;
+  try {
+    // SPEC §5 FR-019: the touch's read-merge-write runs under the cache-file
+    // lock — concurrent hook processes used to merge over the same snapshot
+    // and drop hitCounts/entries. The lock RE-READS the document so the merge
+    // applies to the freshest state, and an entry a concurrent purge already
+    // dropped is never resurrected.
+    const locked = await withFileLock(runtimePaths.promptCachePath, async () => {
+      const lockedCache = normalizePromptCacheDocument(
+        await readJson(runtimePaths.promptCachePath, null),
+        { maxEntries },
+      );
+      const lockedIndex = lockedCache.entries.findIndex(
+        (lockedEntry) => lockedEntry.requestKey === requestKey,
+      );
+      if (lockedIndex < 0) {
+        return null;
+      }
+      const mergedEntry = {
+        ...lockedCache.entries[lockedIndex],
+        updatedAt: Date.now(),
+        lastHitAt: Date.now(),
+        hitCount: (lockedCache.entries[lockedIndex].hitCount ?? 0) + 1,
+      };
+      const nextDocument = normalizePromptCacheDocument({
+        entries: [
+          mergedEntry,
+          ...lockedCache.entries.slice(0, lockedIndex),
+          ...lockedCache.entries.slice(lockedIndex + 1),
+        ],
+      }, { maxEntries });
+      await writeJson(runtimePaths.promptCachePath, nextDocument);
+      return nextDocument.entries[0] ?? mergedEntry;
+    });
+    // Lock-busy (fail-closed skip, journaled) or entry-gone-under-lock →
+    // degrade to the in-memory touched entry, same as the failure path below.
+    return locked ?? touchedEntry;
+  } catch {
+    // SPEC §5 FR-009 (mirrors src/core/token/index.js): the touch-write is a
+    // side effect of a READ — a full/unwritable cache (EACCES, ENOSPC, ...)
+    // must never reject the read. Degrade to the in-memory touched entry; the
+    // persisted hitCount simply lags until a later write succeeds.
+    return touchedEntry;
+  }
 }
 
 export async function writePromptCacheEntry(projectRoot, entry, { maxEntries = DEFAULT_PROMPT_CACHE_MAX_ENTRIES } = {}) {
@@ -500,15 +534,23 @@ export async function writePromptCacheEntry(projectRoot, entry, { maxEntries = D
   }
 
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const cache = normalizePromptCacheDocument(await readJson(runtimePaths.promptCachePath, null), { maxEntries });
-  const nextDocument = normalizePromptCacheDocument({
-    entries: [
-      normalizedEntry,
-      ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
-    ],
-  }, { maxEntries });
-  await writeJson(runtimePaths.promptCachePath, nextDocument);
-  return nextDocument;
+  // SPEC §5 FR-019: the merge must re-read under the lock — merging over a
+  // pre-lock snapshot is the lost-update race this lock exists to close, and
+  // no code path may write the cache unlocked.
+  const lockedDocument = await withFileLock(runtimePaths.promptCachePath, async () => {
+    const cache = normalizePromptCacheDocument(await readJson(runtimePaths.promptCachePath, null), { maxEntries });
+    const nextDocument = normalizePromptCacheDocument({
+      entries: [
+        normalizedEntry,
+        ...cache.entries.filter((existingEntry) => existingEntry.requestKey !== normalizedEntry.requestKey),
+      ],
+    }, { maxEntries });
+    await writeJson(runtimePaths.promptCachePath, nextDocument);
+    return nextDocument;
+  });
+  // Lock-busy → the write was skipped (journaled); callers already tolerate a
+  // skipped cache update, so report null like the invalid-entry path.
+  return lockedDocument ?? null;
 }
 
 function normalizeCompactHistoryEntry(entry) {