@ngockhoale/ukit 2.6.4 → 2.6.6

package/templates/.claude/ukit/runtime/hook-telemetry.mjs

@@ -200,6 +200,22 @@ export function maybeSweepTelemetryDir(dir, {
   return { sampled: true, ...sweepTelemetryDir(dir, options) };
 }
 
+// BUG-C23-10: a bare `catch {}` around the sweep swallowed every failure — a
+// persistent EACCES/ENOSPC meant silent non-convergence of the dir bound.
+// 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 hook-telemetry: latency dir sweep failed (${sweepFailureCount} failure(s) so far) — `
+    + `the appended row is safe but the backlog bound may lag. Cause: ${error?.message || error}`;
+  try {
+    fs.writeSync(1, `${JSON.stringify({ systemMessage: message })}\n`);
+  } catch { /* stdout already gone */ }
+  return message;
+}
+
 export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
   try {
     if (!row || typeof row !== 'object') return false;
@@ -211,7 +227,7 @@ export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
     fs.appendFileSync(filePath, line, 'utf8');
     // Sampled bounded dir sweep (BUG-C21-10): advisory — a sweep failure must
     // never alter the row this call just appended.
-    try { maybeSweepTelemetryDir(dir); } catch { /* advisory */ }
+    try { maybeSweepTelemetryDir(dir); } catch (error) { noteSweepFailure(error); }
     return true;
   } catch {
     // Advisory: an unwritable or corrupt telemetry target must never alter a

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;
@@ -422,7 +457,9 @@ export async function sweepTeeCache(dir, {
   // 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 rest even without new writes.
+  // 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);
@@ -498,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,
@@ -1486,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;
@@ -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;

package/templates/.codex/README.md

@@ -80,7 +80,7 @@ For clearly non-code specialist lanes (docs-only, status, task queue), skip the
 - If verification is needed, prefer `node .codex/ukit/index/verify-context.mjs ...`.
 - **Treat helper commands as internal orchestration.** Run them yourself when needed; never ask end users to run them.
 
-## UKit v1.5.0 Shared Runtime
+## UKit Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, validation, and Safe Patch guardrail toggles.

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.5.0 features.
+This folder stores shared UKit runtime state.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`