@ngockhoale/ukit 3.4.20 → 3.4.22

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.22 - 2026-10-07
+
+**Windows: `.sh` hooks no longer deny every Edit/Write/Bash.**
+- `.sh` hooks are now launched through Git for Windows bash: `UKIT_BASH_BIN` → `CLAUDE_CODE_GIT_BASH_PATH` →
+  default Git install paths → absolute `PATH` entries. WSL's `bash.exe` and a cwd `bash.exe` are never used.
+- On Windows a `.sh` hook whose bash cannot be found or started is reported as `spawn-unavailable` and warned
+  instead of denying every Edit/Write/Bash. POSIX behaviour is unchanged; timeouts, real blocks, missing gate
+  files and `block-dangerous.sh` stay fail-closed.
+- `ukit doctor` flags Windows hook launch failures.
+- `*.sh` is pinned to LF (repo `.gitattributes` and a shipped `.claude/.gitattributes`) so a CRLF checkout cannot
+  break hook scripts. Troubleshooting added to `docs/INSTALL.md`.
+
+## 3.4.21 - 2026-10-07
+
+**Hook runtime no longer burns CPU/disk on every tool call** (five measured bugs, C95).
+- Retention sweeps (tee cache, hook-latency telemetry, execution ledger, hook payloads, omp hook errors) only
+  looked at the first 128 directory entries, so old files past that window were never pruned and the
+  over-cap rule deleted newer files instead. The scan window now rotates.
+- Chained `.sh` hooks no longer each spawn their own `node hook-telemetry.mjs --finish`; `hook-chain-runner.mjs`
+  writes the per-step rows (an Edit chain went from 11 node spawns to 5, same telemetry rows).
+- `unic-decision` now honours its persisted circuit breaker (closed/open/half-open, fail-open): a rejected key
+  or dead endpoint no longer costs a failed call on every prompt.
+- The context hard-cap gate probes the transcript incrementally instead of re-reading the last 4 MB and
+  rewriting `compact-pressure.json` on ~95% of calls; invalid persisted probe state falls back to a full scan.
+
 ## 3.4.20 - 2026-10-06
 
 **`ukit update` now displays the NEW version.** The running process is the old code, so the

package/manifests/documentation.yaml

@@ -707,6 +707,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: non-.md entry — exists for FR-002 manifest consistency
+  - id: tpl-claude-gitattributes
+    path: template_project/.claude/.gitattributes
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: template_project/.claude/.gitattributes
+    merge_strategy: skip
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: non-.md entry — keeps hook *.sh LF on Windows autocrlf checkouts; exists for FR-002 manifest consistency
 
   # ── repo mirrors (derived from template_project/) ───────────────────────────────
   - id: mirror-claude-dir

package/manifests/platform.full.yaml

@@ -1511,6 +1511,19 @@ items:
     packs:
       - core
 
+  # Ships `*.sh text eol=lf` inside .claude/ only (never the user's root .gitattributes) so
+  # a Windows autocrlf checkout cannot turn hook scripts into CRLF that bash rejects.
+  - id: claude-gitattributes
+    type: config
+    sourceTemplate: .claude/.gitattributes
+    targetPath: .claude/.gitattributes
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-reset-compact-pressure
     type: hook
     sourceTemplate: .claude/hooks/reset-compact-pressure.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.20",
+  "version": "3.4.22",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/src/core/hookChainDoctor.js

@@ -24,12 +24,31 @@ const FAILURE_OUTCOMES = new Set([
   'output-overflow',
   'error',
   'signal',
+  'spawn-unavailable',
 ]);
 
 // The pre-O6 remedy, kept verbatim: a failure with no gate evidence must read
 // exactly as it did before escalation existed (SPEC §FR-012).
+// SPEC §FR-007: launch failures only arise on win32 (the runner emits
+// `spawn-unavailable` from its bash-launcher path), so there is one remedy.
+const LAUNCH_REMEDY = 'Windows cannot execute .sh hooks directly — install Git for Windows so C:\\Program Files\\Git\\bin\\bash.exe exists, or set UKIT_BASH_BIN to the full path of bash.exe, then restart the session.';
+
+// Legacy pre-fix win32 rows recorded a failed .sh launch as a plain `error`
+// that finished almost instantly.
+const LEGACY_LAUNCH_FAILURE_MAX_MS = 10;
+
 const BASE_REMEDY = 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.';
 
+function isLaunchFailure(entry, platform) {
+  if (!entry || typeof entry !== 'object') return false;
+  if (typeof entry.scriptName !== 'string' || !entry.scriptName.toLowerCase().endsWith('.sh')) return false;
+  if (entry.failureKind === 'spawn-unavailable') return true;
+  return platform === 'win32'
+    && entry.failureKind === 'error'
+    && typeof entry.elapsedMs === 'number'
+    && entry.elapsedMs < LEGACY_LAUNCH_FAILURE_MAX_MS;
+}
+
 function telemetryDirFor(projectRoot) {
   return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
 }
@@ -78,7 +97,7 @@ async function tailLines(filePath, size) {
   }
 }
 
-export async function inspectHookChainHealth({ projectRoot, now = Date.now() } = {}) {
+export async function inspectHookChainHealth({ projectRoot, now = Date.now(), platform = process.platform } = {}) {
   const label = 'hook-chain health';
 
   // Never-fatal posture extends to malformed input: a missing projectRoot is
@@ -106,6 +125,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   // evidence shapes that prove it, collected in the same pass that counts
   // outcomes so no second read of the rows is needed.
   const gateFailures = new Set();
+  const launchFailures = new Set();
   let budgetExhaustedChains = 0;
 
   for (const file of files) {
@@ -130,6 +150,14 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       const outcome = typeof row.outcome === 'string' && row.outcome.length > 0 ? row.outcome : 'ok';
       counts[outcome] = (counts[outcome] ?? 0) + 1;
 
+      // .sh launch failures are collected from EVERY row (an exit-code row can
+      // still carry one); they are a different signal from a gate that ran and failed.
+      if (Array.isArray(row.scripts)) {
+        for (const entry of row.scripts) {
+          if (isLaunchFailure(entry, platform)) launchFailures.add(entry.scriptName);
+        }
+      }
+
       // Escalation evidence is only ever read off a FAILING row — a gate that
       // ran fine is not evidence of anything, and SPEC §FR-012 scopes the
       // budget signal to a non-ok row ("a non-ok row ... escalates only when
@@ -155,6 +183,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
         if (!entry || typeof entry !== 'object') continue;
         if (entry.failClosed !== true) continue;
         if (typeof entry.failureKind !== 'string' || entry.failureKind === 'ok') continue;
+        if (entry.failureKind === 'spawn-unavailable') continue; // reported as a launch failure
         gateFailures.add(typeof entry.scriptName === 'string' ? entry.scriptName : 'unknown');
       }
     }
@@ -177,7 +206,7 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
     .filter((key) => FAILURE_OUTCOMES.has(key) && counts[key] > 0)
     .sort();
 
-  if (failureKinds.length === 0) {
+  if (failureKinds.length === 0 && launchFailures.size === 0) {
     return {
       label,
       passed: true,
@@ -190,7 +219,9 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   }
 
   const breakdown = failureKinds.map((kind) => `${kind}=${counts[kind]}`).join(', ');
-  const baseDetail = `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`;
+  const baseDetail = failureKinds.length > 0
+    ? `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`
+    : `${counts.rowsScanned} chain row(s) scanned`;
 
   // O6 (SPEC §FR-012): escalate only when a failure actually landed ON a gate —
   // a gate that merely ran is not evidence. The escalation is purely additive:
@@ -207,6 +238,11 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       `A fail-closed gate actually failed (${gateList.join(', ')}) — that is a real budget or path problem, not a slow advisory hook; widen the failing gate's budget or fix that step.`,
     );
   }
+  const launchList = [...launchFailures].sort();
+  if (launchList.length > 0) {
+    escalations.push(`.sh hook(s) could not be launched: ${launchList.join(', ')}`);
+    advices.push(LAUNCH_REMEDY);
+  }
   if (budgetExhaustedChains > 0) {
     escalations.push(`${budgetExhaustedChains} chain row(s) exhausted the total budget`);
     advices.push(

package/src/core/output/index.js

@@ -386,6 +386,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 {
@@ -404,8 +405,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));
@@ -439,7 +449,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/.claude/.gitattributes

@@ -0,0 +1,2 @@
+# Hook scripts must stay LF: a CRLF checkout makes bash fail on "\r".
+*.sh text eol=lf

package/template_project/.claude/ukit/index/route-task.mjs

@@ -1771,7 +1771,18 @@ export async function runRouteDecisionShadow({
 
   let result = null;
   const startedAt = now();
+  // FR-004: skip the CLI spawn while the persisted decision circuit is open
+  // (half-open does not skip — the CLI claims the probe). Any failure = closed.
+  let circuitOpen = false;
   try {
+    const { isDecisionCircuitOpen } = await import('./unic-decision.mjs');
+    circuitOpen = isDecisionCircuitOpen(rootDir, { config, now }) === true;
+  } catch {
+    circuitOpen = false;
+  }
+  if (circuitOpen) {
+    result = { status: 'unavailable', fallbackCode: 'circuit-open' };
+  } else try {
     const spawned = spawnImpl(
       process.execPath,
       [cliPath, '--root', rootDir],

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -716,6 +716,99 @@ function outcome(status, extra = {}) {
   return { status, finishReason: null, answers: [], ...extra };
 }
 
+// --- Persisted circuit breaker (SPEC FR-004 / BUG-4) -----------------------
+// The hook path spawns a fresh process per prompt, so an in-memory breaker is
+// useless. State lives in <projectRoot>/.ukit/storage/cache/decision-circuit.json.
+// Advisory + best-effort: every read/parse/write error degrades to "closed".
+const CIRCUIT_DEFAULTS = { failureThreshold: 3, cooldownMs: 30000 };
+
+function circuitFile(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'decision-circuit.json');
+}
+
+function circuitConfig(config) {
+  const raw = decisionPlaneConfig(config).circuitBreaker;
+  const pick = (value, fallback) =>
+    Number.isFinite(value) && value >= 1 ? value : fallback;
+  return {
+    failureThreshold: pick(raw?.failureThreshold, CIRCUIT_DEFAULTS.failureThreshold),
+    cooldownMs: pick(raw?.cooldownMs, CIRCUIT_DEFAULTS.cooldownMs),
+  };
+}
+
+function writeCircuitState(projectRoot, next, now) {
+  const file = circuitFile(projectRoot);
+  const tmp = `${file}.${process.pid}.tmp`;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(
+      tmp,
+      JSON.stringify({
+        schemaVersion: 1,
+        consecutiveFailures: next.consecutiveFailures,
+        openedAt: next.openedAt,
+        lastFallbackCode: next.lastFallbackCode,
+        updatedAt: now,
+      }),
+      'utf8',
+    );
+    fs.renameSync(tmp, file);
+  } catch {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best-effort */ }
+  }
+}
+
+export function readDecisionCircuit(projectRoot, { config = null, now = () => Date.now() } = {}) {
+  const closed = { state: 'closed', consecutiveFailures: 0, openedAt: null, lastFallbackCode: null };
+  if (typeof projectRoot !== 'string' || projectRoot === '') return closed;
+  try {
+    const raw = JSON.parse(fs.readFileSync(circuitFile(projectRoot), 'utf8'));
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return closed;
+    const consecutiveFailures =
+      Number.isInteger(raw.consecutiveFailures) && raw.consecutiveFailures >= 0
+        ? raw.consecutiveFailures
+        : 0;
+    const lastFallbackCode =
+      typeof raw.lastFallbackCode === 'string' ? raw.lastFallbackCode : null;
+    const base = { consecutiveFailures, openedAt: null, lastFallbackCode };
+    if (!Number.isFinite(raw.openedAt)) return { state: 'closed', ...base };
+    // Negative delta = clock moved backwards / future stamp: never pin open.
+    const delta = now() - raw.openedAt;
+    if (!(delta >= 0)) return { state: 'closed', ...base };
+    const state = delta < circuitConfig(config).cooldownMs ? 'open' : 'half-open';
+    return { state, ...base, openedAt: raw.openedAt };
+  } catch {
+    return closed;
+  }
+}
+
+export function isDecisionCircuitOpen(projectRoot, opts = {}) {
+  return readDecisionCircuit(projectRoot, opts).state === 'open';
+}
+
+function recordCircuitOutcome(projectRoot, prior, kind, { config, now, fallbackCode = null }) {
+  if (typeof projectRoot !== 'string' || projectRoot === '') return;
+  try {
+    const at = now();
+    if (kind === 'success') {
+      if (prior.consecutiveFailures === 0 && prior.openedAt === null) return;
+      writeCircuitState(projectRoot, {
+        consecutiveFailures: 0, openedAt: null, lastFallbackCode: null,
+      }, at);
+      return;
+    }
+    const consecutiveFailures = prior.consecutiveFailures + 1;
+    const reopen =
+      prior.state === 'half-open' ||
+      consecutiveFailures >= circuitConfig(config).failureThreshold;
+    writeCircuitState(projectRoot, {
+      consecutiveFailures,
+      openedAt: reopen ? at : null,
+      lastFallbackCode: fallbackCode,
+    }, at);
+  } catch { /* advisory */ }
+}
+
 /**
  * Send one C13 batch over the configured gateway. `batch` =
  * {batchId?, boundary?, statePacket, questions, deadlineMs?}. Returns a typed
@@ -798,6 +891,24 @@ export async function requestBatch(batch, {
       detail: error?.message ?? String(error),
     });
   }
+  // Persisted breaker (FR-004): consulted only after all local validation, so
+  // those outcomes keep their order and never touch the state file.
+  const breakerOn = typeof projectRoot === 'string' && projectRoot !== '';
+  const circuit = breakerOn
+    ? readDecisionCircuit(projectRoot, { config, now })
+    : null;
+  if (circuit?.state === 'open') {
+    return outcome('unavailable', {
+      batchId: batch?.batchId ?? null,
+      checkpoint,
+      fallbackCode: 'circuit-open',
+      circuitCause: circuit.lastFallbackCode,
+    });
+  }
+  if (circuit?.state === 'half-open') {
+    // Claim the probe: concurrent processes now see 'open' until the cooldown.
+    writeCircuitState(projectRoot, { ...circuit, openedAt: now() }, now());
+  }
   let fingerprint = requestFingerprint(body);
   const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
   const deadlineMs = Number.isFinite(batch?.deadlineMs) ? batch.deadlineMs : timeoutMs;
@@ -889,6 +1000,7 @@ export async function requestBatch(batch, {
     }
 
     const result = parseBatchResponse(parsed, questions);
+    if (breakerOn) recordCircuitOutcome(projectRoot, circuit, 'success', { config, now });
     return {
       batchId: batch?.batchId ?? null,
       checkpoint,
@@ -900,11 +1012,18 @@ export async function requestBatch(batch, {
     };
   }
 
-  return outcome(lastError ?? 'unavailable', {
+  const finalStatus = lastError ?? 'unavailable';
+  const finalCode =
+    lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error');
+  if (breakerOn && (finalStatus === 'timeout' || finalStatus === 'unavailable')) {
+    recordCircuitOutcome(projectRoot, circuit, 'failure', {
+      config, now, fallbackCode: finalCode,
+    });
+  }
+  return outcome(finalStatus, {
     batchId: batch?.batchId ?? null,
     checkpoint,
-    fallbackCode:
-      lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error'),
+    fallbackCode: finalCode,
     requestFingerprint: fingerprint,
   });
 }

package/template_project/.claude/ukit/runtime/compact-threshold.mjs

@@ -557,12 +557,83 @@ const BOUNDARY_TAIL_BYTES = 4 * 1024 * 1024;
 // 4s hook budget on a slow volume.
 const TRANSCRIPT_BOUNDARY_PROBE_TTL_MS = 2_000;
 
+// Persist a probe update only after this many unpersisted bytes were scanned: transcripts grow
+// on every tool call, but rewriting compact-pressure.json (70-110KB) each time is the cost
+// the incremental probe exists to avoid.
+const PROBE_PERSIST_DELTA_BYTES = 256 * 1024;
+
 function normalizeTranscriptProbe(value) {
   if (!value || typeof value !== 'object' || typeof value.path !== 'string' || !value.path) return null;
   const checkedAt = finiteNumber(value.checkedAt, 0);
-  return checkedAt > 0
-    ? { path: value.path, checkedAt, boundaryAt: finiteNumber(value.boundaryAt, 0) }
-    : null;
+  if (!(checkedAt > 0)) return null;
+  // Only a non-negative safe integer is a usable byte offset; anything else (fractional, NaN,
+  // negative, string) is treated as 'no scannedSize' so the next probe does one full scan.
+  const scannedSize = Number.isSafeInteger(value.scannedSize) && value.scannedSize >= 0 ? value.scannedSize : null;
+  return { path: value.path, checkedAt, boundaryAt: finiteNumber(value.boundaryAt, 0), scannedSize };
+}
+
+function boundaryAtOfLine(line) {
+  if (!line.includes('compact_boundary')) return 0;
+  try {
+    const entry = JSON.parse(line);
+    if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
+      const at = Date.parse(entry.timestamp ?? '');
+      if (Number.isFinite(at)) return at;
+    }
+  } catch { /* not a usable boundary line */ }
+  return 0;
+}
+
+// Scan `[max(fromOffset, size - tailBytes), size)` of the transcript for the newest
+// compact_boundary (epoch ms, 0 if none). A leading partial line is dropped only when the
+// read starts mid-line. `scannedSize` is the offset just past the last `\n` read, so a
+// trailing line still being written is rescanned once it is complete and a delta scan always
+// starts at a line boundary. A fromOffset beyond EOF (truncation/rotation) scans the tail.
+// Throws on stat/open/read failure; callers decide the fallback.
+export async function scanCompactBoundary(transcriptPath, { tailBytes = BOUNDARY_TAIL_BYTES, fromOffset = 0 } = {}) {
+  const stat = await fs.stat(transcriptPath);
+  const size = stat.size;
+  if (!stat.isFile() || size === 0) {
+    return { boundaryAt: 0, scannedSize: 0, size };
+  }
+  const requested = Number.isSafeInteger(fromOffset) && fromOffset >= 0 && fromOffset <= size ? fromOffset : 0;
+  const start = Math.max(requested, size - tailBytes);
+  // One extra leading byte tells whether `start` sits on a line boundary.
+  const readStart = start > 0 ? start - 1 : 0;
+  const length = size - readStart;
+  const buffer = Buffer.allocUnsafe(length);
+  const handle = await fs.open(transcriptPath, 'r');
+  let bytesRead;
+  try {
+    ({ bytesRead } = await handle.read(buffer, 0, length, readStart));
+  } finally {
+    await handle.close();
+  }
+  const data = buffer.subarray(0, bytesRead);
+  // A delta scan must start on a line boundary (scannedSize sits just past a `\n`). If the
+  // byte before it is not `\n`, the file was replaced at the same path: rescan from the top.
+  if (requested > 0 && start === requested && data.length > 0 && data[0] !== 0x0a) {
+    return scanCompactBoundary(transcriptPath, { tailBytes, fromOffset: 0 });
+  }
+  let begin = 0;
+  let leadingPartialOnly = false;
+  if (start > 0 && data.length > 0 && data[0] !== 0x0a) {
+    const nl = data.indexOf(0x0a, 1);
+    if (nl === -1) { begin = data.length; leadingPartialOnly = true; } else { begin = nl + 1; }
+  } else if (start > 0) {
+    begin = 1;
+  }
+  const region = data.subarray(begin);
+  const lastNl = region.lastIndexOf(0x0a);
+  const scannedSize = lastNl >= 0
+    ? readStart + begin + lastNl + 1
+    : (leadingPartialOnly ? start : readStart + begin);
+  const lines = region.toString('utf8').split('\n');
+  for (let i = lines.length - 1; i >= 0; i -= 1) {
+    const at = boundaryAtOfLine(lines[i]);
+    if (at) return { boundaryAt: at, scannedSize, size };
+  }
+  return { boundaryAt: 0, scannedSize, size };
 }
 
 // Find the newest compaction recorded in the session transcript, as epoch ms (0 if none).
@@ -576,35 +647,7 @@ export async function detectLatestCompactBoundaryAt(transcriptPath, { tailBytes
     return 0;
   }
   try {
-    const stat = await fs.stat(transcriptPath);
-    if (!stat.isFile() || stat.size === 0) {
-      return 0;
-    }
-    const start = Math.max(0, stat.size - tailBytes);
-    const length = stat.size - start;
-    const buffer = Buffer.allocUnsafe(length);
-    const handle = await fs.open(transcriptPath, 'r');
-    let text;
-    try {
-      const { bytesRead } = await handle.read(buffer, 0, length, start);
-      text = buffer.toString('utf8', 0, bytesRead);
-    } finally {
-      await handle.close();
-    }
-    const lines = text.split('\n');
-    if (start > 0) lines.shift(); // a tail read can split the first line
-    for (let i = lines.length - 1; i >= 0; i -= 1) {
-      const line = lines[i];
-      if (!line.includes('compact_boundary')) continue;
-      try {
-        const entry = JSON.parse(line);
-        if (entry?.type === 'system' && entry?.subtype === 'compact_boundary') {
-          const at = Date.parse(entry.timestamp ?? '');
-          if (Number.isFinite(at)) return at;
-        }
-      } catch { /* not a usable boundary line */ }
-    }
-    return 0;
+    return (await scanCompactBoundary(transcriptPath, { tailBytes, fromOffset: 0 })).boundaryAt;
   } catch {
     return 0;
   }
@@ -616,28 +659,89 @@ export async function detectLatestCompactBoundaryAt(transcriptPath, { tailBytes
 // history that was already summarised away and the hard-cap gate bricks a healthy
 // session. Callers must persist when reset=true, or the reset would re-fire (and
 // zero the counter) on every call.
+//
+// The probe is incremental: it remembers how many bytes were already scanned
+// (`scannedSize`), so an unchanged transcript costs one stat and a grown one only reads the
+// delta. `probed: true` tells the caller to persist; it is raised only on a meaningful change
+// (new path, new boundary, full rescan, or >= persistDeltaBytes unpersisted bytes scanned).
 export async function syncCompactPressureStateWithTranscript(
   rawState = null,
   config = {},
   transcriptPath = '',
-  { now = Date.now(), probeTtlMs = TRANSCRIPT_BOUNDARY_PROBE_TTL_MS } = {},
+  { now = Date.now(), probeTtlMs = TRANSCRIPT_BOUNDARY_PROBE_TTL_MS, persistDeltaBytes = PROBE_PERSIST_DELTA_BYTES } = {},
 ) {
   const normalizedPath = typeof transcriptPath === 'string' ? transcriptPath.trim() : '';
   const previousProbe = normalizeTranscriptProbe(rawState?.transcriptBoundaryProbe);
-  // A process-persistent, session-scoped cache avoids rereading/parsing up to 4MB for every
+  const samePath = Boolean(previousProbe) && previousProbe.path === normalizedPath;
+  // A process-persistent, session-scoped cache avoids rereading/parsing the transcript for every
   // mutation during a tool burst. It keys on the path (not just time) so a resumed/new
   // transcript always scans immediately. The short TTL is deliberately only a performance
   // coalescing window; PreCompact remains the immediate source of truth.
-  const probeFresh = previousProbe
-    && previousProbe.path === normalizedPath
+  const probeFresh = samePath
     && now - previousProbe.checkedAt >= 0
     && now - previousProbe.checkedAt < probeTtlMs;
-  const boundaryAt = probeFresh
-    ? previousProbe.boundaryAt
-    : await detectLatestCompactBoundaryAt(normalizedPath);
-  const probe = probeFresh
-    ? previousProbe
-    : { path: normalizedPath, checkedAt: now, boundaryAt };
+
+  let boundaryAt;
+  let probe;
+  let probed;
+  if (probeFresh) {
+    boundaryAt = previousProbe.boundaryAt;
+    probe = previousProbe;
+    probed = false;
+  } else {
+    // `persistedScannedSize` is the scannedSize loaded from disk via rawState: the gate only
+    // persists when probed is true, so this bounds the delta a later process must re-read.
+    const persistedScannedSize = samePath ? previousProbe.scannedSize : null;
+    const fullScan = async () => {
+      const scan = await scanCompactBoundary(normalizedPath, { fromOffset: 0 });
+      return {
+        boundaryAt: scan.boundaryAt,
+        probe: { path: normalizedPath, checkedAt: now, boundaryAt: scan.boundaryAt, scannedSize: scan.scannedSize },
+        probed: true,
+      };
+    };
+    const incrementalScan = async () => {
+      const { size } = await fs.stat(normalizedPath);
+      if (size === persistedScannedSize) {
+        // Nothing new since the persisted probe: reuse, no read.
+        const reused = previousProbe.boundaryAt;
+        return {
+          boundaryAt: reused,
+          probe: { path: normalizedPath, checkedAt: now, boundaryAt: reused, scannedSize: persistedScannedSize },
+          probed: false,
+        };
+      }
+      if (size < persistedScannedSize) return fullScan(); // truncation/rotation
+      const scan = await scanCompactBoundary(normalizedPath, { fromOffset: persistedScannedSize });
+      const merged = scan.boundaryAt || previousProbe.boundaryAt;
+      return {
+        boundaryAt: merged,
+        probe: { path: normalizedPath, checkedAt: now, boundaryAt: merged, scannedSize: scan.scannedSize },
+        probed: merged !== previousProbe.boundaryAt
+          || scan.scannedSize - persistedScannedSize >= persistDeltaBytes,
+      };
+    };
+    let result = null;
+    if (persistedScannedSize !== null) {
+      // Any incremental failure retries one full scan, so the gate decides exactly as a full
+      // re-read would; only if that fails too do we fall back to the previous boundary.
+      try { result = await incrementalScan(); } catch { result = null; }
+    }
+    if (!result) {
+      try {
+        result = await fullScan();
+      } catch {
+        // stat/open/read failure: keep the previous boundary for the same path, else 0.
+        const kept = samePath ? previousProbe.boundaryAt : 0;
+        result = {
+          boundaryAt: kept,
+          probe: { path: normalizedPath, checkedAt: now, boundaryAt: kept, scannedSize: persistedScannedSize },
+          probed: !samePath,
+        };
+      }
+    }
+    ({ boundaryAt, probe, probed } = result);
+  }
   const accounted = finiteNumber(rawState?.lastCompactBoundaryAt, 0);
   if (!boundaryAt || boundaryAt <= accounted) {
     return {
@@ -645,7 +749,7 @@ export async function syncCompactPressureStateWithTranscript(
         ? { ...rawState, transcriptBoundaryProbe: probe }
         : rawState,
       reset: false,
-      probed: !probeFresh,
+      probed,
     };
   }
   return {
@@ -655,7 +759,7 @@ export async function syncCompactPressureStateWithTranscript(
       transcriptBoundaryProbe: probe,
     },
     reset: true,
-    probed: !probeFresh,
+    probed,
   };
 }