@bli-cockpit/cli 0.2.156 → 0.2.158

package/dist/adapters/codex-attribution.js

@@ -167,6 +167,7 @@ async function attributeOneSession(file, worktrees, collectionRoots) {
         file_path: file.file,
         file_name: fileName,
         codex_session_id: sessionIdFromFileName(fileName) ?? shortHash(file.file),
+        session_id_source: sessionIdFromFileName(fileName) ? "file_name" : "path_hash",
         cwd_basename: null,
         cwd_hash: null,
         session_file_mtime: new Date(file.mtimeMs).toISOString(),
@@ -197,6 +198,7 @@ async function attributeOneSession(file, worktrees, collectionRoots) {
     const metaSessionId = sanitizeSessionId(signals.session_ids[0]);
     if (metaSessionId) {
         base.codex_session_id = metaSessionId;
+        base.session_id_source = "session_meta";
     }
     const primaryCwd = signals.cwds[0] ?? null;
     if (primaryCwd) {

package/dist/commands/backfill-checkpoint.js

@@ -10,6 +10,7 @@
  */
 import { recordBackfillCursorObservations, } from "../cursors/backfill-cursor.js";
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { isRedactionStubObjectKey, markCursorEntryStubbed } from "../cursors/raw-evidence-stub-entry.js";
 import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
 import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
 import { indexDurableMainObjectKeys } from "./backfill-evidence-outcomes.js";
@@ -34,10 +35,11 @@ export async function recordBackfillDurableSessionPointers(options) {
             // No pointer, no prior entry, or already pointed: nothing this pass owes.
             // BLI-11102: a pointer the server named a redaction stub is not a
             // delivery, so a real pointer replaces it and the mark clears.
-            const replacesStub = Boolean(prior?.stub_reoffer) && prior?.uploaded_object_key !== objectKey;
+            // BLI-11119: an entry the cursor itself knows is `stubbed` counts too.
+            const replacesStub = Boolean(prior?.stub_reoffer || prior?.stubbed) && prior?.uploaded_object_key !== objectKey;
             if (!objectKey || !prior || (prior.uploaded_object_key && !replacesStub))
                 continue;
-            if (replacesStub)
+            if (replacesStub && !isRedactionStubObjectKey(objectKey))
                 stubsReplaced += 1;
             cursor.sessions[candidate.session_id] = deliveredCursorEntry(prior, candidate, objectKey, options.now);
             changed = true;
@@ -71,8 +73,15 @@ function deliveredCursorEntry(prior, candidate, objectKey, now) {
         uploaded_byte_size: candidate.byte_size,
         last_seen_at: now.toISOString(),
     };
+    // BLI-11119: a re-offer that stubbed again earned another marker, not the
+    // transcript. The entry says so and keeps its mark for the next pass.
+    if (isRedactionStubObjectKey(objectKey)) {
+        markCursorEntryStubbed(entry);
+        return entry;
+    }
     // The mark says "this pointer is a stub"; the pointer written above is not.
     delete entry.stub_reoffer;
+    delete entry.stubbed;
     return entry;
 }
 export function advanceBackfillCursorThroughResolvedPrefix(options) {

package/dist/commands/backfill-report.js

@@ -26,7 +26,11 @@ export async function reportBackfillOutcome(command, io, ctx, upload) {
         failureReason ??= sessionReportFailureReason(posted);
     }
     if (posted.acknowledged) {
-        await checkpointResolvedBackfillProgress(ctx, upload);
+        // BLI-11112: the sync's stub pass saw only stubbed sessions, so it records
+        // their pointers and never moves the history cursor past anything else.
+        await checkpointResolvedBackfillProgress(ctx, upload, {
+            advanceCursor: !command.stubPass,
+        });
     }
     const completion = summarizeBackfillCompletion({
         ctx,
@@ -35,7 +39,7 @@ export async function reportBackfillOutcome(command, io, ctx, upload) {
         stoppedEarly: Boolean(blockedAt),
         failureReason,
     });
-    if (completion.status === "complete" && command.all) {
+    if (completion.status === "complete" && command.all && !command.stubPass) {
         await writeAllHistoryCompletionMarker(ctx);
     }
     return {
@@ -47,7 +51,9 @@ export async function reportBackfillOutcome(command, io, ctx, upload) {
             completion,
             blockedAt,
         }),
-        stub_reoffer: summarizeStubReoffer(ctx.stubReoffer, upload.uploadable),
+        stub_reoffer: summarizeStubReoffer(ctx.stubReoffer, upload.uploadable, posted.acknowledged ? upload.durableCandidateKeys : new Set(), 
+        // One sync result per batch the loop reached; a stopped run reached fewer.
+        upload.batches.slice(0, upload.syncResults.length).flatMap((batch) => batch.candidates)),
     };
 }
 /**
@@ -114,7 +120,7 @@ function sessionReportFailureReason(posted) {
  * both writes wait on the report acknowledgement, because a cursor advanced
  * past a session the server never recorded can never be walked back.
  */
-async function checkpointResolvedBackfillProgress(ctx, upload) {
+async function checkpointResolvedBackfillProgress(ctx, upload, options) {
     const { paths, scan, cursor, now, deterministicSkipCandidateKeys } = ctx;
     if (upload.durableCandidateKeys.size > 0) {
         await recordBackfillDurableSessionPointers({
@@ -124,6 +130,8 @@ async function checkpointResolvedBackfillProgress(ctx, upload) {
             now,
         });
     }
+    if (!options.advanceCursor)
+        return;
     const cursorAdvanced = advanceBackfillCursorThroughResolvedPrefix({
         cursor,
         candidates: scan.candidates,

package/dist/commands/backfill-scan.js

@@ -21,7 +21,9 @@ import { labelOutsideRootCandidates, outsideRootsWorkspace, } from "./backfill-o
 import { reasonCountsFor } from "./backfill-reasons.js";
 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
@@ -51,15 +53,19 @@ export async function scanBackfillRun(command, io, now) {
     // BLI-11102: a redaction-crash stub is not a delivery. The server names
     // them; those sessions reopen exactly like pointer-less ones. A dry run
     // keeps its one-request contract (the reachability probe) and does not ask.
-    const stubReoffer = command.dryRun
-        ? emptyStubReofferPlan("dry_run")
-        : await loadStubReofferPlan({
-            paths,
-            dashboardUrl: scope.dashboardUrl,
-            sources,
-            fetchImpl: io.fetch,
-        });
+    // BLI-11112: the sync's stub pass brings the door's answer with it.
+    const stubReoffer = command.stubPass
+        ? command.stubPass.plan
+        : command.dryRun
+            ? emptyStubReofferPlan("dry_run")
+            : await loadStubReofferPlan({
+                paths,
+                dashboardUrl: scope.dashboardUrl,
+                sources,
+                fetchImpl: io.fetch,
+            });
     reopenStubbedSessions(pointerlessTerminalSessions, stubReoffer);
+    const stubCursorHashes = await loadStubCursorHashes(paths, stubReoffer);
     const scan = await scanBackfillSessions({
         command,
         homeDir: command.homeDir ?? os.homedir(),
@@ -69,6 +75,8 @@ export async function scanBackfillRun(command, io, now) {
         window: scope.window,
         cursor,
         pointerlessTerminalSessions,
+        stubReoffer,
+        stubCursorHashes,
         now,
     });
     const reasonCounts = await auditScannedCandidates(scan, worktreeDiscovery.incomplete_reasons);
@@ -125,12 +133,25 @@ async function scanBackfillSessions(options) {
     const claudeAttribution = options.sources.includes("claude_code")
         ? await scanClaudeHistory(options, claudeProjectsDir, scanLimit)
         : null;
+    // BLI-11119: a stubbed session is found by the id in its content or by the
+    // file hash its cursor entry recorded, across every root the scan walked.
+    const scanned = locateStubbedSessions({
+        plan: options.stubReoffer,
+        candidates: [
+            ...(codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
+            ...(claudeAttribution?.results.map(normalizeClaudeCandidate) ?? []),
+        ],
+        cursorHashes: options.stubCursorHashes,
+        sinceMinutes: options.window.since_minutes,
+    });
     const selection = selectBackfillCandidates({
-        codexAttribution,
-        claudeAttribution,
+        scanned,
         cursor: options.cursor,
         pointerlessTerminalSessions: options.pointerlessTerminalSessions,
         maxFiles: options.command.maxFiles,
+        onlySessions: options.command.stubPass
+            ? new Set(options.command.stubPass.plan.sessions.keys())
+            : undefined,
     });
     // BLI-11091: a session outside every approved root is labelled, not
     // refused. It rides the synthetic outside-roots workspace from here on, so
@@ -194,10 +215,9 @@ 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.codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
-        ...(options.claudeAttribution?.results.map(normalizeClaudeCandidate) ?? []),
-    ]
+    const allCandidates = options.scanned
+        .filter((candidate) => !options.onlySessions ||
+        options.onlySessions.has(stubSessionKey(candidate.source, candidate.session_id)))
         .filter((candidate) => isAfterCursor(candidate, options.cursor) ||
         isPointerlessTerminalRetry(candidate, options.pointerlessTerminalSessions))
         .sort((a, b) => compareBackfillCandidatesForRetry(a, b, options.pointerlessTerminalSessions));
@@ -257,6 +277,7 @@ function normalizeCodexCandidate(result) {
     return {
         source: "codex",
         session_id: result.codex_session_id,
+        session_id_source: result.session_id_source,
         file_path: result.file_path,
         state: result.state,
         reason: result.reason,

package/dist/commands/backfill-stub-locate.js

@@ -0,0 +1,104 @@
+/**
+ * Where on this machine is the transcript behind a stub? (BLI-11119)
+ *
+ * The stubs door names a session by the id inside its object key, and the
+ * collector wrote that key with the id it read from the transcript's CONTENT
+ * (`session_meta.id` for Codex). A rollout's file name does not always carry
+ * that id: a resumed or forked session is filed as
+ * `rollout-<time>-<parent>_<child>.jsonl` while its first line names another
+ * id, and Codex moves files from `sessions/` into `archived_sessions/`. So a
+ * stubbed session is located the way it was keyed, across every root the scan
+ * walked, never by file name alone:
+ *
+ * 1. a scanned session whose id matches (`found_by: session_meta`, or
+ *    `file_name` when the file's first line gave no id and the scan fell back
+ *    to the name, which is then the id the key used too);
+ * 2. otherwise a scanned file whose sha256 equals the cursor entry's
+ *    `file_hash_sha256` for that session (`found_by: file_hash`); it is offered
+ *    under the STUBBED session's id, because the server retires a stub only for
+ *    a successor that names the same session;
+ * 3. otherwise `not_found`, recorded on the cursor so the scheduled sync stops
+ *    rescanning history for it every tick (see `sync-stub-heal.ts`).
+ */
+import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { stubSessionKey } from "../evidence-stubs-client.js";
+/** How many per-session lines the locate log carries; the counts cover the rest. */
+const LOGGED_SESSION_LIMIT = 25;
+/** `codex:<id>` -> the file hash the cursor last recorded for that stubbed session. */
+export async function loadStubCursorHashes(paths, plan) {
+    const hashes = new Map();
+    if (plan.sessions.size === 0)
+        return hashes;
+    for (const source of ["codex", "claude_code"]) {
+        const filename = source === "claude_code" ? CLAUDE_CURSOR_FILENAME : undefined;
+        const cursor = await readRawEvidenceCursor(paths, { filename }).catch(() => null);
+        if (!cursor)
+            continue;
+        for (const key of plan.sessions.keys()) {
+            if (!key.startsWith(`${source}:`))
+                continue;
+            const hash = cursor.sessions[key.slice(source.length + 1)]?.file_hash_sha256;
+            if (hash)
+                hashes.set(key, hash);
+        }
+    }
+    return hashes;
+}
+/**
+ * Match every stubbed session to a scanned file, record how on `plan.found_by`,
+ * and return the scanned candidates plus one candidate per hash match, carrying
+ * the stubbed session's id. Logs the outcome, found or not.
+ */
+export function locateStubbedSessions(options) {
+    const { plan } = options;
+    if (plan.sessions.size === 0)
+        return options.candidates;
+    const byKey = new Map();
+    const byHash = new Map();
+    for (const candidate of options.candidates) {
+        byKey.set(stubSessionKey(candidate.source, candidate.session_id), candidate);
+        if (candidate.content_hash_sha256) {
+            const hashKey = `${candidate.source}:${candidate.content_hash_sha256}`;
+            if (!byHash.has(hashKey))
+                byHash.set(hashKey, candidate);
+        }
+    }
+    const extra = [];
+    const sessions = [];
+    for (const key of plan.sessions.keys()) {
+        const found = locateOne(key, byKey, byHash, options.cursorHashes);
+        plan.found_by.set(key, found.foundBy);
+        if (found.candidate)
+            extra.push(found.candidate);
+        sessions.push({ session: key, found_by: found.foundBy });
+    }
+    const counts = { session_meta: 0, file_name: 0, file_hash: 0, not_found: 0 };
+    for (const session of sessions)
+        counts[session.found_by] += 1;
+    console.error("[backfill] stubbed sessions located", JSON.stringify({
+        reason: counts.not_found === sessions.length ? "stub_sessions_not_found" : "stub_sessions_located",
+        sessions: sessions.length,
+        ...counts,
+        scanned_candidates: options.candidates.length,
+        since_minutes: options.sinceMinutes,
+        found_by: sessions.slice(0, LOGGED_SESSION_LIMIT),
+    }));
+    return extra.length > 0 ? [...options.candidates, ...extra] : options.candidates;
+}
+function locateOne(key, byKey, byHash, cursorHashes) {
+    const byId = byKey.get(key);
+    if (byId) {
+        const fromContent = byId.source === "codex" && byId.session_id_source === "session_meta";
+        return { foundBy: fromContent ? "session_meta" : "file_name" };
+    }
+    const at = key.indexOf(":");
+    const source = key.slice(0, at);
+    const hash = cursorHashes.get(key);
+    const byContent = hash ? byHash.get(`${source}:${hash}`) : undefined;
+    if (!byContent)
+        return { foundBy: "not_found" };
+    return {
+        foundBy: "file_hash",
+        candidate: { ...byContent, session_id: key.slice(at + 1), session_id_source: undefined },
+    };
+}

package/dist/commands/backfill-stub-reoffer.js

@@ -1,9 +1,18 @@
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { markCursorEntryStubbed } from "../cursors/raw-evidence-stub-entry.js";
 import { fetchStubbedSessions, stubSessionKey } from "../evidence-stubs-client.js";
 import { describeError } from "../health-detail.js";
 import { readLocalCollectorSessionFile } from "../local-state.js";
+import { candidateCursorKey } from "./backfill-candidates.js";
 export function emptyStubReofferPlan(reason) {
-    return { status: "skipped", reason, sessions: new Map(), stub_count: 0, marked_local_sessions: 0 };
+    return {
+        status: "skipped",
+        reason,
+        sessions: new Map(),
+        stub_count: 0,
+        marked_local_sessions: 0,
+        found_by: new Map(),
+    };
 }
 /** Ask the server which of this operator's pointers are stubs. Never throws; writes nothing. */
 export async function loadStubReofferPlan(options) {
@@ -24,6 +33,7 @@ export async function loadStubReofferPlan(options) {
         sessions,
         stub_count: answer.unique_stub_count,
         marked_local_sessions: 0,
+        found_by: new Map(),
     };
 }
 /**
@@ -33,7 +43,7 @@ export async function loadStubReofferPlan(options) {
 export async function markStubReoffers(paths, plan, now) {
     if (plan.sessions.size === 0)
         return;
-    plan.marked_local_sessions = await markStubbedSessions(paths, plan.sessions, now);
+    plan.marked_local_sessions = await markStubbedSessions(paths, plan, now);
 }
 /** Reopen stubbed sessions exactly like pointer-less ones: selected past the cursor, sorted first. */
 export function reopenStubbedSessions(reopen, plan) {
@@ -53,8 +63,10 @@ export function stubClaimsForCandidates(candidates, plan) {
     }
     return claims;
 }
-export function summarizeStubReoffer(plan, candidates) {
-    const reoffered = candidates.filter((candidate) => plan.sessions.has(stubSessionKey(candidate.source, candidate.session_id))).length;
+export function summarizeStubReoffer(plan, candidates, durableCandidateKeys = new Set(), attempted = candidates) {
+    const offered = candidates.filter((candidate) => plan.sessions.has(stubSessionKey(candidate.source, candidate.session_id)));
+    const stubsOf = (list) => list.reduce((total, candidate) => total + (plan.sessions.get(stubSessionKey(candidate.source, candidate.session_id))?.length ?? 0), 0);
+    const reoffered = offered.length;
     const summary = {
         status: plan.status,
         reason: plan.reason,
@@ -62,6 +74,9 @@ export function summarizeStubReoffer(plan, candidates) {
         sessions: plan.sessions.size,
         marked_local_sessions: plan.marked_local_sessions,
         reoffered_sessions: reoffered,
+        reoffered_stubs: stubsOf(offered.filter((candidate) => attempted.includes(candidate))),
+        replaced_stubs: stubsOf(offered.filter((candidate) => durableCandidateKeys.has(candidateCursorKey(candidate)))),
+        found_by: countFoundBy(plan),
     };
     if (plan.sessions.size > 0) {
         console.error("[backfill] redaction-stubbed sessions re-offered", JSON.stringify({
@@ -74,20 +89,43 @@ export function summarizeStubReoffer(plan, candidates) {
     }
     return summary;
 }
-async function markStubbedSessions(paths, sessions, now) {
+function countFoundBy(plan) {
+    const counts = { session_meta: 0, file_name: 0, file_hash: 0, not_found: 0 };
+    for (const method of plan.found_by.values())
+        counts[method] += 1;
+    return counts;
+}
+/**
+ * Mark every door-named session this cursor tracks, and make its entry tell
+ * the truth (BLI-11119): an entry written before the stub rule existed claimed
+ * the full file as uploaded. The door is the source of truth, so each such
+ * entry is reconciled to `stubbed: true` with the marker's bytes, counted and
+ * logged as `stub_cursor_reconciled`. A session the scan could not find in any
+ * root keeps `not_found_at`, so the scheduled sync waits before looking again.
+ */
+async function markStubbedSessions(paths, plan, now) {
     let marked = 0;
+    let reconciled = 0;
     for (const source of ["codex", "claude_code"]) {
         const filename = source === "claude_code" ? CLAUDE_CURSOR_FILENAME : undefined;
         try {
             const cursor = await readRawEvidenceCursor(paths, { filename });
             let changed = false;
-            for (const [key, pointerIds] of sessions) {
+            for (const [key, pointerIds] of plan.sessions) {
                 if (!key.startsWith(`${source}:`))
                     continue;
                 const entry = cursor.sessions[key.slice(source.length + 1)];
                 if (!entry)
                     continue;
-                entry.stub_reoffer = { reason: "stub_reoffered", stub_pointer_ids: pointerIds, marked_at: now.toISOString() };
+                const notFound = plan.found_by.get(key) === "not_found";
+                entry.stub_reoffer = {
+                    reason: "stub_reoffered",
+                    stub_pointer_ids: pointerIds,
+                    marked_at: now.toISOString(),
+                    ...(notFound ? { not_found_at: now.toISOString() } : {}),
+                };
+                if (markCursorEntryStubbed(entry))
+                    reconciled += 1;
                 changed = true;
                 marked += 1;
             }
@@ -100,5 +138,6 @@ async function markStubbedSessions(paths, sessions, now) {
             console.error("[backfill] stub mark not written to the cursor", JSON.stringify({ reason: "stub_mark_write_failed", source, ...describeError(error) }));
         }
     }
+    console.error("[backfill] stubbed sessions' cursor entries reconciled with the stubs door", JSON.stringify({ reason: "stub_cursor_reconciled", count: reconciled, marked_local_sessions: marked }));
     return marked;
 }

package/dist/commands/backfill-upload.js

@@ -20,10 +20,11 @@ const BACKFILL_MAX_CONSECUTIVE_FAILURES = 3;
  */
 export async function uploadBackfillBatches(command, io, lock, ctx) {
     const uploadable = uploadableCandidates(ctx.scan.candidates);
-    // Doctor needs a boundary after each session. Ordinary backfill retains
-    // its existing batching, and scheduled sync does not use this command.
+    // Doctor needs a boundary after each session, and so does the scheduled
+    // sync's stub pass (BLI-11112), which hands the lock to a waiting backfill
+    // at the next one. Ordinary backfill retains its existing batching.
     const plannedBatches = buildBackfillBatches(uploadable);
-    const batches = command.deadlineMs !== undefined || command.onProgress
+    const batches = command.deadlineMs !== undefined || command.onProgress || command.stubPass
         ? plannedBatches.flatMap((batch) => batch.candidates.map((candidate) => ({
             worktree: batch.worktree, candidates: [candidate],
         })))
@@ -72,6 +73,12 @@ export async function uploadBackfillBatches(command, io, lock, ctx) {
             failureReason = "deferred_budget_exhausted";
             break;
         }
+        if (command.stubPass?.shouldYield && (await command.stubPass.shouldYield())) {
+            blockedAt = stoppedAt("yielded to a waiting backfill", index);
+            failureReason = "yielded_to_backfill";
+            console.error("[collector stubs] stub pass yielded the collection lock to a waiting backfill", JSON.stringify({ reason: "backfill_waiting", sessions_done: index, sessions_left: batches.length - index }));
+            break;
+        }
         const outcome = await uploadOneBackfillBatch(command, io, ctx, batch, rawEvidenceBudget);
         foldBatchIntoTally(tally, batch, outcome);
         reportProgress();

package/dist/commands/backfill.js

@@ -103,7 +103,14 @@ export async function runBackfill(command, io) {
     if (plan.kind === "result")
         return plan.result;
     const { paths } = scanned;
-    const lock = await acquireBackfillLock(paths, now);
+    // BLI-11112: the sync's stub pass does not take the backfill lock. It runs
+    // under the collection lock, which already serialises it against any
+    // backfill, and the backfill lock is the flag a WAITING backfill raises: a
+    // person's backfill that arrives mid-pass must wait its turn, not bounce off
+    // `backfill_already_running`.
+    const lock = command.stubPass
+        ? { acquired: true, handle: { release: async () => undefined, heartbeat: async () => undefined } }
+        : await acquireBackfillLock(paths, now);
     if (!lock.acquired) {
         return lockHeldResult(command, scanned, {
             failureReason: "backfill_already_running",
@@ -112,29 +119,36 @@ export async function runBackfill(command, io) {
     }
     // BLI-11091: the scheduled sync holds this lock most of the time an agent
     // is working, so wait for it (bounded) instead of exiting at batch 0. Giving
-    // up is `sync_lock_held`, a blocked result and so a non-zero exit.
-    let waited;
-    try {
-        waited = await acquireSyncLockWithWait(paths, command.syncLockWaitMs ?? BACKFILL_SYNC_LOCK_WAIT_MS);
-    }
-    catch (error) {
-        await lock.handle.release();
-        throw error;
+    // up is `sync_lock_held`, a blocked result and so a non-zero exit. The
+    // sync's own stub pass (BLI-11112) runs inside the sync's lock and skips it.
+    let collectionLock;
+    if (command.stubPass) {
+        collectionLock = { handle: { release: async () => undefined } };
     }
-    if (!waited.acquired) {
-        await lock.handle.release();
-        return lockHeldResult(command, scanned, {
-            failureReason: "sync_lock_held",
-            what: "sync collection lock held",
-        });
+    else {
+        let waited;
+        try {
+            waited = await acquireSyncLockWithWait(paths, command.syncLockWaitMs ?? BACKFILL_SYNC_LOCK_WAIT_MS);
+        }
+        catch (error) {
+            await lock.handle.release();
+            throw error;
+        }
+        if (!waited.acquired) {
+            await lock.handle.release();
+            return lockHeldResult(command, scanned, {
+                failureReason: "sync_lock_held",
+                what: "sync collection lock held",
+            });
+        }
+        collectionLock = waited.lock;
     }
-    const collectionLock = waited.lock;
     try {
         // Backfill and scheduled/manual sync share upload spool and raw-evidence
         // cursors. Holding the same collection lock makes their read-modify-write
         // updates serial, while the dedicated backfill lock still prevents two
         // historical scans from running together.
-        if (scanned.scopedCursor.reset) {
+        if (scanned.scopedCursor.reset && !command.stubPass) {
             await writeBackfillCursor(paths, scanned.cursor);
         }
         // BLI-11102: mark server-named stubs as not delivered, under the lock

package/dist/commands/public-root.js

@@ -21,7 +21,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.156");
+    writeLine(io?.stdout ?? process.stdout, "0.2.158");
     return 0;
   }
 

package/dist/commands/session-sync-record.js

@@ -11,6 +11,7 @@ import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConf
 import { normalizeDashboardUrl } from "../upload-http.js";
 import { flushPendingCodexSessionReports, queueCodexSessionReport, } from "../upload.js";
 import { CLAUDE_CURSOR_FILENAME, countStaleSessions, readRawEvidenceCursor, recordSessionObservation, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { isRedactionStubObjectKey, markCursorEntryStubbed } from "../cursors/raw-evidence-stub-entry.js";
 import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
 import { liveSyncCursorEntryRequiresRetry } from "./session-sync-attribution.js";
 /**
@@ -331,5 +332,16 @@ function recordSourceObservation(options, result) {
         uploaded_byte_size: uploadedByteSize,
         last_seen_at: options.now.toISOString(),
     };
+    // BLI-11119: a pointer that is the redaction-crash marker is not a delivery.
+    // The entry records the marker's bytes, and keeps the re-offer mark while
+    // the stub still stands.
+    if (isRedactionStubObjectKey(uploadedObjectKey)) {
+        markCursorEntryStubbed(entry);
+        if (prior?.stub_reoffer)
+            entry.stub_reoffer = prior.stub_reoffer;
+        if (uploadedThisSync) {
+            console.error("[collector sync] session delivered only as a redaction-crash stub", JSON.stringify({ reason: "stub_cursor_recorded", source: options.source, byte_size: result.byte_size }));
+        }
+    }
     recordSessionObservation(options.cursor, sessionId, entry);
 }

package/dist/commands/session-sync-upload.js

@@ -10,6 +10,7 @@ import { startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from
 import { LocalUploadBlockedError, syncLocalAmbientEnvelope, } from "../upload.js";
 import { RAW_EVIDENCE_DEFAULT_BYTE_BUDGET, RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET, } from "../adapters/raw-evidence.js";
 import { liveSyncTargetKey, liveSyncTargetWorktrees, matchesLiveSyncWorktree, } from "./session-sync-attribution.js";
+import { runYieldingAtBoundaries } from "./sync-yield.js";
 const CLAUDE_DAMP_GROWTH_BYTES = 256 * 1024;
 const CLAUDE_DAMP_MAX_AGE_MS = 6 * 60 * 60 * 1000;
 /**
@@ -33,10 +34,13 @@ export async function syncEveryTargetWorktree(options) {
         remainingBytes: RAW_EVIDENCE_DEFAULT_BYTE_BUDGET,
         remainingObjects: RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET,
     };
-    const outcomes = [];
-    let everyWorktreeUploaded = true;
-    for (const worktree of syncWorktrees) {
-        const outcome = await syncOneWorktree({
+    // BLI-11112: a waiting backfill takes the lock at the next worktree
+    // boundary; the worktrees not reached stay pending for it or the next tick.
+    const loop = await runYieldingAtBoundaries({
+        items: syncWorktrees,
+        shouldYield: run.yieldCheck,
+        describe: (outcome) => ({ status: outcome.sync.status }),
+        runOne: (worktree) => syncOneWorktree({
             run,
             now: options.now,
             plan: options.plan,
@@ -50,16 +54,16 @@ export async function syncEveryTargetWorktree(options) {
             recordDampedClaudeSession: (sessionId, priorPointer) => {
                 dampedClaudePointers.set(sessionId, priorPointer);
             },
-        });
-        everyWorktreeUploaded =
-            everyWorktreeUploaded && outcome.sync.status === "uploaded";
-        outcomes.push(outcome);
-    }
+        }),
+    });
+    const outcomes = loop.results;
+    const everyWorktreeUploaded = outcomes.every((outcome) => outcome.sync.status === "uploaded");
     return {
         outcomes,
         everyWorktreeUploaded,
         claudePriorDurablePointers: claudeDurablePointersFromCursor(options.plan.claudeCursorBefore),
         growthDampedSessionCount: dampedClaudePointers.size,
+        yieldedWorktreesLeft: loop.left,
     };
 }
 /** Every Claude session the cursor already holds a durable pointer for. */

package/dist/commands/session-sync.js

@@ -151,6 +151,7 @@ export async function runAttributedWorktreeSync(options) {
         failure_records: health.failure_records,
         notice: health.notice,
         hold: health.hold,
+        yielded_worktrees_left: worktreePass.yieldedWorktreesLeft,
         sessions_observed: sessions.length,
         sessions_outside_root: health.sessions_outside_root,
         outside_root_directories: health.outside_root_directories,

package/dist/commands/sync-run.js

@@ -3,6 +3,8 @@ import { discoverCommandWorktrees } from "./local-discovery.js";
 import { runAttributedWorktreeSync } from "./session-sync.js";
 import { reportMultiRepoSync, reportNoWorktreeSync, reportSingleRepoSync, } from "./sync-report.js";
 import { resolveSyncCollectionRoots } from "./sync-roots.js";
+import { healStubsDuringTick } from "./sync-stub-heal.js";
+import { backfillWaitingCheck } from "./sync-yield.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { rawEvidenceDedupSummary, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
 /**
@@ -18,7 +20,8 @@ export async function runSyncLocked(command, io) {
     // holds 559 copies of one rollout needs the disk back before it stages
     // anything else (BLI-3066). Safe by construction — a duplicate is identical
     // by content hash to the survivor.
-    const dedup = await sweepDuplicateStagedRawEvidence(getCollectorRuntimePaths(command.homeDir), io.env);
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const dedup = await sweepDuplicateStagedRawEvidence(paths, io.env);
     if (!dedup.skipped && dedup.removed_dirs > 0) {
         writeLine(io.stdout, rawEvidenceDedupSummary(dedup));
     }
@@ -37,7 +40,11 @@ export async function runSyncLocked(command, io) {
         startContexts: false,
         worktrees,
         fetchImpl: io.fetch,
+        yieldCheck: backfillWaitingCheck(paths),
     });
+    // After the tick's own uploads, still under the lock: re-offer up to 25 of
+    // this machine's stubbed sessions. Never fails the tick.
+    await healStubsDuringTick(command, io);
     if (discoveryNotice) {
         run.discovery_partial = true;
         run.notice = [discoveryNotice, run.notice].filter(Boolean).join("; ");

package/dist/commands/sync-stub-heal.js

@@ -0,0 +1,155 @@
+import { runBackfill } from "./backfill.js";
+import { loadStubReofferPlan } from "./backfill-stub-reoffer.js";
+import { backfillWaitingCheck } from "./sync-yield.js";
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { describeError } from "../health-detail.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
+/** At most this many stubbed sessions are re-offered per tick (one backfill batch). */
+export const SYNC_STUB_SESSIONS_PER_TICK = 25;
+const DAY_MS = 24 * 60 * 60_000;
+/**
+ * BLI-11119: a stubbed session a re-offer could not find in any root, by
+ * content id or file hash, is looked for again after this long. Without it
+ * every tick rescanned (and hashed) every transcript back to the session's
+ * date for a file that is gone.
+ */
+export const STUB_NOT_FOUND_RETRY_MS = DAY_MS;
+const DEFAULT_DEPS = { runBackfill, loadPlan: loadStubReofferPlan };
+export async function healStubsDuringTick(command, io, deps = DEFAULT_DEPS, now = new Date()) {
+    const summary = {
+        reason: "unknown",
+        stubs_asked: 0,
+        stubs_reoffered: 0,
+        stubs_remaining: 0,
+        sessions_local: 0,
+        sessions_selected: 0,
+        sessions_not_found_recently: 0,
+    };
+    try {
+        summary.reason = await runStubPass(command, io, deps, now, summary);
+    }
+    catch (error) {
+        summary.reason = "stub_pass_threw";
+        console.error("[collector stubs] tick stub pass threw; the tick is unaffected", JSON.stringify({ reason: "stub_pass_threw", ...describeError(error) }));
+    }
+    console.error("[collector stubs] tick", JSON.stringify(summary));
+    return summary;
+}
+async function runStubPass(command, io, deps, now, summary) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    // A backfill waiting for the lock heals stubs itself, with the whole door.
+    if ((await inspectBackfillLock(paths)).held)
+        return "backfill_running";
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const sessionFile = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (!sessionFile)
+        return "no_device_session";
+    const sources = config?.collect_claude_jsonl === false ? ["codex"] : ["codex", "claude_code"];
+    const dashboardUrl = (sessionFile.dashboard_url ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL)
+        .trim()
+        .replace(/\/+$/, "");
+    const plan = await deps.loadPlan({ paths, dashboardUrl, sources, fetchImpl: io.fetch });
+    summary.stubs_asked = plan.stub_count;
+    summary.stubs_remaining = plan.stub_count;
+    if (plan.status === "skipped")
+        return plan.reason;
+    if (plan.status === "unavailable")
+        return `stub_door_unavailable:${plan.reason}`;
+    if (plan.sessions.size === 0)
+        return "no_stubs";
+    const local = await locallyTrackedStubSessions(paths, plan);
+    summary.sessions_local = local.length;
+    if (local.length === 0)
+        return "stubs_not_on_this_machine";
+    const lookable = local.filter((session) => !notFoundRecently(session.notFoundAt, now));
+    summary.sessions_not_found_recently = local.length - lookable.length;
+    if (lookable.length === 0)
+        return "stubs_not_found_recently";
+    const selected = lookable.slice(0, SYNC_STUB_SESSIONS_PER_TICK);
+    summary.sessions_selected = selected.length;
+    const trimmed = {
+        ...plan,
+        sessions: new Map(selected.map((session) => [session.key, session.pointerIds])),
+        stub_count: selected.reduce((total, session) => total + session.pointerIds.length, 0),
+        marked_local_sessions: 0,
+        found_by: new Map(),
+    };
+    const window = stubWindow(selected, sessionFile.paired_at, now);
+    const result = await deps.runBackfill({
+        homeDir: command.homeDir,
+        repoRoot: command.repoRoot,
+        maxDepth: command.maxDepth,
+        maxRepos: command.maxRepos,
+        ...window,
+        dryRun: false,
+        yes: true,
+        json: true,
+        stubPass: { plan: trimmed, shouldYield: backfillWaitingCheck(paths) },
+    }, backfillIoFor(io));
+    const outcome = result.stub_reoffer;
+    summary.stubs_reoffered = outcome?.reoffered_stubs ?? 0;
+    summary.stubs_remaining = Math.max(0, plan.stub_count - (outcome?.replaced_stubs ?? 0));
+    return stubPassReason(result);
+}
+/** Door-order list of the stubbed sessions whose cursor entry lives on this machine. */
+async function locallyTrackedStubSessions(paths, plan) {
+    const cursors = {
+        codex: await readRawEvidenceCursor(paths).catch(() => null),
+        claude_code: await readRawEvidenceCursor(paths, { filename: CLAUDE_CURSOR_FILENAME }).catch(() => null),
+    };
+    const local = [];
+    for (const [key, pointerIds] of plan.sessions) {
+        const at = key.indexOf(":");
+        const source = key.slice(0, at);
+        const entry = cursors[source]?.sessions[key.slice(at + 1)];
+        if (entry) {
+            local.push({ key, pointerIds, mtimeMs: entry.file_mtime_ms, notFoundAt: entry.stub_reoffer?.not_found_at ?? null });
+        }
+    }
+    return local;
+}
+function notFoundRecently(notFoundAt, now) {
+    if (!notFoundAt)
+        return false;
+    const at = Date.parse(notFoundAt);
+    return Number.isFinite(at) && now.getTime() - at < STUB_NOT_FOUND_RETRY_MS;
+}
+/**
+ * The narrowest backfill window that still reaches every selected session:
+ * back to the oldest one's file time plus a day. A backfill window never
+ * reaches before pairing, so an older session (or one with no recorded time)
+ * asks for all history instead.
+ */
+function stubWindow(selected, pairedAt, now) {
+    const times = selected.map((session) => session.mtimeMs);
+    const oldest = Math.min(...times);
+    const paired = pairedAt ? Date.parse(pairedAt) : Number.NaN;
+    if (times.some((time) => !Number.isFinite(time) || time <= 0))
+        return { all: true };
+    if (!Number.isFinite(paired) || oldest < paired)
+        return { all: true };
+    return { all: false, sinceDays: Math.max(1, Math.ceil((now.getTime() - oldest) / DAY_MS) + 1) };
+}
+function stubPassReason(result) {
+    const outcome = result.stub_reoffer;
+    if (result.failure_reason === "yielded_to_backfill")
+        return "yielded_to_backfill";
+    if (result.status === "blocked")
+        return `stub_backfill_blocked:${result.failure_reason ?? "unknown"}`;
+    if (!outcome || outcome.reoffered_sessions === 0)
+        return "stubs_not_found_locally";
+    if (outcome.replaced_stubs < outcome.reoffered_stubs) {
+        return `stubs_partly_replaced:${result.failure_reason ?? "unknown"}`;
+    }
+    return "stubs_reoffered";
+}
+/**
+ * The backfill writes its `--json` result and progress to stdout; the sync's
+ * stdout is its own `--json` receipt, so those lines go nowhere and the
+ * backfill's own `[backfill]` logs still reach stderr.
+ */
+function backfillIoFor(io) {
+    const discard = { write: () => true };
+    return { stdin: io.stdin, stdout: discard, stderr: io.stderr, fetch: io.fetch };
+}

package/dist/commands/sync-yield.js

@@ -0,0 +1,61 @@
+/**
+ * BLI-11112: the scheduled sync hands the collection lock to a waiting
+ * backfill at its next worktree boundary.
+ *
+ * A tick on a machine with a backlog now runs 10 to 15 minutes, longer than
+ * the backfill's old wait, so a person who typed `cockpit backfill` sat out the
+ * whole tick and got `sync_lock_held`. The rule is plain: a backfill that wants
+ * the lock takes the backfill lock FIRST and then waits for the collection
+ * lock (`backfill-lock-wait.ts`). The backfill lock being held is the waiter's
+ * flag. Before each worktree upload the sync asks whether that flag is up; if
+ * it is, it finishes nothing new, writes down what it already did, and
+ * releases the lock. The worktrees it did not reach stay pending in the cursor
+ * and are exactly what the backfill (or the next tick) picks up. A worktree
+ * already uploading is never interrupted, so the wait is bounded by one
+ * worktree's upload, which is why each one logs its own elapsed time.
+ */
+import { inspectBackfillLock } from "../backfill-lock.js";
+/** The waiter's flag: the backfill lock is held while its owner waits for ours. */
+export function backfillWaitingCheck(paths, inspect = inspectBackfillLock) {
+    return async () => {
+        try {
+            return (await inspect(paths)).held;
+        }
+        catch {
+            // A lock probe that cannot read the file means nobody is waiting; the
+            // sync carries on exactly as it did before this rule existed.
+            return false;
+        }
+    };
+}
+/**
+ * Run `runOne` over `items` in order, asking `shouldYield` before each one.
+ * The first `true` stops the loop; nothing already started is interrupted.
+ */
+export async function runYieldingAtBoundaries(options) {
+    const now = options.now ?? (() => Date.now());
+    const results = [];
+    const started = now();
+    for (const [index, item] of options.items.entries()) {
+        if (options.shouldYield && (await options.shouldYield())) {
+            const left = options.items.length - index;
+            console.error("[session-sync] yielded the collection lock to a waiting backfill", JSON.stringify({
+                reason: "backfill_waiting",
+                worktrees_done: index,
+                worktrees_left: left,
+                elapsed_ms: now() - started,
+            }));
+            return { results, yielded: true, left };
+        }
+        const itemStarted = now();
+        const result = await options.runOne(item);
+        results.push(result);
+        console.error("[session-sync] worktree synced", JSON.stringify({
+            index: index + 1,
+            total: options.items.length,
+            elapsed_ms: now() - itemStarted,
+            ...(options.describe ? options.describe(result) : {}),
+        }));
+    }
+    return { results, yielded: false, left: 0 };
+}

package/dist/cursors/raw-evidence-cursor.js

@@ -196,6 +196,7 @@ function parseSessionEntry(value) {
         uploaded_byte_size: optionalNumberOrNull(record["uploaded_byte_size"]),
         last_seen_at: lastSeenAt,
         ...parseStubReoffer(record["stub_reoffer"]),
+        ...(record["stubbed"] === true ? { stubbed: true } : {}),
     };
 }
 function parseStubReoffer(value) {
@@ -208,7 +209,15 @@ function parseStubReoffer(value) {
         : [];
     if (record["reason"] !== "stub_reoffered" || !markedAt || ids.length === 0)
         return {};
-    return { stub_reoffer: { reason: "stub_reoffered", stub_pointer_ids: ids, marked_at: markedAt } };
+    const notFoundAt = optionalString(record["not_found_at"]);
+    return {
+        stub_reoffer: {
+            reason: "stub_reoffered",
+            stub_pointer_ids: ids,
+            marked_at: markedAt,
+            ...(notFoundAt ? { not_found_at: notFoundAt } : {}),
+        },
+    };
 }
 function parseCheckpoints(value) {
     if (!value || typeof value !== "object")

package/dist/cursors/raw-evidence-stub-entry.js

@@ -0,0 +1,39 @@
+/**
+ * A redaction-crash stub is a promise to come back, not a delivery (BLI-11119).
+ *
+ * When the redactor crashed, the collector uploaded the 42-byte marker
+ * `REDACTION_STUB_TEXT` in place of the transcript, and the cursor entry then
+ * recorded the ORIGINAL file size as uploaded. Nothing local ever considered
+ * the session undelivered. This module is the one place a cursor entry is told
+ * the truth about a stub: `stubbed: true`, `uploaded_byte_size` the marker's
+ * 42 bytes, and `byte_offset` 0 because no session byte is durable.
+ *
+ * Two ways a stub is recognised, both deterministic:
+ * - at write time, by the object key: every transcript key's last segment
+ *   starts with the first 16 hex of its content hash (a re-keyed pointer keeps
+ *   that prefix), and the marker always hashes to `REDACTION_STUB_SHA256`;
+ * - after the fact, by the stubs door's answer, which is the source of truth
+ *   for every entry written before this rule existed.
+ */
+import { REDACTION_STUB_BYTE_SIZE, REDACTION_STUB_SHA256, } from "@bli-cockpit/telemetry-core";
+const STUB_KEY_PREFIX = REDACTION_STUB_SHA256.slice(0, 16);
+/** True when this object key names the redaction-crash marker, not a transcript. */
+export function isRedactionStubObjectKey(objectKey) {
+    if (!objectKey)
+        return false;
+    const segment = objectKey.slice(objectKey.lastIndexOf("/") + 1);
+    return segment.startsWith(STUB_KEY_PREFIX);
+}
+/**
+ * Make the entry say what the server holds: a stub. Returns whether anything
+ * changed, so a caller reconciling old entries can count what it corrected.
+ */
+export function markCursorEntryStubbed(entry) {
+    const changed = entry.stubbed !== true ||
+        entry.uploaded_byte_size !== REDACTION_STUB_BYTE_SIZE ||
+        entry.byte_offset !== 0;
+    entry.stubbed = true;
+    entry.uploaded_byte_size = REDACTION_STUB_BYTE_SIZE;
+    entry.byte_offset = 0;
+    return changed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.156",
+  "version": "0.2.158",
   "private": false,
   "type": "module",
   "bin": {