@ngockhoale/ukit 2.6.0 → 2.6.2

package/templates/.claude/hooks/verification-guard.sh

@@ -11,7 +11,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "verification-guard"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "verification-guard"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -38,10 +46,14 @@ else
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
-  # already degrades on - the shared helper's truncate posture (R4.5).
-  if [ "$__ukit_size" -gt 2097152 ]; then
-    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit verification-guard: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/hooks/vision-router.sh

@@ -28,7 +28,15 @@ if source "$SCRIPT_DIR/../ukit/runtime/hook-input.sh" 2>/dev/null; then
 source "$SCRIPT_DIR/../ukit/runtime/hook-telemetry.sh" 2>/dev/null || true
   trap ukit_cleanup_hook_input EXIT
   # Bounded stdin (H01): stage before anything reads it; Node gets a path, never the payload.
-  ukit_stage_hook_input 2097152 truncate || exit 0
+  ukit_stage_hook_input 2097152 truncate
+  __ukit_main_stage_rc=$?
+  if [ "$__ukit_main_stage_rc" -ne 0 ]; then
+    # Infra failure during staging (mktemp/truncate): payload was never
+    # inspected — announce the degrade (SPEC §8), never a silent pass.
+    ukit_emit_input_degraded advisory "vision-router"
+  fi
+# BUG-C21-01: a truncated/stalled staged payload must be announced (SPEC §8), never silently passed.
+ukit_input_degraded && ukit_emit_input_degraded advisory "vision-router"
 else
   # Runtime helper missing (pre-install tree): the SAME bounded staging,
   # inline - `cat >/dev/null` used to block forever on a producer that never
@@ -55,10 +63,14 @@ else
   wait "$__ukit_waiter" 2>/dev/null
   exec 8<&-
   __ukit_size="$(wc -c < "$UKIT_INPUT_FILE" 2>/dev/null | tr -d '[:space:]')"
-  # A bounded cut (rc != 0) leaves a short payload that the JSON consumer
-  # already degrades on - the shared helper's truncate posture (R4.5).
-  if [ "$__ukit_size" -gt 2097152 ]; then
-    truncate -s 2097152 "$UKIT_INPUT_FILE" 2>/dev/null
+  if [ "$__ukit_stage_rc" -ne 0 ] || [ "$__ukit_size" -gt 2097152 ]; then
+    # BUG-C21-01 fallback parity (SPEC §8): a truncated/stalled staged payload
+    # must be announced, never silently acted on — same shape as the helper
+    # path's ukit_emit_input_degraded.
+    rm -f "$UKIT_INPUT_FILE"
+    UKIT_INPUT_FILE=""
+    printf '%s\n' '{"systemMessage":"UKit vision-router: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input."}'
+    exit 0
   fi
   trap '[ -n "$UKIT_INPUT_FILE" ] && rm -f "$UKIT_INPUT_FILE"' EXIT
 fi

package/templates/.claude/settings.json

@@ -103,7 +103,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-allow-bash.sh\"",
-            "timeout": 8
+            "timeout": 12
           },
           {
             "type": "command",
@@ -124,6 +124,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/context-hardcap-gate.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/verification-guard.sh\"",
+            "timeout": 8
           }
         ]
       }
@@ -135,7 +140,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
-            "timeout": 4
+            "timeout": 8
           }
         ]
       },
@@ -150,12 +155,12 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
-            "timeout": 4
+            "timeout": 8
           },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/task-watchdog.sh\"",
-            "timeout": 4
+            "timeout": 8
           }
         ]
       },
@@ -165,12 +170,12 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/compress-output.sh\"",
-            "timeout": 8
+            "timeout": 12
           },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/record-execution.sh\"",
-            "timeout": 4
+            "timeout": 8
           }
         ]
       }
@@ -191,7 +196,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\"",
-            "timeout": 8
+            "timeout": 12
           },
           {
             "type": "command",
@@ -207,7 +212,7 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/completion-gate.sh\"",
-            "timeout": 4
+            "timeout": 8
           }
         ]
       }
@@ -234,12 +239,12 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/auto-prune-bash.sh\"",
-            "timeout": 8
+            "timeout": 12
           },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/reset-compact-pressure.sh\"",
-            "timeout": 8
+            "timeout": 12
           },
           {
             "type": "command",

package/templates/.claude/ukit/index/provision-worktree.mjs

@@ -19,6 +19,27 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+// FR-005 (BUG-C21-08): every spawnSync below must carry an explicit timeout — a
+// wedged `git` (hung credential helper, stalled volume) otherwise blocks this
+// process forever. 15s is generous for the two metadata probes used here;
+// UKIT_PROVISION_GIT_TIMEOUT_MS overrides it for tests and pathological hosts.
+const GIT_CALL_TIMEOUT_MS = (() => {
+  const raw = Number(process.env.UKIT_PROVISION_GIT_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : 15000;
+})();
+
+// Runs a git probe with the bounded budget. Returns the spawnSync result, or
+// { error, timedOut: true } shape already present on result.error when the
+// child was killed for exceeding GIT_CALL_TIMEOUT_MS.
+function gitProbe(args, root) {
+  const res = spawnSync('git', ['-C', root, ...args], {
+    encoding: 'utf8',
+    timeout: GIT_CALL_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+  });
+  return res;
+}
+
 function fail(msg) {
   process.stderr.write(`provision-worktree: ${msg}\n`);
   process.exit(1);
@@ -86,7 +107,8 @@ if (mainPkg && wtPkg) {
 // idempotent, untracked local-metadata change — never part of any commit.
 function excludeNodeModulesFromGit(root) {
   try {
-    const common = spawnSync('git', ['-C', root, 'rev-parse', '--git-common-dir'], { encoding: 'utf8' });
+    const common = gitProbe(['rev-parse', '--git-common-dir'], root);
+    if (common.error) return false; // wedged/timed-out git — best effort, skip the exclude
     if (common.status !== 0) return false; // not a git repo (e.g. unit-test fixture) — best effort
     const gitCommonDir = path.resolve(root, common.stdout.trim());
     const excludePath = path.join(gitCommonDir, 'info', 'exclude');
@@ -109,7 +131,13 @@ function excludeNodeModulesFromGit(root) {
 // worktree's tracked file with main's unreviewed local state.
 function trackedClaudeFiles(root) {
   try {
-    const res = spawnSync('git', ['-C', root, 'ls-files', '--', '.claude'], { encoding: 'utf8' });
+    const res = gitProbe(['ls-files', '--', '.claude'], root);
+    // A timed-out/wedged git must surface loudly: returning an empty set here
+    // would let the copy clobber a git-tracked file under .claude/. A non-zero
+    // status only means "not a git repo" (unit-test fixture) and stays benign.
+    if (res.error) {
+      fail(`git ls-files probe failed (${res.error.code || res.error.message || res.error}); cannot verify tracked .claude files — aborting rather than risk clobbering them`);
+    }
     if (res.status !== 0 || !res.stdout) return new Set();
     return new Set(res.stdout.split('\n').map((s) => s.trim()).filter(Boolean));
   } catch {

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

@@ -115,6 +115,99 @@ function crashCounterPath(projectRoot) {
   );
 }
 
+// --- exec-ledger dir bound (BUG-C21-11, FR-006) -------------------------------
+// One ledger file per session identity plus journals/quarantines used to
+// accumulate forever (no GC, no sweep). The sweep is SAMPLED off the mutation
+// path (~1/16 locked writes, UKIT_LEDGER_SWEEP_PROBABILITY to force/disable)
+// and BOUNDED — <= maxEntries stats and <= maxRemovals unlinks per sweep, so a
+// pre-existing oversized dir is amortized down instead of stalling a hook.
+// Count-cap removals only touch files older than LEDGER_COUNT_CAP_MIN_AGE_MS so
+// a live session's ledger/journal is never evicted by recency ordering.
+const LEDGER_SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const LEDGER_SWEEP_MAX_ENTRIES = 128;
+const LEDGER_SWEEP_MAX_REMOVALS = 64;
+const LEDGER_MAX_FILES = 200;
+const LEDGER_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+const LEDGER_COUNT_CAP_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+
+function ledgerSweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_LEDGER_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return LEDGER_SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+// sweepExecLedgerDir(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
+//   { scanned, removed }
+//
+// Removes ledger/journal/quarantine files older than maxAgeMs; while the dir
+// exceeds maxFiles, removes the oldest scanned entries that are ALSO older than
+// LEDGER_COUNT_CAP_MIN_AGE_MS — fresh files for live sessions are never evicted.
+export async function sweepExecLedgerDir(dir, {
+  now = Date.now,
+  maxAgeMs = LEDGER_MAX_AGE_MS,
+  maxFiles = LEDGER_MAX_FILES,
+  maxEntries = LEDGER_SWEEP_MAX_ENTRIES,
+  maxRemovals = LEDGER_SWEEP_MAX_REMOVALS,
+} = {}) {
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  const countCapCutoff = now() - LEDGER_COUNT_CAP_MIN_AGE_MS;
+  const entries = [];
+  let scanned = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    try {
+      const stats = await fs.stat(path.join(dir, name));
+      if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
+    } catch { /* raced away — fine */ }
+  }
+  entries.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first
+  // Overflow counts eligible FILES only — foreign entries (`.lock` dirs, other
+  // state files sharing the dir) inflate `names.length` and would evict real
+  // ledgers while the dir is actually under the cap.
+  const overflow = Math.max(0, entries.length - maxFiles);
+  let removed = 0;
+  for (const entry of entries) {
+    if (removed >= maxRemovals) break;
+    const stale = entry.mtimeMs < cutoff;
+    const evictable = entry.mtimeMs < countCapCutoff;
+    // Journals/quarantines are the ONLY copy of a fail-closed event until
+    // drained, and the crash counter is stuck-loop state — evicting them by
+    // recency silently loses receipts the protocol promises to keep. They
+    // still age out via the 30d stale cutoff, never via the count cap.
+    const receiptProtected = entry.name.endsWith('.journal')
+      || entry.name.endsWith('.quarantine')
+      || entry.name === 'gate-crash-counter.json';
+    if (stale || (removed < overflow && evictable && !receiptProtected)) {
+      try {
+        await fs.rm(path.join(dir, entry.name), { force: true });
+        removed += 1;
+      } catch { /* raced away — fine */ }
+    }
+  }
+  return { scanned, removed };
+}
+
+// Sampled gate — by default only ~1 in 16 ledger mutations pays for a bounded
+// sweep at all. Advisory: a sweep failure must never lose a ledger event.
+export async function maybeSweepExecLedgerDir(dir, {
+  probability,
+  random = Math.random,
+  ...options
+} = {}) {
+  const p = Number.isFinite(probability)
+    ? 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)) };
+}
+
 function resumeIntentPath(projectRoot, sessionId) {
   return path.join(
     projectRoot,
@@ -1082,7 +1175,12 @@ export async function recordLedgerEvent(event, {
     if (drained.commit) await drained.commit();
     return { committed: true, eventId, value, drained: drained.applied, quarantined: drained.quarantined };
   });
-  if (outcome.ok) return outcome.value;
+  if (outcome.ok) {
+    // Sampled bounded dir sweep (BUG-C21-11): runs outside the ledger lock so a
+    // contended acquisition never pays sweep latency. Advisory — never throws.
+    try { await maybeSweepExecLedgerDir(path.dirname(target)); } catch { /* advisory */ }
+    return outcome.value;
+  }
 
   // Fail-closed: the acquisition budget expired or the wait aborted. The main ledger is
   // NEVER mutated unlocked — journal the event once; the next acquired lock reconciles it.

package/templates/.claude/ukit/runtime/hook-input.sh

@@ -121,6 +121,31 @@ ukit_stage_hook_input() {
   return 0
 }
 
+# BUG-C21-01 (SPEC §8 announcement contract): a staged truncation or staging
+# stall means the hook is about to inspect an INCOMPLETE payload. Gated hooks
+# must announce that instead of silently passing on input they never fully
+# read:
+#   ukit_input_degraded                    — predicate: staging cut the payload
+#   ukit_emit_input_degraded <posture> <hook-name>
+#       failclosed → PreToolUse "ask" decision JSON on stdout, then exit 2
+#                    (fail-closed gates defer the uninspectable call to a human)
+#       advisory   → systemMessage degrade notice on stdout, then exit 0
+# Both shapes use the §8 contract keys only; payload bytes are never echoed.
+ukit_input_degraded() {
+  [ "${UKIT_INPUT_TRUNCATED:-0}" = "1" ] || [ "${UKIT_HOOK_INPUT_STALLED:-0}" = "1" ]
+}
+
+ukit_emit_input_degraded() {
+  local posture="${1:-advisory}" hook_name="${2:-hook}"
+  if [ "$posture" = "failclosed" ]; then
+    printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"UKit could not fully read this tool-call payload (stdin staging was cut at the deadline/size bound), so ${hook_name} cannot prove it safe. UKit defers this to a human decision.\"}}"
+    echo "BLOCKED: ${hook_name} could not inspect a truncated/stalled payload; deferred to human." >&2
+    exit 2
+  fi
+  printf '%s\n' "{\"systemMessage\":\"UKit ${hook_name}: tool-call payload was truncated or stalled during stdin staging; skipped this pass rather than act on incomplete input.\"}"
+  exit 0
+}
+
 ukit_cleanup_hook_input() {
   # TASK-019: emit the telemetry finish marker while the staged payload file
   # still exists (its mtime is the envelope start). Strictly advisory — the

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

@@ -87,8 +87,8 @@ export function telemetryDirFor(projectRoot) {
 }
 
 // Bounded work on THIS session's file only: stat, at most one read of a file
-// already capped at maxBytes, one rewrite of the kept half. The append path
-// never lists or sweeps the telemetry directory.
+// already capped at maxBytes, one rewrite of the kept half. Directory growth is
+// bounded separately by the sampled sweepTelemetryDir below (BUG-C21-10).
 function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
   let size = 0;
   try {
@@ -115,6 +115,87 @@ function rotateIfNeeded(filePath, incomingBytes, maxBytes) {
   }
 }
 
+// --- hook-latency dir bound (BUG-C21-10, FR-006) -----------------------------
+// Per-session files were byte-capped but the directory was never swept, so file
+// count grew with every session. The sweep is SAMPLED off the append path
+// (default ~1/16 appends, UKIT_TELEMETRY_SWEEP_PROBABILITY to force/disable)
+// and BOUNDED — at most maxEntries stats and maxRemovals unlinks per sweep, so
+// a pre-existing oversized dir is amortized down rather than stalling a hook.
+const TELEMETRY_SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const TELEMETRY_SWEEP_MAX_ENTRIES = 128;
+const TELEMETRY_SWEEP_MAX_REMOVALS = 64;
+const TELEMETRY_MAX_FILES = 200;
+const TELEMETRY_MAX_AGE_MS = 14 * 24 * 60 * 60 * 1000;
+
+function telemetrySweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_TELEMETRY_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return TELEMETRY_SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+// sweepTelemetryDir(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
+//   { scanned, removed }
+//
+// Removes .jsonl entries older than maxAgeMs; while the dir exceeds maxFiles,
+// removes the oldest scanned entries (bounded by maxRemovals). Fresh session
+// files under the count cap are never touched.
+export function sweepTelemetryDir(dir, {
+  now = Date.now,
+  maxAgeMs = TELEMETRY_MAX_AGE_MS,
+  maxFiles = TELEMETRY_MAX_FILES,
+  maxEntries = TELEMETRY_SWEEP_MAX_ENTRIES,
+  maxRemovals = TELEMETRY_SWEEP_MAX_REMOVALS,
+} = {}) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return { scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  const entries = [];
+  let scanned = 0;
+  for (const name of names) {
+    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 });
+    } catch { /* raced away — fine */ }
+  }
+  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
+  // actually under the cap.
+  const overflow = Math.max(0, entries.length - maxFiles);
+  let removed = 0;
+  for (const entry of entries) {
+    if (removed >= maxRemovals) break;
+    if (removed < overflow || entry.mtimeMs < cutoff) {
+      try {
+        fs.rmSync(path.join(dir, entry.name), { force: true });
+        removed += 1;
+      } catch { /* raced away — fine */ }
+    }
+  }
+  return { scanned, removed };
+}
+
+// Sampled gate — same shape as the payload-store sweep: by default ~1 in 16
+// appends pays for a bounded sweep at all.
+export function maybeSweepTelemetryDir(dir, {
+  probability,
+  random = Math.random,
+  ...options
+} = {}) {
+  const p = Number.isFinite(probability)
+    ? Math.min(1, Math.max(0, probability))
+    : telemetrySweepProbabilityFromEnv();
+  if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
+  return { sampled: true, ...sweepTelemetryDir(dir, options) };
+}
+
 export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
   try {
     if (!row || typeof row !== 'object') return false;
@@ -124,6 +205,9 @@ export function appendTelemetryRow(projectRoot, sessionId, row, options = {}) {
     const line = `${JSON.stringify(row)}\n`;
     rotateIfNeeded(filePath, Buffer.byteLength(line, 'utf8'), capBytes(options.maxBytes));
     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 */ }
     return true;
   } catch {
     // Advisory: an unwritable or corrupt telemetry target must never alter a

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

@@ -376,6 +376,90 @@ function buildRecoveryHintSummary(summary, rawPath, { tokensBefore = 0 } = {}) {
   return null;
 }
 
+// --- tee/ cache bound (BUG-C21-07, FR-006) -----------------------------------
+// persistRawOutput used to write one preserved-output file per compression and
+// nothing ever deleted from tee/ (live dir: 3,642 files / 26M). The bound below
+// mirrors the hook-payload-store sweep pattern: sweeps are SAMPLED off the hot
+// path (default ~1/16 writes, UKIT_TEE_SWEEP_PROBABILITY to force/disable) and
+// BOUNDED — at most TEE_SWEEP_MAX_ENTRIES stats and TEE_SWEEP_MAX_REMOVALS
+// unlinks per sweep, so a pre-existing oversized dir is amortized down instead
+// of stalling a single PostToolUse.
+const TEE_SWEEP_PROBABILITY_DEFAULT = 1 / 16;
+const TEE_SWEEP_MAX_ENTRIES = 128;
+const TEE_SWEEP_MAX_REMOVALS = 64;
+const TEE_MAX_FILES = 500;
+const TEE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+function teeSweepProbabilityFromEnv() {
+  const raw = Number(process.env.UKIT_TEE_SWEEP_PROBABILITY);
+  if (!Number.isFinite(raw)) return TEE_SWEEP_PROBABILITY_DEFAULT;
+  return Math.min(1, Math.max(0, raw));
+}
+
+// sweepTeeCache(dir, {now, maxAgeMs, maxFiles, maxEntries, maxRemovals}) ->
+//   { sampled, scanned, removed }
+//
+// Removes entries older than maxAgeMs; if the directory still exceeds maxFiles
+// (count from the single readdir listing), removes the oldest scanned entries —
+// capped by maxRemovals — so each sampled sweep makes bounded progress toward
+// the count cap on a pre-existing oversized dir.
+export async function sweepTeeCache(dir, {
+  now = Date.now,
+  maxAgeMs = TEE_MAX_AGE_MS,
+  maxFiles = TEE_MAX_FILES,
+  maxEntries = TEE_SWEEP_MAX_ENTRIES,
+  maxRemovals = TEE_SWEEP_MAX_REMOVALS,
+} = {}) {
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return { sampled: true, scanned: 0, removed: 0 };
+  }
+  const cutoff = now() - maxAgeMs;
+  const entries = [];
+  let scanned = 0;
+  for (const name of names) {
+    if (scanned >= maxEntries) break;
+    scanned += 1;
+    try {
+      const stats = await fs.stat(path.join(dir, name));
+      if (stats.isFile()) entries.push({ name, mtimeMs: stats.mtimeMs });
+    } catch { /* raced away — fine */ }
+  }
+  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
+  // actually under the cap.
+  const overflow = Math.max(0, entries.length - maxFiles);
+  let removed = 0;
+  for (const entry of entries) {
+    if (removed >= maxRemovals) break;
+    if (removed < overflow || entry.mtimeMs < cutoff) {
+      try {
+        await fs.rm(path.join(dir, entry.name), { force: true });
+        removed += 1;
+      } catch { /* raced away — fine */ }
+    }
+  }
+  return { sampled: true, scanned, removed };
+}
+
+// Sampled gate identical in shape to maybeSweepStalePayloads: only ~1 in 16
+// writes pays for a bounded sweep at all. UKIT_TEE_SWEEP_PROBABILITY (clamped to
+// [0,1]) forces or disables sweeping without editing code.
+export async function maybeSweepTeeCache(dir, {
+  probability,
+  random = Math.random,
+  ...options
+} = {}) {
+  const p = Number.isFinite(probability)
+    ? Math.min(1, Math.max(0, probability))
+    : teeSweepProbabilityFromEnv();
+  if (random() >= p) return { sampled: false, scanned: 0, removed: 0 };
+  return sweepTeeCache(dir, options);
+}
+
 async function persistRawOutput(projectRoot, {
   command = '',
   summary = '',
@@ -402,6 +486,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(() => {});
 
   return {
     rawSaved: true,