@ngockhoale/ukit 3.4.20 → 3.4.22

package/template_project/.claude/ukit/runtime/execution-ledger.mjs

@@ -160,6 +160,7 @@ export async function sweepExecLedgerDir(dir, {
   maxFiles = LEDGER_MAX_FILES,
   maxEntries = LEDGER_SWEEP_MAX_ENTRIES,
   maxRemovals = LEDGER_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let dirents;
   try {
@@ -178,9 +179,15 @@ export async function sweepExecLedgerDir(dir, {
     if (dirent.isFile()) eligibleNames.push(dirent.name);
   }
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = await fs.stat(path.join(dir, name));
@@ -258,7 +265,7 @@ export async function maybeSweepExecLedgerDir(dir, {
     ? Math.min(1, Math.max(0, probability))
     : ledgerSweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return { sampled: true, ...(await sweepExecLedgerDir(dir, options)) };
+  return { sampled: true, ...(await sweepExecLedgerDir(dir, { ...options, random })) };
 }
 
 function resumeIntentPath(projectRoot, sessionId) {

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -6,7 +6,7 @@ import { pathToFileURL } from 'node:url';
 // TASK-016: children run through the process-tree runner instead of bare
 // spawnSync — a timed-out child is TERM→KILLed as a whole POSIX process group,
 // so a bash wrapper can no longer orphan the Node grandchildren it spawned.
-import { runHookProcess } from './hook-process.mjs';
+import { runHookProcess, resolveHookCommand, SPAWN_UNAVAILABLE_CODES } from './hook-process.mjs';
 // Repeated identical blocks (a model respawning an agent into the same refusal) get a
 // "stop and report verbatim" directive appended. Advisory + fail-open; see block-breaker.mjs.
 // Loaded dynamically so a partially-updated runtime (module missing) degrades to "no advice"
@@ -88,6 +88,7 @@ async function readStdinBounded() {
 //   'signal'           — the child died from a signal this runner did not send
 //   'error'            — the child never spawned (ENOENT and friends)
 //   'budget-exhausted' — the script never ran: the chain total budget was spent
+//   'spawn-unavailable' — win32 bash launcher not found or could not start the .sh script (no process ran); warned, never blocks
 function chainFailureKind(processResult) {
   switch (processResult?.failureKind) {
     case 'overflow':
@@ -169,6 +170,18 @@ function parseScriptArg(arg) {
 // 'timeout'. The deadline is enforced by Promise.race + AbortSignal; the
 // rejection race keeps running in the background (in-proc code cannot be
 // SIGKILLed) but its late return value is discarded.
+// FR-004: warning for a step whose win32 bash launcher never started. Single
+// Windows fixText — this classification is unreachable off win32 (`viaBash`).
+const SPAWN_UNAVAILABLE_FIX =
+  'Fix: install Git for Windows (https://git-scm.com/download/win) or set UKIT_BASH_BIN to the full path of bash.exe.';
+
+function spawnUnavailableWarning(scriptName, cause) {
+  const gateText = FAIL_CLOSED_SCRIPTS.has(scriptName)
+    ? 'fail-closed gate NOT enforced'
+    : 'advisory hook skipped';
+  return `UKit WARNING: hook ${scriptName} could not be launched (${cause}) and was SKIPPED — ${gateText}. ${SPAWN_UNAVAILABLE_FIX}\n`;
+}
+
 async function runModuleStep({ scriptPath, payload, payloadText, projectRoot, env, deadlineMs }) {
   const controller = new AbortController();
   let timer;
@@ -296,11 +309,25 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
       // (ask + exit 2). Under --emit-verdict the runner replays the direct
       // Claude contract (deny + exit 0), so children must NOT see it.
       ...(chainMarker ? { UKIT_HOOK_CHAIN_RUNNER: '1' } : {}),
+      // BUG-3 (TASK-003): the runner owns hook-latency rows for every chained
+      // step (see recordHookTiming below). This marker keeps hook-telemetry.sh
+      // unarmed in `.sh` children so they spawn no `--finish` node/sleep.
+      // Distinct from UKIT_HOOK_CHAIN_RUNNER, which is withheld under
+      // --emit-verdict; this one is set in both modes. Direct invocations
+      // (no runner) never see it and stay armed.
+      UKIT_HOOK_TELEMETRY_BY_RUNNER: '1',
     };
     const stepDeadlineMs = Math.min(childBudgetsMs[scriptIndex], remainingMs);
     // TASK-001: `.mjs` args run in-proc via runHook(ctx); `.sh` stays a child
     // process. Both paths share deadline/budget, results[] shape, and break
     // conditions.
+    // FR-003/FR-004: non-.mjs steps launch through the resolver (absolute Git
+    // Bash on win32 for `.sh`, the script itself everywhere else). `viaBash`
+    // is the ONLY thing that can turn a launch failure into spawn-unavailable.
+    const launch = scriptPath.endsWith('.mjs')
+      ? { command: scriptPath, args: [], viaBash: false }
+      : resolveHookCommand(scriptPath);
+    const { viaBash } = launch;
     const result = scriptPath.endsWith('.mjs')
       ? await runModuleStep({
           scriptPath,
@@ -310,10 +337,13 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
           env: stepEnv,
           deadlineMs: stepDeadlineMs,
         })
-      : await runHookProcess({
-          command: scriptPath,
+      : launch.command === null
+        // No bash found on win32: nothing is spawned (never a bare `bash`).
+        ? { code: 1, stdout: '', stderr: '', failureKind: 'error', spawnFailed: true, errorCode: null }
+        : await runHookProcess({
+          command: launch.command,
           deadlineMs: stepDeadlineMs,
-          args: [],
+          args: launch.args,
           input: payloadText,
           maxBuffer: MAX_BUFFER_BYTES,
           cwd: projectRoot,
@@ -324,6 +354,38 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
           // decision JSON.
           env: stepEnv,
         });
+    const launchFailed = viaBash && (
+      launch.command === null
+      || (result.spawnFailed === true && SPAWN_UNAVAILABLE_CODES.has(result.errorCode))
+    );
+    if (launchFailed && scriptName !== 'block-dangerous.sh' && fs.existsSync(scriptPath)) {
+      const stepElapsedMs = Date.now() - childStartedAt;
+      results.push({
+        scriptName,
+        code: 0,
+        stdout: '',
+        stderr: spawnUnavailableWarning(scriptName, launch.command === null ? 'bash.exe not found' : result.errorCode),
+        failureKind: 'spawn-unavailable',
+        killed: false,
+        elapsedMs: stepElapsedMs,
+      });
+      recordHookTiming({
+        projectRoot,
+        sessionId: payload?.session_id,
+        event: payload?.hook_event_name || null,
+        tool: payload?.tool_name || null,
+        toolUseId: payload?.tool_use_id || null,
+        hook: scriptName,
+        elapsedMs: stepElapsedMs,
+        outcome: 'spawn-unavailable',
+      });
+      continue;
+    }
+    if (launch.command === null) {
+      // Resolver found no bash but the step does not qualify for the degrade
+      // (script missing / block-dangerous.sh): fail closed exactly like a spawn error.
+      result.stderr = `UKit hook ${scriptName} could not be launched: bash.exe not found\n`;
+    }
     const failureKind = chainFailureKind(result);
     // FR-001: on infra failure (error/timeout — no module verdict) the result
     // code is 2 when the step is fail-closed, else 1.
@@ -350,21 +412,21 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
       elapsedMs: Date.now() - childStartedAt,
     });
 
-    // TASK-001 (FR-003): `.sh` children write their own hook-latency row via
-    // hook-telemetry.sh --finish; in-proc `.mjs` steps cannot — the runner
-    // emits the equivalent row per module step (hook = basename incl. `.mjs`).
-    if (scriptPath.endsWith('.mjs')) {
-      recordHookTiming({
-        projectRoot,
-        sessionId: payload?.session_id,
-        event: payload?.hook_event_name || null,
-        tool: payload?.tool_name || null,
-        toolUseId: payload?.tool_use_id || null,
-        hook: scriptName,
-        elapsedMs: Date.now() - childStartedAt,
-        outcome: failureKind,
-      });
-    }
+    // TASK-001 (FR-003) / TASK-003 (BUG-3): the runner is the single telemetry
+    // owner for every chained step. `.mjs` steps run in-proc and cannot write
+    // their own row; `.sh` children are told via UKIT_HOOK_TELEMETRY_BY_RUNNER
+    // not to spawn hook-telemetry.mjs --finish. One row per step, hook =
+    // basename incl. extension; elapsedMs includes bash start-up.
+    recordHookTiming({
+      projectRoot,
+      sessionId: payload?.session_id,
+      event: payload?.hook_event_name || null,
+      tool: payload?.tool_name || null,
+      toolUseId: payload?.tool_use_id || null,
+      hook: scriptName,
+      elapsedMs: Date.now() - childStartedAt,
+      outcome: failureKind,
+    });
 
     // B1 (TASK-001, SPEC §FR-001): under `--emit-verdict` a child that emits a
     // `hookSpecificOutput` permission decision owns the verdict even at exit 0
@@ -602,18 +664,34 @@ try {
       .filter((r) => r !== decisionResult && r !== last && typeof r.stdout === 'string' && r.stdout.length > 0)
       .map((r) => r.stdout)
       .join('');
+    // FR-005: spawn-unavailable steps never block, but must stay visible. Their
+    // warnings go to stderr exactly ONCE (here) and, where stdout is a clean
+    // JSON document the runner owns, into `systemMessage`.
+    const warnings = chain.results
+      .filter((r) => r.failureKind === 'spawn-unavailable')
+      .map((r) => r.stderr)
+      .join('');
+    if (warnings) process.stderr.write(warnings);
     if (decisionOwnsVerdict) {
       let verdictOut = decisionResult.stdout;
       try {
         const doc = JSON.parse(verdictOut);
         const hso = doc?.hookSpecificOutput;
+        let changed = false;
         if (hso?.permissionDecision === 'deny') {
           const advice = breakerAdvice(hso.permissionDecisionReason);
           if (advice) {
             hso.permissionDecisionReason = `${hso.permissionDecisionReason}\n${advice}`;
-            verdictOut = JSON.stringify(doc);
+            changed = true;
           }
         }
+        if (warnings && doc && typeof doc === 'object' && !Array.isArray(doc)) {
+          doc.systemMessage = typeof doc.systemMessage === 'string' && doc.systemMessage
+            ? `${doc.systemMessage}\n${warnings.trimEnd()}`
+            : warnings.trimEnd();
+          changed = true;
+        }
+        if (changed) verdictOut = JSON.stringify(doc);
       } catch { /* unparseable verdict: replay it untouched */ }
       process.stdout.write(verdictOut);
       if (decisionResult.stderr) process.stderr.write(decisionResult.stderr);
@@ -662,8 +740,14 @@ try {
       } else {
         if (contextStdout) process.stdout.write(contextStdout);
         if (last.stdout) process.stdout.write(last.stdout);
-        if (last.stderr) process.stderr.write(last.stderr);
+        // A spawn-unavailable `last` carries only the warning already written above.
+        if (last.stderr && last.failureKind !== 'spawn-unavailable') process.stderr.write(last.stderr);
         process.exitCode = last.code === 0 ? 0 : (lastIsFailClosed ? 2 : 0);
+        // FR-005(c): exiting 0 with an otherwise empty stdout — surface the warning
+        // to the host as a systemMessage. Plain context stdout is left untouched.
+        if (warnings && process.exitCode === 0 && !contextStdout && !last.stdout) {
+          process.stdout.write(JSON.stringify({ systemMessage: warnings.trimEnd() }));
+        }
       }
     }
   }

package/template_project/.claude/ukit/runtime/hook-payload-store.mjs

@@ -195,6 +195,7 @@ export async function sweepStalePayloadsAsync(dir, {
   now = Date.now,
   maxAgeMs = SWEEP_MAX_AGE_MS,
   maxEntries = SWEEP_MAX_ENTRIES,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -203,12 +204,18 @@ export async function sweepStalePayloadsAsync(dir, {
     return { sampled: true, scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  const eligibleNames = names.filter((name) => name.endsWith('.json') || name.endsWith('.tmp'));
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
   let removed = 0;
-  for (const name of names) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
-    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
     const filePath = path.join(dir, name);
     try {
       if ((await fsp.stat(filePath)).mtimeMs < cutoff) {
@@ -234,7 +241,7 @@ export async function maybeSweepStalePayloadsAsync(dir, {
 } = {}) {
   const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepStalePayloadsAsync(dir, { now, maxAgeMs, maxEntries });
+  return sweepStalePayloadsAsync(dir, { now, maxAgeMs, maxEntries, random });
 }
 
 // sweepStalePayloads(dir, {now, maxAgeMs, maxEntries}) -> {sampled, scanned, removed}
@@ -247,6 +254,7 @@ export function sweepStalePayloads(dir, {
   now = Date.now,
   maxAgeMs = SWEEP_MAX_AGE_MS,
   maxEntries = SWEEP_MAX_ENTRIES,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -255,12 +263,18 @@ export function sweepStalePayloads(dir, {
     return { sampled: true, scanned: 0, removed: 0 };
   }
   const cutoff = now() - maxAgeMs;
+  const eligibleNames = names.filter((name) => name.endsWith('.json') || name.endsWith('.tmp'));
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
   let removed = 0;
-  for (const name of names) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
-    if (!name.endsWith('.json') && !name.endsWith('.tmp')) continue;
     const filePath = path.join(dir, name);
     try {
       if (fs.statSync(filePath).mtimeMs < cutoff) {
@@ -287,5 +301,5 @@ export function maybeSweepStalePayloads(dir, {
 } = {}) {
   const p = Number.isFinite(probability) ? Math.min(1, Math.max(0, probability)) : sweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepStalePayloads(dir, { now, maxAgeMs, maxEntries });
+  return sweepStalePayloads(dir, { now, maxAgeMs, maxEntries, random });
 }

package/template_project/.claude/ukit/runtime/hook-process.mjs

@@ -18,15 +18,29 @@
 //     assumes group semantics.
 //
 // Contract (TASK-016 Interfaces):
-//   runHookProcess({command, args, input, deadlineMs, maxBuffer, ...}) ->
-//     Promise<{code, signal, stdout, stderr, failureKind, elapsedMs}>
+//   runHookProcess({command, args, input, deadlineMs, maxBuffer, spawnImpl, ...}) ->
+//     Promise<{code, signal, stdout, stderr, failureKind, elapsedMs, spawnFailed, errorCode}>
 //   failureKind: 'none' | 'deadline' | 'signal' | 'overflow' | 'error'
 //     'deadline' — this runner killed the child because the deadline expired
 //     'signal'   — the child died from a signal this runner did not send
 //     'overflow' — captured output exceeded maxBuffer; the tree was culled
 //     'error'    — the child never spawned (ENOENT and friends)
+//   spawnFailed: true only when the process was NEVER started — derived from child
+//     event order (an 'error' with no preceding 'spawn' event, or spawn() throwing
+//     synchronously), never from timing. An 'error' after 'spawn' is not a spawn failure.
+//   errorCode: the error's `code` (ENOENT, EINVAL, EPIPE, ...) or null.
+//   spawnImpl: injectable spawn function (default child_process.spawn) for tests.
+//
+// Windows .sh launching (resolveHookCommand / resolveWindowsBash):
+//   Windows cannot exec a `.sh` file directly, so on win32 a `.sh` hook is launched
+//   through an ABSOLUTE Git Bash path (never a bare `bash`, which Windows would look up
+//   in the child cwd first). Script paths are passed with forward slashes. POSIX spawns
+//   the script directly, unchanged. UKIT_HOOK_SHELL_PLATFORM overrides the platform seen
+//   by resolveHookCommand only (tests/diagnostics); UKIT_BASH_BIN overrides the bash path.
 
 import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
 
 // POSIX only. Windows kill() targets the direct child; process groups do not
 // exist there, so pretending otherwise would be a silent, wrong assumption.
@@ -41,6 +55,93 @@ export const KILL_GRACE_MS = 500;
 // runner past its own budget.
 const HARD_SETTLE_SLACK_MS = 2000;
 
+// Error codes meaning "the launcher itself could not be started".
+export const SPAWN_UNAVAILABLE_CODES = new Set([
+  'ENOENT',
+  'EINVAL',
+  'EACCES',
+  'EPERM',
+  'ENOEXEC',
+  'EFTYPE',
+]);
+
+/** Windows path -> forward slashes, so bash's dirname/$0 logic works. */
+export function toBashPath(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+const win32 = path.win32;
+
+function safeExists(exists, candidate) {
+  try {
+    return Boolean(exists(candidate));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Locate Git Bash on Windows. Returns an absolute path or null — never a bare
+ * or relative name (Windows resolves bare names in the child cwd first, which
+ * would let a planted bash.exe in a cloned repo run).
+ */
+export function resolveWindowsBash({ env = process.env, exists = fs.existsSync } = {}) {
+  const override = env.UKIT_BASH_BIN;
+  if (typeof override === 'string' && override && win32.isAbsolute(override)) return override;
+
+  const probe = (candidate) =>
+    typeof candidate === 'string' &&
+    candidate !== '' &&
+    win32.isAbsolute(candidate) &&
+    safeExists(exists, candidate);
+
+  const claude = env.CLAUDE_CODE_GIT_BASH_PATH;
+  if (probe(claude)) return claude;
+
+  const defaults = [
+    'C:\\Program Files\\Git\\bin\\bash.exe',
+    'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
+  ];
+  if (typeof env.LOCALAPPDATA === 'string' && env.LOCALAPPDATA) {
+    defaults.push(win32.join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'));
+  }
+  for (const candidate of defaults) {
+    if (probe(candidate)) return candidate;
+  }
+
+  const trimSlash = (p) => p.replace(/\\+$/, '').toLowerCase();
+  const system32 = trimSlash(win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32'));
+  const rawPath = env.PATH ?? env.Path ?? '';
+  for (const rawEntry of String(rawPath).split(';')) {
+    const entry = rawEntry.trim().replace(/^"+|"+$/g, '').trim();
+    if (!entry || !win32.isAbsolute(entry)) continue;
+    const norm = trimSlash(win32.normalize(entry));
+    if (norm === system32 || norm.endsWith('\\microsoft\\windowsapps')) continue;
+    const candidate = win32.join(entry, 'bash.exe');
+    if (safeExists(exists, candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Decide how to launch a hook script. win32 + `.sh` -> Git Bash (command may be
+ * null when none was found); everything else spawns the script directly.
+ */
+export function resolveHookCommand(
+  scriptPath,
+  { env = process.env, platform = env.UKIT_HOOK_SHELL_PLATFORM || process.platform, exists = fs.existsSync } = {},
+) {
+  if (typeof scriptPath !== 'string') return { command: '', args: [], viaBash: false };
+  if (platform === 'win32' && /\.sh$/i.test(scriptPath)) {
+    return {
+      command: resolveWindowsBash({ env, exists }),
+      args: [toBashPath(scriptPath)],
+      viaBash: true,
+    };
+  }
+  return { command: scriptPath, args: [], viaBash: false };
+}
+
 /**
  * Signal a process GROUP by pid (negative-pid kill). Swallows ESRCH — the
  * child may have exited between arming the timer and this call, or the pid may
@@ -73,18 +174,20 @@ export function runHookProcess({
   cwd,
   env = process.env,
   graceMs = KILL_GRACE_MS,
+  spawnImpl = spawn,
 }) {
   return new Promise((resolve) => {
     const startedAt = Date.now();
     let child;
     try {
-      child = spawn(command, args, {
+      child = spawnImpl(command, args, {
         cwd,
         env,
         // Detached ONLY on POSIX: the child becomes a group leader so the whole
         // tree dies together. Windows never gets a group assumption.
         detached: GROUP_KILL_SUPPORTED,
         stdio: ['pipe', 'pipe', 'pipe'],
+        windowsHide: true,
       });
     } catch (err) {
       resolve({
@@ -94,6 +197,8 @@ export function runHookProcess({
         stderr: String(err?.message || err),
         failureKind: 'error',
         elapsedMs: Date.now() - startedAt,
+        spawnFailed: true,
+        errorCode: err?.code ?? null,
       });
       return;
     }
@@ -104,6 +209,8 @@ export function runHookProcess({
     let hardSettled = false;
     let overflowed = false;
     let spawnError = null;
+    let spawned = false;
+    let spawnFailed = false;
     let stdoutBuf = Buffer.alloc(0);
     let stderrBuf = Buffer.alloc(0);
     const stdoutRef = { value: stdoutBuf };
@@ -146,6 +253,8 @@ export function runHookProcess({
         stderr: stderrRef.value.toString('utf8'),
         failureKind,
         elapsedMs: Date.now() - startedAt,
+        spawnFailed,
+        errorCode: spawnError?.code ?? null,
       });
     };
 
@@ -238,9 +347,16 @@ export function runHookProcess({
       }, deadlineMs + Math.max(0, graceMs) + HARD_SETTLE_SLACK_MS);
     }
 
+    // Event order, not timing, tells "never started" from "failed after start".
+    child.once('spawn', () => {
+      spawned = true;
+    });
     child.on('error', (err) => {
       // Spawn failures (ENOENT and friends) emit 'error' without 'close'.
-      if (!spawnError) spawnError = err;
+      if (!spawnError) {
+        spawnError = err;
+        spawnFailed = !spawned;
+      }
       finish();
     });
     child.on('close', () => {

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

@@ -231,6 +231,7 @@ export function sweepTelemetryDir(dir, {
   maxFiles = TELEMETRY_MAX_FILES,
   maxEntries = TELEMETRY_SWEEP_MAX_ENTRIES,
   maxRemovals = TELEMETRY_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -245,9 +246,15 @@ export function sweepTelemetryDir(dir, {
   // `entries.length` an under-count and `overflow` was always 0.
   const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = fs.statSync(path.join(dir, name));
@@ -283,7 +290,7 @@ export function maybeSweepTelemetryDir(dir, {
     ? Math.min(1, Math.max(0, probability))
     : telemetrySweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return { sampled: true, ...sweepTelemetryDir(dir, options) };
+  return { sampled: true, ...sweepTelemetryDir(dir, { ...options, random }) };
 }
 
 // BUG-C23-10: a bare `catch {}` around the sweep swallowed every failure — a

package/template_project/.claude/ukit/runtime/hook-telemetry.sh

@@ -17,10 +17,21 @@
 # without adding a node spawn to the hot path — and trap
 # ukit_hook_telemetry_finish on EXIT themselves.
 #
+# BUG-3 (TASK-003): inside hook-chain-runner.mjs the runner is the single
+# telemetry owner — it times every step and writes the hook-latency row itself.
+# It exports UKIT_HOOK_TELEMETRY_BY_RUNNER=1 to each child; when that marker is
+# 1 this file stays unarmed (UKIT_TEL_ARMED=0) and arm/finish return at once —
+# no mktemp, no node, no sleep watchdog. Direct invocations (Codex direct hooks,
+# debug runs) carry no marker and behave exactly as before.
+#
 # Missing runtime (pre-install tree) simply leaves telemetry off: wrappers
 # source this file with `|| true` and the armed flag stays unset.
 
-UKIT_TEL_ARMED=1
+if [ "${UKIT_HOOK_TELEMETRY_BY_RUNNER:-}" = "1" ]; then
+  UKIT_TEL_ARMED=0
+else
+  UKIT_TEL_ARMED=1
+fi
 UKIT_TEL_HOOK="$(basename "${BASH_SOURCE[1]:-$0}")"
 UKIT_TEL_RUNTIME_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 UKIT_TEL_START_FILE=""
@@ -52,6 +63,7 @@ ukit_tel_file_ms() {
 # one mktemp; a `node -e` clock read would cost ~30ms to measure milliseconds.
 # Always returns 0 — an unarmed hook must behave exactly like an unmeasured one.
 ukit_hook_telemetry_arm() {
+  [ "${UKIT_TEL_ARMED:-}" = "1" ] || return 0
   UKIT_TEL_START_FILE="$(mktemp "${TMPDIR:-/tmp}/ukit-tel-start.XXXXXX" 2>/dev/null)" || {
     UKIT_TEL_START_FILE=""
     return 0
@@ -65,6 +77,7 @@ ukit_hook_telemetry_finish() {
   # captured it before its own conditionals could reset $?); $? is only the
   # fallback for direct debug invocation.
   local rc="${UKIT_TEL_RC:-$?}"
+  [ "${UKIT_TEL_ARMED:-}" = "1" ] || return 0
   command -v node >/dev/null 2>&1 || return 0
   # UKIT_INPUT_FILE is a plain shell variable (never exported), so the staged
   # payload path — and through it the envelope start mtime — is passed here

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

@@ -455,6 +455,7 @@ export async function sweepTeeCache(dir, {
   maxFiles = TEE_MAX_FILES,
   maxEntries = TEE_SWEEP_MAX_ENTRIES,
   maxRemovals = TEE_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let dirents;
   try {
@@ -478,8 +479,17 @@ export async function sweepTeeCache(dir, {
   const cutoff = now() - maxAgeMs;
   const entries = [];
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  // Circular window at a random start so expired files beyond the first
+  // maxEntries readdir names are still reached (BUG-1: the head slice never
+  // age-pruned the tail). Non-finite random() falls back to start 0.
+  const L = eligibleNames.length;
+  const r = random();
+  const start = L > maxEntries
+    ? Math.min(L - 1, Math.max(0, Math.floor((Number.isFinite(r) ? r : 0) * L)))
+    : 0;
+  const windowSize = Math.min(maxEntries, L);
+  for (let i = 0; i < windowSize; i += 1) {
+    const name = eligibleNames[(start + i) % L];
     scanned += 1;
     try {
       const stats = await fs.stat(path.join(dir, name));
@@ -516,7 +526,7 @@ export async function maybeSweepTeeCache(dir, {
     ? Math.min(1, Math.max(0, probability))
     : teeSweepProbabilityFromEnv();
   if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
-  return sweepTeeCache(dir, options);
+  return sweepTeeCache(dir, { ...options, random });
 }
 
 async function persistRawOutput(projectRoot, {

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

@@ -273,6 +273,18 @@ function parseStructuredDecision(stdout) {
 
 function translateExecResult(scriptName, execResult) {
   const failureKind = typeof execResult?.failureKind === 'string' ? execResult.failureKind : null;
+  // The runner could not launch a .sh hook at all (win32 without bash): a loud warning,
+  // never a block, and no captured content travels with it.
+  if (failureKind === 'spawn-unavailable') {
+    const launchStderr = typeof execResult?.stderr === 'string' ? execResult.stderr : '';
+    return {
+      block: false,
+      warning: launchStderr.trim()
+        || `${scriptName} could not be launched and was skipped (spawn-unavailable) — install Git for Windows or set UKIT_BASH_BIN.`,
+      stdout: '',
+      stderr: launchStderr,
+    };
+  }
   // Infrastructure outcomes produce no verdict: no captured content travels with
   // them (overflowed stdout is truncated mid-stream and may embed secrets).
   const infrastructure = failureKind
@@ -454,6 +466,7 @@ async function sweepHookErrorsDir(dir, {
   maxFiles = HOOK_ERROR_MAX_FILES,
   maxEntries = HOOK_ERROR_SWEEP_MAX_ENTRIES,
   maxRemovals = HOOK_ERROR_SWEEP_MAX_REMOVALS,
+  random = Math.random,
 } = {}) {
   let names;
   try {
@@ -468,9 +481,15 @@ async function sweepHookErrorsDir(dir, {
   // `entries.length` an under-count and `overflow` was always 0.
   const eligibleNames = names.filter((name) => name.endsWith('.jsonl'));
   const entries = [];
+  // FR-002 (BUG-2): scan a circular window of at most maxEntries names from a
+  // random start so files past the first maxEntries are eventually pruned.
+  const total = eligibleNames.length;
+  const rawStart = total > maxEntries ? Math.floor(random() * total) : 0;
+  const start = Number.isFinite(rawStart) ? Math.min(total - 1, Math.max(0, rawStart)) : 0;
+  const limit = Math.min(maxEntries, total);
   let scanned = 0;
-  for (const name of eligibleNames) {
-    if (scanned >= maxEntries) break;
+  for (let i = 0; i < limit; i += 1) {
+    const name = eligibleNames[(start + i) % total];
     scanned += 1;
     try {
       const stats = await fs.promises.stat(path.join(dir, name));