@ngockhoale/ukit 2.6.3 → 2.6.5

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

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import {
   buildCompactMachineKey,
   buildRuntimePaths,
@@ -19,9 +21,42 @@ import { updateCompactPressureFromOutput } from './compact-threshold.mjs';
 // Hook-context self-deadline (2.4.1 orphan-leak class): the compress-output hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
 // budget. Non-hook usage never sets it and is never self-killed.
+// SPEC §8 degrade channel: stdout is the only surface the hook consumer reliably
+// shows the user; stderr is model-facing. writeSync(1) because a same-tick
+// process.exit() can discard a buffered async write on a pipe.
+function emitSystemMessage(text) {
+  try {
+    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: text })}\n`);
+  } catch { /* stdout already gone */ }
+}
+
+// BUG-C23-10: bare `.catch(() => {})` swallowed every sweep failure — a
+// persistent EACCES/ENOSPC on .ukit meant silent non-convergence of the tee/
+// backlog bound (live dir observed at 2,417 files). Announce the first failure
+// and then every 25th, C22 rate-limit posture.
+let sweepFailureCount = 0;
+export function noteSweepFailure(error) {
+  sweepFailureCount += 1;
+  if (sweepFailureCount !== 1 && sweepFailureCount % 25 !== 0) return null;
+  const message =
+    `UKit output-compression: tee cache sweep failed (${sweepFailureCount} failure(s) so far) — `
+    + `the preserved output is safe but the backlog bound may lag. Cause: ${error?.message || error}`;
+  emitSystemMessage(message);
+  return message;
+}
+
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
 if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
-  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+  setTimeout(() => {
+    // BUG-C23-04: deadline expiry abandons configured compression work — a
+    // degrade, and §8(ii) requires it be announced before the exit.
+    emitSystemMessage(
+      `UKit output-compression exceeded its ${HOOK_DEADLINE_MS}ms hook deadline — `
+      + 'tool output passed through uncompressed this call (likely stalled filesystem). '
+      + 'If this repeats, check the .ukit volume or raise UKIT_HOOK_DEADLINE_MS.',
+    );
+    process.exit(0);
+  }, HOOK_DEADLINE_MS).unref();
 }
 
 const ANSI_RE = /\u001b\[[0-9;]*m/g;
@@ -410,16 +445,29 @@ export async function sweepTeeCache(dir, {
   maxEntries = TEE_SWEEP_MAX_ENTRIES,
   maxRemovals = TEE_SWEEP_MAX_REMOVALS,
 } = {}) {
-  let names;
+  let dirents;
   try {
-    names = await fs.readdir(dir);
+    dirents = await fs.readdir(dir, { withFileTypes: true });
   } catch {
     return { sampled: true, scanned: 0, removed: 0 };
   }
+  // Eligible-file count comes from the dirents (one bounded readdir, no per-name
+  // stat) so the count cap is enforceable even when maxFiles > maxEntries —
+  // BUG-C22-10: capping `scanned` at maxEntries made `entries.length` an
+  // under-count and `overflow` was always 0. Expected drain: each sampled sweep
+  // removes up to maxRemovals, so a backlog of B files converges after
+  // ~ceil(B/maxRemovals) sweeps (~16x that many writes at the default 1/16
+  // sampling); the 7d age cutoff drains the remainder only when new writes keep
+  // arriving — a stopped writer converges at ~ceil(B/maxRemovals) sweeps and no
+  // faster, since sweeps are sampled off the write path (BUG-C23-10, FR-006).
+  const eligibleNames = [];
+  for (const dirent of dirents) {
+    if (dirent.isFile()) eligibleNames.push(dirent.name);
+  }
   const cutoff = now() - maxAgeMs;
   const entries = [];
   let scanned = 0;
-  for (const name of names) {
+  for (const name of eligibleNames) {
     if (scanned >= maxEntries) break;
     scanned += 1;
     try {
@@ -429,9 +477,9 @@ export async function sweepTeeCache(dir, {
   }
   entries.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
   // Overflow counts eligible FILES only — foreign entries (non-matching names,
-  // dirs) inflate `names.length` and would evict real entries while the dir is
+  // dirs) inflate the dir listing and would evict real entries while the dir is
   // actually under the cap.
-  const overflow = Math.max(0, entries.length - maxFiles);
+  const overflow = Math.max(0, eligibleNames.length - maxFiles);
   let removed = 0;
   for (const entry of entries) {
     if (removed >= maxRemovals) break;
@@ -487,8 +535,9 @@ async function persistRawOutput(projectRoot, {
   await fs.mkdir(teeCacheDir, { recursive: true });
   await fs.writeFile(absolutePath, rawOutputText, 'utf8');
   // Bounded, sampled tee/ prune (BUG-C21-07): advisory only — a sweep failure
-  // must never lose the preserved output this call just wrote.
-  await maybeSweepTeeCache(teeCacheDir).catch(() => {});
+  // must never lose the preserved output this call just wrote. BUG-C23-10: a
+  // persistent failure (EACCES/ENOSPC) still surfaces as a bounded degrade.
+  await maybeSweepTeeCache(teeCacheDir).catch(noteSweepFailure);
 
   return {
     rawSaved: true,
@@ -1475,7 +1524,19 @@ async function main() {
   process.stdout.write(result.summary);
 }
 
-main().catch((error) => {
-  console.error('[UKit] Failed to compress tool output:', error?.message || String(error));
-  process.exitCode = 1;
-});
+// BUG-C23-13: only run main() on direct CLI invocation — an unguarded bottom
+// call executes on ANY import(), reading the importer's stdin and exiting its
+// process. Guard shape matches compact-threshold.mjs.
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+if (invokedPath && pathToFileURL(invokedPath).href === import.meta.url) {
+  main().catch((error) => {
+    console.error('[UKit] Failed to compress tool output:', error?.message || String(error));
+    // BUG-C23-01: stderr alone is invisible to the hook consumer — the §8
+    // announce contract requires a stdout systemMessage on the crash path too.
+    emitSystemMessage(
+      'UKit output-compression failed before it could compress this tool output; '
+      + 'the raw output was passed through uncompressed. Run `ukit doctor` if this repeats.',
+    );
+    process.exitCode = 1;
+  });
+}

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
 import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 import {
   buildCompactMachineKey,
   buildRuntimePaths,
@@ -22,9 +24,27 @@ import {
 // Hook-context self-deadline (2.4.1 orphan-leak class): the reinject-context hook passes
 // UKIT_HOOK_DEADLINE_MS so a wedged read can never orphan this process past the hook
 // budget. Non-hook usage never sets it and is never self-killed.
+// SPEC §8 degrade channel: stdout is the only surface the hook consumer reliably
+// shows the user; stderr is model-facing. writeSync(1) because a same-tick
+// process.exit() can discard a buffered async write on a pipe.
+function emitSystemMessage(text) {
+  try {
+    fsSync.writeSync(1, `${JSON.stringify({ systemMessage: text })}\n`);
+  } catch { /* stdout already gone */ }
+}
+
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10);
 if (Number.isFinite(HOOK_DEADLINE_MS) && HOOK_DEADLINE_MS > 0) {
-  setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+  setTimeout(() => {
+    // BUG-C23-04: deadline expiry abandons the configured context reinjection —
+    // a degrade, and §8(ii) requires it be announced before the exit.
+    emitSystemMessage(
+      `UKit reinject-context exceeded its ${HOOK_DEADLINE_MS}ms hook deadline — `
+      + 'post-compaction context reinjection skipped this pass (likely stalled filesystem). '
+      + 'If this repeats, check the .ukit volume or raise UKIT_HOOK_DEADLINE_MS.',
+    );
+    process.exit(0);
+  }, HOOK_DEADLINE_MS).unref();
 }
 
 const STATE_TTL_MS = 30 * 60 * 1000;
@@ -108,7 +128,7 @@ async function main() {
   // (writeThresholdCompactPlan) re-read from disk, so they build on the zeroed state and
   // keep their own stats increments intact. Session-scoped: sibling sessions keep their
   // own records.
-  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, sessionConfig), sessionConfig);
+  await writeCompactPressureState(projectRoot, await resetCompactPressureState(pressureState, sessionConfig), sessionConfig);
   const anchorLines = dynamicLines.filter((line) => (
     line.startsWith('- Recent routed lane:')
     || line.startsWith('- Current approach:')
@@ -124,7 +144,7 @@ async function main() {
     || line.startsWith('- Recent delegation hint:')
   ));
   const maxTokens = Math.max(160, Math.min(320, Number(config.memory?.maxInjectionTokens) || 320));
-  const thresholdPlan = buildThresholdCompactPlan({
+  const thresholdPlan = await buildThresholdCompactPlan({
     state: pressureState,
     config,
     routeState: state,
@@ -1047,7 +1067,19 @@ async function buildPreviousContextLines(projectRoot, state, config) {
   return [`- Previous context: ${rankedItems.map((item) => buildPreviousContextSnippet(item)).join(' | ')}`];
 }
 
-main().catch((error) => {
-  console.error('[UKit] Failed to build compact reinject context:', error?.message || String(error));
-  process.exitCode = 1;
-});
+// BUG-C23-13: only run main() on direct CLI invocation — an unguarded bottom
+// call executes on ANY import(), reading the importer's stdin and exiting its
+// process. Guard shape matches compact-threshold.mjs.
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
+if (invokedPath && pathToFileURL(invokedPath).href === import.meta.url) {
+  main().catch((error) => {
+    console.error('[UKit] Failed to build compact reinject context:', error?.message || String(error));
+    // BUG-C23-01: stderr alone is invisible to the hook consumer — the §8
+    // announce contract requires a stdout systemMessage on the crash path too.
+    emitSystemMessage(
+      'UKit reinject-context failed before it could rebuild the compact context block; '
+      + 'the session continues without reinjected context this pass. Run `ukit doctor` if this repeats.',
+    );
+    process.exitCode = 1;
+  });
+}

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

@@ -561,7 +561,11 @@ async function alreadyCoordinatedThisStop({ projectRoot, sessionKey, now, dedupe
         return true;
       }
       await fs.mkdir(path.dirname(statePath), { recursive: true });
-      await fs.writeFile(statePath, `${JSON.stringify({ lastStop: { key: sessionKey, ts: now } }, null, 1)}\n`, 'utf8');
+      // BUG-C23-08: spread `current` — a bare { lastStop } write erased the
+      // `handoff` stall-streak slot written by bumpHandoffStallCount, which ran
+      // AFTER this dedupe write each invocation → count always read 1 and the
+      // FR-004 liveness breaker could never fire.
+      await fs.writeFile(statePath, `${JSON.stringify({ ...current, lastStop: { key: sessionKey, ts: now } }, null, 1)}\n`, 'utf8');
       return false;
     });
     return outcome.ok ? outcome.value === true : false;
@@ -683,6 +687,9 @@ function isDirectRun() {
     selfUrlPath = null;
   }
   if (selfUrlPath && selfUrlPath === selfPath) return true;
+  // BUG-C22-01: skip fs entirely for non-matching importers — a stalled mount
+  // must not park the event loop during `await import` inside an armed deadline.
+  if (selfUrlPath && path.basename(selfUrlPath) !== path.basename(selfPath)) return false;
   try {
     return fsSync.realpathSync(selfUrlPath) === fsSync.realpathSync(selfPath);
   } catch {

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

@@ -175,8 +175,15 @@ export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxW
           continue; // the slot is free now — retry immediately
         }
       }
-    } catch {
-      continue; // lock vanished between mkdir and stat — retry immediately
+    } catch (statError) {
+      // BUG-C22-16: a persistent stat error (EPERM/ENOTDIR/EIO on a failing
+      // mount, or ELOOP/ENOENT on a dangling symlink where mkdir still reports
+      // EEXIST) must not busy-spin — a bare `continue` skipped both the
+      // maxWait break and the backoff sleep, looping mkdir→stat→throw forever.
+      if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
+      if (statError?.code === 'ENOENT') continue; // lock vanished — retry immediately
+      await sleep(lockBackoffDelayMs());
+      continue;
     }
 
     if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked

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

@@ -394,12 +394,16 @@ function sweepHookErrorsDir(dir, {
     return { scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  // BUG-C22-13: eligible count comes from the full name listing (bounded by the
+  // single readdir, no per-name stat) so the count cap is enforceable even
+  // though maxFiles > maxEntries — capping `scanned` first made
+  // `entries.length` an under-count and `overflow` was always 0.
+  const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
   let scanned = 0;
-  for (const name of names) {
+  for (const name of eligibleNames) {
     if (scanned >= maxEntries) break;
     scanned += 1;
-    if (!name.endsWith('.jsonl')) continue;
     try {
       const stats = fs.statSync(path.join(dir, name));
       if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
@@ -409,7 +413,7 @@ function sweepHookErrorsDir(dir, {
   // Overflow counts eligible FILES only — foreign entries (non-matching names,
   // dirs) inflate `names.length` and would evict real entries while the dir is
   // actually under the cap.
-  const overflow = Math.max(0, entries.length - maxFiles);
+  const overflow = Math.max(0, eligibleNames.length - maxFiles);
   let removed = 0;
   for (const entry of entries) {
     if (removed >= maxRemovals) break;
@@ -820,6 +824,42 @@ export async function runSessionCompact(pi, event, { projectRoot, context: exten
   return undefined;
 }
 
+// ── BUG-C22-05 crash-streak breaker (parity with .claude/hooks/completion-gate.sh) ──
+// A persistently crashing completion evaluator must not fail every Stop forever.
+// The byte-append file is shared with the shell hook so one streak tracks both
+// harnesses; a clean evaluation deletes it, so the count is consecutive crashes.
+const COMPLETION_CRASH_STREAK_FILE = path.join('.ukit', 'storage', 'cache', 'completion-gate-crash.streak');
+
+async function bumpCompletionCrashStreak(projectRoot) {
+  const file = path.join(projectRoot, COMPLETION_CRASH_STREAK_FILE);
+  try {
+    await fs.promises.mkdir(path.dirname(file), { recursive: true });
+    await fs.promises.appendFile(file, '.');
+    const buf = await fs.promises.readFile(file);
+    return buf.length || 1;
+  } catch {
+    return 1;
+  }
+}
+
+async function resetCompletionCrashStreak(projectRoot) {
+  try {
+    await fs.promises.rm(path.join(projectRoot, COMPLETION_CRASH_STREAK_FILE), { force: true });
+  } catch { /* best effort */ }
+}
+
+async function readStopGateMaxCrashStreaks(projectRoot) {
+  try {
+    const parsed = JSON.parse(
+      await fs.promises.readFile(path.join(projectRoot, '.ukit', 'storage', 'config.json'), 'utf8'),
+    );
+    const value = parsed?.handoff?.fullstack?.stopGateMaxCrashStreaks;
+    return Number.isFinite(value) ? Math.max(1, value) : 3;
+  } catch {
+    return 3;
+  }
+}
+
 export async function runSessionStop(
   pi,
   event,
@@ -834,7 +874,35 @@ export async function runSessionStop(
   const payload = buildHookPayload('Stop', metadata);
   const state = suppliedState ?? await readRouteState(projectRoot, payload);
   const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
-  const evaluation = evaluateCompletion({ state, ledger });
+  let evaluation;
+  try {
+    evaluation = evaluateCompletion({ state, ledger });
+  } catch (error) {
+    // BUG-C22-05: fail-closed like the shell gate (continue the turn), but only up
+    // to the configured consecutive-crash cap — a persistently broken evaluator
+    // must release loudly instead of looping every Stop forever.
+    const streak = await bumpCompletionCrashStreak(projectRoot);
+    const maxStreak = await readStopGateMaxCrashStreaks(projectRoot);
+    if (streak > maxStreak) {
+      await resetCompletionCrashStreak(projectRoot);
+      sendContext(pi, [
+        `[UKit] stop coordinator released this stop after ${maxStreak} consecutive infrastructure failures `
+        + '(the completion evaluator crashed every Stop — gate fail-closed cap reached). '
+        + 'The completion gate is DOWN, not your work: run `ukit install` to repair, '
+        + 'then re-send the task in a new message if the run must continue.',
+      ], 'nextTurn', { display: true });
+      return undefined;
+    }
+    pi.logger?.warn?.(`[UKit] completion evaluator crashed (streak ${streak}/${maxStreak}): ${error?.message || error}`);
+    return {
+      continue: true,
+      additionalContext:
+        `UKit stop coordinator: infrastructure failure while evaluating this stop (crash streak ${streak}/${maxStreak}) — `
+        + 'the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message.',
+    };
+  }
+  // A clean evaluation resets the consecutive-crash streak (shared with the shell hook).
+  await resetCompletionCrashStreak(projectRoot);
   if (!evaluation.continue) {
     if (evaluation.capped) pi.logger?.warn?.(`[UKit] ${evaluation.reason}`);
     const missingEvidence = Array.isArray(evaluation.missingEvidence) ? evaluation.missingEvidence : [];

package/templates/ukit/storage/config.json

@@ -273,6 +273,7 @@
     "fullstack": {
       "stopGateEnabled": true,
       "stopGateMaxStalledBlocks": 12,
+      "stopGateMaxCrashStreaks": 3,
       "quietScansRequired": 2,
       "idleWatchdogMin": 5,
       "autoArchive": true,
@@ -580,6 +581,7 @@
       "fullstack": {
         "stopGateEnabled": "Bật Stop gate handoff: RUN.md Phase != done/blocked → Stop hook từ chối stop kèm Next step, giữ handoff-fullstack chạy tiếp thay vì đứng sau recap. Tắt chỉ khi debug.",
         "stopGateMaxStalledBlocks": "Liveness breaker: cursor không nhích qua N lần block liên tiếp thì gate thả stop (tránh vòng lặp vô tận). Mặc định 12.",
+        "stopGateMaxCrashStreaks": "Liveness breaker cho coordinator crash: sau N lần block liên tiếp do infrastructure failure, gate thả stop kèm cảnh báo lớn. Mặc định 3.",
         "quietScansRequired": "Số scan liên tiếp không thấy việc mới trước khi handoff-fullstack được phép đóng run. Mặc định 2.",
         "idleWatchdogMin": "Khoảng phút cho scheduled wakeup nếu harness hỗ trợ (cron/loop). Mặc định 5.",
         "autoArchive": "true = Phase F tự archive cycle vào docs/AI_HANDOFF/archive/cycle-NN/ khi hoàn tất.",