@bli-cockpit/cli 0.2.249 → 0.2.251

package/dist/adapters/raw-evidence-collection-state.js

@@ -23,6 +23,7 @@
  * `.staging-<pid>-<rand>` directory that `raw-evidence-facts.ts` promotes once
  * collection is done.
  */
+import { openPrepareMemo } from "./raw-evidence-prepare-memo.js";
 import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
@@ -63,6 +64,7 @@ export async function openCollection(context, options, places) {
     if (options.images)
         budget.images ??= options.images;
     const stagingAllowance = (budget.staging ??= await openStagingAllowance(options.stateDir, options.env ?? process.env, { statfs: options.statfs }));
+    budget.prepareMemo ??= await openPrepareMemo(options.stateDir);
     return {
         context,
         filesDir: path.join(places.stagingDir, "files"),

package/dist/adapters/raw-evidence-prepare-memo.js

@@ -0,0 +1,212 @@
+/**
+ * Remember what a transcript became, so a tick does not rebuild it (BLI-3936).
+ *
+ * Turning a transcript into the bytes that go up costs a read, the image step, the slim rules, the
+ * secret mask and a sha256 of the result. The result only matters for ONE decision: is this
+ * content already durable remotely? Before this file, every 15-minute tick (and every worktree
+ * pass inside it) paid that whole cost for every recent transcript to learn the answer it had
+ * already learned the tick before: 280 slim passes and 0.38 GB of JSON per tick on the reference
+ * Mac, plus 82 mask passes, for transcripts that had not changed.
+ *
+ * The memo answers the question without the work. It is keyed by the same source key the delivery
+ * ledger uses, and an entry is trusted only when ALL of these still hold:
+ *
+ *   - the file's size, inode and mtime/ctime (nanoseconds) are exactly what they were when the
+ *     entry was written, so the file has not been appended to, rewritten or replaced;
+ *   - the recipe is the same: collector version (slim rules and secret rules ship with it), the
+ *     machine's image-handling mode, and whether an image step ran at all;
+ *   - the entry is not `volatile`: a transcript that still held an image with no stored
+ *     description (or whose slim step failed) can change shape on the next tick without the file
+ *     changing, so it is always rebuilt.
+ *
+ * The caller then reuses the entry ONLY when the remembered content hash is already durable
+ * remotely (`skipContentHashes`). Anything else, including every file that is not yet delivered,
+ * takes the normal full path, so the memo can only ever remove work whose outcome is already
+ * known. A memo that is lost, corrupt, or wrong in the safe direction costs one slow tick, never
+ * a missed upload. It holds ids, sizes, hashes and redaction metadata, never a byte of content.
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import { isMissingFileFailure } from "../health-detail.js";
+import { readJsonFile, writeJsonFileAtomic } from "../local-state-files.js";
+import { LOCAL_COLLECTOR_VERSION } from "../local-state-config.js";
+export const PREPARE_MEMO_FILENAME = "transcript-prepare-memo.json";
+const MEMO_FORMAT = "prepare-memo.v1";
+/** About 700 bytes an entry, so this is at most a few MB; the oldest leave first. */
+export const PREPARE_MEMO_MAX_ENTRIES = 20_000;
+/** A source not seen for this long is a deleted or rotated session. */
+const FORGET_AFTER_MS = 14 * 24 * 3_600_000;
+/** Refresh `seen_ms` at most this often, so an unchanged tick does not rewrite the file. */
+const SEEN_REFRESH_MS = 24 * 3_600_000;
+const TAG = "[raw-evidence-memo]";
+export function sourceStampOf(stat) {
+    return {
+        size: Number(stat.size),
+        identity: [stat.ino, stat.mtimeNs, stat.ctimeNs].map(String).join(":"),
+    };
+}
+/** Stat a file the way the memo wants it. Null when it cannot be stat'd: the caller takes the normal path, which says why. */
+export async function statSourceForMemo(filePath) {
+    try {
+        return sourceStampOf(await fs.stat(filePath, { bigint: true }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Everything besides the file that decides what its prepared bytes are. */
+export function prepareRecipe(options) {
+    return [MEMO_FORMAT, LOCAL_COLLECTOR_VERSION, options.kind, options.imageMode ?? "no_image_step"].join("|");
+}
+export function prepareMemoPath(stateDir) {
+    return path.join(stateDir, PREPARE_MEMO_FILENAME);
+}
+const EMPTY_COUNTS = { skipped_count: 0, skipped_bytes: 0, rebuilt_count: 0, rebuilt_bytes: 0, volatile_count: 0, volatile_reused_count: 0, volatile_reused_bytes: 0 };
+export async function openPrepareMemo(stateDir) {
+    const entries = await readMemoEntries(stateDir);
+    let dirty = false;
+    let counts = { ...EMPTY_COUNTS };
+    /** Sources recalled since the last `settle`: only these have their `seen_ms` refreshed. */
+    const recalled = new Set();
+    /** In-memory only, never persisted: see `rememberForThisRun`. */
+    const thisRun = new Map();
+    return {
+        recall(sourceKey, stamp, recipe) {
+            const entry = entries.get(sourceKey);
+            if (!entry)
+                return recallThisRun(thisRun, sourceKey, stamp, recipe);
+            if (entry.volatile)
+                return recallThisRun(thisRun, sourceKey, stamp, recipe);
+            if (entry.recipe !== recipe)
+                return null;
+            if (entry.size !== stamp.size || entry.identity !== stamp.identity)
+                return null;
+            recalled.add(sourceKey);
+            return entry;
+        },
+        remember(sourceKey, entry, now = Date.now()) {
+            entries.set(sourceKey, { ...entry, seen_ms: now });
+            thisRun.delete(sourceKey);
+            dirty = true;
+        },
+        rememberForThisRun(sourceKey, entry) {
+            thisRun.set(sourceKey, { ...entry, volatile: true, seen_ms: Date.now() });
+        },
+        count(outcome, bytes) {
+            if (outcome === "volatile_reused") {
+                counts.volatile_reused_count += 1;
+                counts.volatile_reused_bytes += bytes;
+                return;
+            }
+            if (outcome === "skipped") {
+                counts.skipped_count += 1;
+                counts.skipped_bytes += bytes;
+                return;
+            }
+            counts.rebuilt_count += 1;
+            counts.rebuilt_bytes += bytes;
+            if (outcome === "volatile")
+                counts.volatile_count += 1;
+        },
+        async settle(now = Date.now()) {
+            const done = counts;
+            counts = { ...EMPTY_COUNTS };
+            dirty = refreshSeen(entries, recalled, now) || dirty;
+            recalled.clear();
+            if (!dirty)
+                return done;
+            const kept = trimEntries(entries, now);
+            try {
+                await writeJsonFileAtomic(prepareMemoPath(stateDir), { schema_version: MEMO_FORMAT, entries: Object.fromEntries(kept) });
+                dirty = false;
+            }
+            catch (error) {
+                console.error(TAG + " memo not written; the next tick rebuilds what it would have skipped", JSON.stringify({ reason: "prepare_memo_write_failed", entries: kept.length, error_name: error instanceof Error ? error.name : typeof error }));
+            }
+            return done;
+        },
+    };
+}
+function recallThisRun(thisRun, sourceKey, stamp, recipe) {
+    const entry = thisRun.get(sourceKey);
+    if (!entry || entry.recipe !== recipe)
+        return null;
+    if (entry.size !== stamp.size || entry.identity !== stamp.identity)
+        return null;
+    return entry;
+}
+/**
+ * Entries recalled this pass keep their `seen_ms` fresh, lazily, so they are not forgotten while in
+ * use. Only those: an entry nobody recalls (a deleted or rotated session) ages out after
+ * FORGET_AFTER_MS.
+ */
+function refreshSeen(entries, recalled, now) {
+    let touched = false;
+    for (const key of recalled) {
+        const entry = entries.get(key);
+        if (entry && now - entry.seen_ms > SEEN_REFRESH_MS) {
+            entry.seen_ms = now;
+            touched = true;
+        }
+    }
+    return touched;
+}
+function trimEntries(entries, now) {
+    for (const [key, entry] of entries) {
+        if (now - entry.seen_ms > FORGET_AFTER_MS)
+            entries.delete(key);
+    }
+    const newestFirst = [...entries.entries()].sort((a, b) => b[1].seen_ms - a[1].seen_ms);
+    const kept = newestFirst.slice(0, PREPARE_MEMO_MAX_ENTRIES);
+    if (kept.length < entries.size) {
+        entries.clear();
+        for (const [key, entry] of kept)
+            entries.set(key, entry);
+    }
+    return kept;
+}
+async function readMemoEntries(stateDir) {
+    const entries = new Map();
+    let raw;
+    try {
+        raw = await readJsonFile(prepareMemoPath(stateDir));
+    }
+    catch (error) {
+        if (!isMissingFileFailure(error)) {
+            console.error(TAG + " memo unreadable; every transcript is rebuilt once", JSON.stringify({ reason: "prepare_memo_unreadable" }));
+        }
+        return entries;
+    }
+    const stored = raw;
+    if (stored?.schema_version !== MEMO_FORMAT || !stored.entries || typeof stored.entries !== "object")
+        return entries;
+    let dropped = 0;
+    for (const [key, value] of Object.entries(stored.entries)) {
+        const entry = parseEntry(value);
+        if (entry)
+            entries.set(key, entry);
+        else
+            dropped += 1;
+    }
+    if (dropped > 0) {
+        console.error(TAG + " memo entries dropped as malformed", JSON.stringify({ reason: "prepare_memo_entries_malformed", dropped, kept: entries.size }));
+    }
+    return entries;
+}
+function parseEntry(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const entry = value;
+    if (typeof entry["size"] !== "number" || typeof entry["identity"] !== "string")
+        return null;
+    if (typeof entry["recipe"] !== "string" || typeof entry["byte_size"] !== "number")
+        return null;
+    if (typeof entry["content_hash"] !== "string" || !/^[0-9a-f]{64}$/u.test(entry["content_hash"]))
+        return null;
+    if (typeof entry["volatile"] !== "boolean" || typeof entry["seen_ms"] !== "number")
+        return null;
+    const redacted = entry["redacted"];
+    if (redacted !== null && (typeof redacted !== "object" || typeof redacted.completenessLabel !== "string"))
+        return null;
+    return entry;
+}

package/dist/adapters/raw-evidence-transcript-file.js

@@ -10,6 +10,11 @@
  *
  * Every refusal pushes a named skip into the gap ledger first, so a file this
  * module declines is never silently absent.
+ *
+ * BLI-3936: the read, the image step, the slim rules, the mask and the hash exist to answer one
+ * question, "is this content already durable remotely?". A transcript whose file has not changed
+ * since the tick that answered it is not rebuilt: `reuseUnchangedTranscript` replays the answer
+ * from the prepare memo (`raw-evidence-prepare-memo.ts`) and says so in the pass's summary line.
  */
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -20,6 +25,7 @@ import { maskSecretsInTranscript, } from "./raw-evidence-sanitize.js";
 import { mightHoldEmbeddedImages } from "@bli-cockpit/telemetry-core";
 import { markBudgetCapApplied, markCapApplied, } from "./raw-evidence-completeness.js";
 import { evidenceEntry } from "./raw-evidence-manifest.js";
+import { prepareRecipe, statSourceForMemo, } from "./raw-evidence-prepare-memo.js";
 import { describeSnapshot, stubReplacementClaim, supersedeClaimFor, } from "./raw-evidence-snapshot-supersede.js";
 import { admitEvidence, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
 /**
@@ -44,6 +50,12 @@ export async function collectOneEvidenceFile(collection, options) {
         logDeliveryBackoffHold(options.kind, names.sourceKey);
         return false;
     }
+    // BLI-3936: stat BEFORE the read. The same stamp, taken again after the work, proves the file
+    // did not move underneath it; only then is the result remembered.
+    const stamp = await statSourceForMemo(options.filePath);
+    const recipe = prepareRecipe({ imageMode: collection.budget.images?.mode, kind: options.kind });
+    if (await reuseUnchangedTranscript(collection, options, names, stamp, recipe))
+        return true;
     const read = await readEvidenceFileWithinCap(options.filePath, options.maxFileBytes);
     if (read.status === "read_failed")
         return skip("file_read_failed");
@@ -51,7 +63,10 @@ export async function collectOneEvidenceFile(collection, options) {
         markCapApplied(collection, options.kind, "max_file_bytes");
         return skip("file_too_large");
     }
-    const { sanitized, contentHash, stubClaim } = await prepareTranscriptForUpload(collection, options, names, read.bytes);
+    const { sanitized, contentHash, stubClaim, volatile, deferredOnly, redactedEntry } = await prepareTranscriptForUpload(collection, options, names, read.bytes);
+    await rememberPreparedTranscript(collection, options, names, {
+        stamp, recipe, readBytes: read.bytes.byteLength, contentHash, byteSize: sanitized.bytes.byteLength, volatile, deferredOnly, redactedEntry,
+    });
     if (collection.skipContentHashes.has(contentHash) && !stubClaim) {
         collection.reused.push({
             kind: options.kind,
@@ -82,17 +97,20 @@ function recordEvidenceSkip(collection, kind, label, reason) {
 async function prepareTranscriptForUpload(collection, options, names, bytes) {
     // BLI-16977: describe each distinct embedded image once and, when the one switch says so, swap the
     // base64 for a short marker BEFORE masking, so the masker and the content hash see the final bytes.
-    const imagesPrepared = await prepareEmbeddedImages(collection, {
+    const images = await prepareEmbeddedImages(collection, {
         bytes,
         kind: options.kind,
         sessionId: options.sessionId,
     });
+    const redactedBefore = collection.redacted.length;
     const sanitized = maskSecretsInTranscript(collection, {
-        raw: imagesPrepared,
+        raw: images.bytes,
         kind: options.kind,
         evidenceLabel: names.evidenceLabel,
         secretLikeFileName: names.secretLikeFileName,
     });
+    // The ledger entry this mask pushed (if any), kept so a later skip can replay it.
+    const redactedEntry = collection.redacted.length > redactedBefore ? collection.redacted[collection.redacted.length - 1] : null;
     const contentHash = sha256(sanitized.bytes);
     // BLI-11102: a session the server named a redaction stub is re-offered even
     // when these bytes are already durable, because the stub is not a delivery.
@@ -103,7 +121,7 @@ async function prepareTranscriptForUpload(collection, options, names, bytes) {
         byteSize: sanitized.bytes.byteLength,
         alreadyDurable: collection.skipContentHashes.has(contentHash),
     });
-    return { sanitized, contentHash, stubClaim };
+    return { sanitized, contentHash, stubClaim, volatile: images.volatile, deferredOnly: images.deferredOnly, redactedEntry };
 }
 /**
  * The transcript bytes after the image step. Unchanged (the very same buffer) unless this sync has
@@ -115,24 +133,119 @@ async function prepareEmbeddedImages(collection, file) {
     const session = collection.budget.images;
     const source = file.kind.startsWith("codex") ? "codex" : file.kind.startsWith("claude") ? "claude_code" : null;
     if (!session || !source)
-        return file.bytes;
+        return { bytes: file.bytes, volatile: false, deferredOnly: false };
     // Drop mode slims every transcript, image-bearing or not; keep mode only describes the ones that can hold an image.
     if (session.mode !== "describe_and_drop" && !mightHoldEmbeddedImages(file.bytes))
-        return file.bytes;
+        return { bytes: file.bytes, volatile: false, deferredOnly: false };
     try {
         const prepared = await session.prepareTranscript({
             text: file.bytes.toString("utf8"),
             source,
             sessionId: file.sessionId,
         });
+        // BLI-3936: "volatile" = the next tick could build different bytes, or do image work, from
+        // this very file: an image still without a stored description (keep mode never replaces, so
+        // any image counts) or a slim step that failed and should be retried.
+        const imagesPending = session.mode === "describe_and_drop"
+            ? prepared.imageCount > prepared.replacedCount
+            : prepared.imageCount > 0;
+        const slimFailed = session.mode === "describe_and_drop" && prepared.slim === null;
+        const volatile = imagesPending || slimFailed;
+        // BLI-22785: volatile ONLY because the budget or a backoff held images back, and the slim step held up.
+        const deferredOnly = volatile && prepared.deferredOnly && !slimFailed;
         if (!prepared.changed)
-            return file.bytes;
-        return Buffer.from(prepared.text, "utf8");
+            return { bytes: file.bytes, volatile, deferredOnly };
+        return { bytes: Buffer.from(prepared.text, "utf8"), volatile, deferredOnly };
     }
     catch (error) {
         console.error("[raw-evidence] image or slim step failed, uploading the transcript as it was", JSON.stringify({ reason: "image_step_failed", kind: file.kind, ...describeError(error) }));
-        return file.bytes;
+        return { bytes: file.bytes, volatile: true, deferredOnly: false };
+    }
+}
+/**
+ * BLI-3936: the answer for a transcript whose file has not changed since a tick that found its
+ * content already durable remotely. Replays exactly what the full path would have recorded (the
+ * reuse entry, and the redaction ledger entry if the mask had fired) without reading, slimming,
+ * masking or hashing a byte. Anything else, including every file not yet delivered, returns false
+ * and takes the full path, so this can only remove work whose outcome is already known.
+ */
+async function reuseUnchangedTranscript(collection, options, names, stamp, recipe) {
+    const memo = collection.budget.prepareMemo;
+    if (!memo || !stamp)
+        return false;
+    // A session the server named a redaction stub is re-offered whatever is durable (BLI-11102).
+    if (collection.stubReoffers.has(options.sessionId))
+        return false;
+    // A file over this pass's cap takes the full path, which names the cap it hit.
+    if (options.maxFileBytes && stamp.size > options.maxFileBytes)
+        return false;
+    const known = memo.recall(names.sourceKey, stamp, recipe);
+    if (!known)
+        return false;
+    if (!collection.skipContentHashes.has(known.content_hash)) {
+        if (known.volatile)
+            logVolatileReuse(options.kind, names.sourceKey, known.content_hash, "hash_not_durable_full_path");
+        return false;
+    }
+    if (known.redacted) {
+        collection.redacted.push({
+            kind: options.kind,
+            label: names.evidenceLabel,
+            redaction: known.redacted.redaction,
+            completenessLabel: known.redacted.completenessLabel,
+        });
+    }
+    collection.reused.push({
+        kind: options.kind,
+        label: names.evidenceLabel,
+        content_hash_sha256: known.content_hash,
+        codex_session_id: options.sessionId,
+    });
+    if (known.volatile) {
+        // BLI-22785: images held back by this run's budget or a backoff; rebuilding gives the same bytes.
+        memo.count("volatile_reused", stamp.size);
+        logVolatileReuse(options.kind, names.sourceKey, known.content_hash, "images_deferred_budget_cannot_refill_this_run");
+        return true;
+    }
+    memo.count("skipped", stamp.size);
+    return true;
+}
+function logVolatileReuse(kind, sourceKey, contentHash, reason) {
+    console.error("[raw-evidence] volatile transcript " + (reason === "hash_not_durable_full_path" ? "rebuilt" : "reused this run"), JSON.stringify({ reason, kind, source_key: sourceKey, hash_prefix: contentHash.slice(0, 12) }));
+}
+/** Remember what this transcript became, but only if the file stayed put while it was built. */
+async function rememberPreparedTranscript(collection, options, names, built) {
+    const memo = collection.budget.prepareMemo;
+    if (!memo)
+        return;
+    memo.count(built.volatile ? "volatile" : "rebuilt", built.readBytes);
+    if ((built.volatile && !built.deferredOnly) || !built.stamp)
+        return;
+    const after = await statSourceForMemo(options.filePath);
+    const stable = after !== null
+        && after.size === built.stamp.size
+        && after.identity === built.stamp.identity
+        && built.readBytes === built.stamp.size;
+    if (!stable)
+        return;
+    const entry = {
+        ...built.stamp,
+        recipe: built.recipe,
+        content_hash: built.contentHash,
+        byte_size: built.byteSize,
+        redacted: built.redactedEntry
+            ? { redaction: built.redactedEntry.redaction, completenessLabel: built.redactedEntry.completenessLabel }
+            : null,
+    };
+    if (built.volatile) {
+        // BLI-22785: in memory for this process only; the memo file keeps no volatile entry.
+        memo.rememberForThisRun(names.sourceKey, entry);
+        return;
     }
+    const known = memo.recall(names.sourceKey, built.stamp, built.recipe);
+    if (known && !known.volatile && known.content_hash === built.contentHash)
+        return;
+    memo.remember(names.sourceKey, { ...entry, volatile: false });
 }
 function nameEvidenceFile(options) {
     const fileName = path.basename(options.filePath);

package/dist/adapters/raw-evidence.js

@@ -92,6 +92,7 @@ export async function collectRawEvidencePack(context, options) {
         await ensurePrivateDir(collection.filesDir);
         recordAttributionCompleteness(collection, options);
         await collectEverySource(collection, options, sinceMinutes);
+        await reportPrepareMemo(collection);
         return collection.entries.length === 0
             ? await finishWithEmptyPack(collection, options, run)
             : await finishWithPromotedPack(collection, options, run);
@@ -100,6 +101,25 @@ export async function collectRawEvidencePack(context, options) {
         return await finishWithFailedPack(collection, { ...run, error });
     }
 }
+/**
+ * BLI-3936: say how many transcripts this pass did not have to rebuild, and keep the memo that
+ * made it possible. Counts and bytes only. Never throws: the memo is a cache.
+ */
+async function reportPrepareMemo(collection) {
+    const counts = await collection.budget.prepareMemo?.settle();
+    if (!counts || counts.skipped_count + counts.rebuilt_count + counts.volatile_reused_count === 0)
+        return;
+    console.error(counts.skipped_count + counts.volatile_reused_count > 0 ? "[raw-evidence] slim skipped unchanged" : "[raw-evidence] no unchanged transcripts to skip", JSON.stringify({
+        reason: "source_unchanged_since_last_prepare",
+        count: counts.skipped_count,
+        bytes: counts.skipped_bytes,
+        rebuilt_count: counts.rebuilt_count,
+        rebuilt_bytes: counts.rebuilt_bytes,
+        rebuilt_volatile_count: counts.volatile_count,
+        rebuilt_volatile_reused_count: counts.volatile_reused_count,
+        rebuilt_volatile_reused_bytes: counts.volatile_reused_bytes,
+    }));
+}
 /**
  * Every kind of evidence this repo can offer, in the order it is read. Codex and
  * Claude transcripts are each switchable off by the caller; the git diffs are

package/dist/autostart-darwin-plist.js

@@ -25,6 +25,17 @@ import { decodeXmlEntities, xmlEscape } from "./autostart-xml.js";
  * cheap — the collection lock turns overlap into a named no-op.
  */
 export const DARWIN_NETWORK_CHANGE_SIGNAL = "/private/var/run/resolv.conf";
+/**
+ * The least time launchd leaves between two starts of the tick (BLI-3936). Its default is 10
+ * seconds, and WatchPaths on the session directories fires on every transcript write, so on a
+ * busy Mac the tick restarted the moment it exited. launchd delays a throttled start rather than
+ * dropping it, so a transcript write or a network change inside the window still produces exactly
+ * one run, at the end of it. Five minutes keeps capture near-real-time (a session is collected
+ * within five minutes of its last write) and caps the tick at 12 runs an hour however many
+ * agents are writing. Applies to every trigger: launchd cannot say which one fired, which is
+ * why this is the whole debounce and no code-side "which trigger was it" check exists.
+ */
+export const DARWIN_MIN_SECONDS_BETWEEN_TICKS = 300;
 /**
  * What the tick says to sync.err.log when neither the registered node binary
  * nor a login-shell node exists. Named, actionable, path-free (BLI-3553).
@@ -165,12 +176,13 @@ function renderPlist(options) {
         `  <integer>${options.intervalSeconds}</integer>`,
         "  <key>RunAtLoad</key>",
         "  <true/>",
-        // WatchPaths makes a transcript write fire `cockpit sync` within seconds, so
-        // captures land near-real-time; StartInterval above is the safety-net floor.
-        // It fires often, but launchd single-flights the job, sync holds its own
-        // lock, and growing-transcript re-upload is damped — so cost stays bounded
-        // and no extra debounce is needed.
+        // WatchPaths makes a transcript write fire `cockpit sync` soon after, so captures land
+        // near-real-time; StartInterval above is the safety-net floor. launchd single-flights the job
+        // and sync holds its own lock, but neither stops a busy Mac restarting the tick the moment it
+        // exits; ThrottleInterval is the minimum gap between starts (BLI-3936).
         ...watchPathsBlock(options.watchPaths),
+        "  <key>ThrottleInterval</key>",
+        `  <integer>${DARWIN_MIN_SECONDS_BETWEEN_TICKS}</integer>`,
         "  <key>StandardOutPath</key>",
         `  <string>${xmlEscape(options.stdoutPath)}</string>`,
         "  <key>StandardErrorPath</key>",
@@ -262,6 +274,10 @@ function darwinAgentRegistrationProblems(plist, expected) {
     if (!plist.includes(`  <integer>${expected.intervalSeconds}</integer>`)) {
         problems.push(`cadence is not ${expected.intervalSeconds} seconds`);
     }
+    // BLI-3936: a plist written before the throttle existed has no minimum gap between ticks.
+    if (!plist.includes(`  <key>ThrottleInterval</key>\n  <integer>${DARWIN_MIN_SECONDS_BETWEEN_TICKS}</integer>`)) {
+        problems.push(`minimum gap between ticks is not ${DARWIN_MIN_SECONDS_BETWEEN_TICKS} seconds`);
+    }
     const expectedCommand = renderDarwinSyncCommand({
         discoveryArgs: expected.discoveryArgs,
         workDirs: expected.workDirs,

package/dist/autostart.js

@@ -22,7 +22,7 @@ import { installRemindAgent, remindAgentStatus, uninstallRemindAgent } from "./a
  * import site the rest of the collector already knows (BLI-3571).
  */
 export { AUTOSTART_LABEL, DEFAULT_AUTOSTART_INTERVAL_SECONDS, WINDOWS_AUTOSTART_TASK_NAME, REMIND_AUTOSTART_LABEL, WINDOWS_REMIND_TASK_NAME, } from "./autostart-contract.js";
-export { DARWIN_NETWORK_CHANGE_SIGNAL, DARWIN_NODE_MISSING_MESSAGE, writeDarwinAutostartPlist, } from "./autostart-darwin-plist.js";
+export { DARWIN_MIN_SECONDS_BETWEEN_TICKS, DARWIN_NETWORK_CHANGE_SIGNAL, DARWIN_NODE_MISSING_MESSAGE, writeDarwinAutostartPlist, } from "./autostart-darwin-plist.js";
 export { launchdUserDomain, reregisterDarwinAgent, } from "./autostart-darwin.js";
 /**
  * Installs (or refreshes) the scheduled `cockpit sync` this machine's OS

package/dist/commands/backfill-live-window.js

@@ -0,0 +1,41 @@
+/**
+ * BLI-22790: backfill is history. A session file modified inside the live window belongs to the
+ * normal sync tick, which collects the same `DEFAULT_SINCE_MINUTES` (24 h) every ~15 minutes and
+ * already uploads these sessions (`riding_already_durable`). Re-preparing a live, still-growing
+ * session in backfill held the collection lock for 232 s per tick and kept the run "partial"
+ * forever, so doctor re-ran the backfill on every tick.
+ */
+import { DEFAULT_SINCE_MINUTES } from "../adapters/raw-evidence-collection-state.js";
+import { stubSessionKey } from "../evidence-stubs-client.js";
+export const BACKFILL_LIVE_WINDOW_MS = DEFAULT_SINCE_MINUTES * 60 * 1000;
+/** The window this run uses: none for a stub pass (it names its sessions), else the test seam or the default. */
+export function liveWindowMsFor(command) {
+    return command.stubPass ? 0 : (command.liveWindowMs ?? BACKFILL_LIVE_WINDOW_MS);
+}
+/** `onlySessions` (`codex:<id>` / `claude_code:<id>`) when set, then the live window. */
+export function scopeBackfillCandidates(candidates, options) {
+    const key = (c) => stubSessionKey(c.source, c.session_id);
+    const scoped = options.onlySessions ? candidates.filter((c) => options.onlySessions.has(key(c))) : candidates;
+    return leaveLiveSessionsToTheTick(scoped, options.live);
+}
+/**
+ * Drop the candidates the tick owns: modified within `liveWindowMs` (0 keeps all), unless the
+ * server names the session a redaction stub (BLI-11102), which is re-offered even while live.
+ * Logs the count either way.
+ */
+export function leaveLiveSessionsToTheTick(candidates, options) {
+    let liveExcluded = 0;
+    const kept = options.liveWindowMs <= 0 ? candidates : candidates.filter((candidate) => {
+        const live = options.now.getTime() - candidate.session_file_mtime_ms < options.liveWindowMs
+            && !options.stubbedSessions.has(stubSessionKey(candidate.source, candidate.session_id));
+        if (live)
+            liveExcluded += 1;
+        return !live;
+    });
+    console.error("[backfill] live sessions left to the tick", JSON.stringify({
+        reason: liveExcluded > 0 ? "live_owned_by_tick" : "no_live_sessions",
+        live_excluded: liveExcluded,
+        live_window_minutes: Math.round(options.liveWindowMs / 60_000),
+    }));
+    return { kept, liveExcluded };
+}

package/dist/commands/backfill-report.js

@@ -228,7 +228,17 @@ function countRemainingHistory(options) {
 async function writeAllHistoryCompletionMarker(ctx) {
     const { paths, cursor, sources, scopedCursor, scan, oversizedCandidateKeys, now } = ctx;
     const cappedSidecars = cappedSidecarCount(scan.candidates);
-    recordBackfillScanCoverage(cursor, sources, now, now);
+    // BLI-22790: sessions left to the tick were NOT covered here. Mark coverage only up to the
+    // start of the live window, so once they age out a later backfill still sees them.
+    const coveredThrough = scan.live_excluded_count > 0
+        ? new Date(now.getTime() - scan.live_window_ms)
+        : now;
+    console.error("[backfill] history coverage recorded", JSON.stringify({
+        reason: scan.live_excluded_count > 0 ? "covered_through_live_window_start" : "covered_through_now",
+        live_excluded: scan.live_excluded_count,
+        live_window_minutes: Math.round(scan.live_window_ms / 60_000),
+    }));
+    recordBackfillScanCoverage(cursor, sources, coveredThrough, now);
     await writeBackfillCursor(paths, cursor);
     const oversizedCandidates = scan.candidates.filter((candidate) => oversizedCandidateKeys.has(candidateCursorKey(candidate)));
     await writeBackfillCompletionMarker(paths, {

package/dist/commands/backfill-scan.js

@@ -14,6 +14,7 @@ import { scanAndAttributeClaudeSessions, } from "../adapters/claude-attribution.
 import { defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { liveWindowMsFor, scopeBackfillCandidates } from "./backfill-live-window.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
 import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
@@ -23,7 +24,6 @@ import { blockedBackfillResult } from "./backfill-result.js";
 import { emptyStubReofferPlan, loadStubReofferPlan, reopenStubbedSessions, } from "./backfill-stub-reoffer.js";
 import { loadStubCursorHashes, locateStubbedSessions } from "./backfill-stub-locate.js";
 import { resolveBackfillScope } from "./backfill-scope.js";
-import { stubSessionKey } from "../evidence-stubs-client.js";
 /**
  * SCAN: is this machine paired, what roots/sources/window apply, and what did
  * the archived Codex + Claude session stores actually contain. Returns either
@@ -149,11 +149,13 @@ async function scanBackfillSessions(options) {
         cursorHashes: options.stubCursorHashes,
         sinceMinutes: options.window.since_minutes,
     });
+    const liveWindowMs = liveWindowMsFor(options.command);
     const selection = selectBackfillCandidates({
         scanned,
         cursor: options.cursor,
         pointerlessTerminalSessions: options.pointerlessTerminalSessions,
         maxFiles: options.command.maxFiles,
+        live: { liveWindowMs, now: options.now, stubbedSessions: options.stubReoffer.sessions },
         onlySessions: options.command.stubPass
             ? new Set(options.command.stubPass.plan.sessions.keys())
             : undefined,
@@ -177,6 +179,8 @@ async function scanBackfillSessions(options) {
         issues,
         retryable_candidate_keys: retryableCandidateKeys(candidates),
         omitted_candidate_count: selection.omittedCandidateCount,
+        live_excluded_count: selection.liveExcluded,
+        live_window_ms: liveWindowMs,
     };
 }
 /**
@@ -220,9 +224,8 @@ async function scanClaudeHistory(request, projectsDir, scanLimit) {
  * so a `--max-files` cap spends its budget on them before newer history.
  */
 function selectBackfillCandidates(options) {
-    const allCandidates = options.scanned
-        .filter((candidate) => !options.onlySessions ||
-        options.onlySessions.has(stubSessionKey(candidate.source, candidate.session_id)))
+    const { kept, liveExcluded } = scopeBackfillCandidates(options.scanned, options);
+    const allCandidates = kept
         .filter((candidate) => isAfterCursor(candidate, options.cursor) ||
         isPointerlessTerminalRetry(candidate, options.pointerlessTerminalSessions))
         .sort((a, b) => compareBackfillCandidatesForRetry(a, b, options.pointerlessTerminalSessions));
@@ -230,6 +233,7 @@ function selectBackfillCandidates(options) {
     return {
         candidates,
         omittedCandidateCount: allCandidates.length - candidates.length,
+        liveExcluded,
     };
 }
 async function loadPointerlessTerminalSessions(paths, sources) {

package/dist/commands/doctor-disk-words.js

@@ -19,7 +19,7 @@ export function uncommittedReasonWords(reason) {
 }
 /** The same for objects the server refused outright (terminal). */
 export function terminalReasonWords(reason) {
-    if (reason === "storage_rejected_object_too_large" || /_failed_http_413/u.test(reason))
+    if (reason === "storage_rejected_object_too_large" || reason === "evidence_too_large_http_413" || /_failed_http_413/u.test(reason))
         return "too large for storage";
     if (reason === "storage_rejected_media_type")
         return "a file type storage refuses";