@bli-cockpit/cli 0.2.156 → 0.2.157

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

@@ -22,6 +22,7 @@ import { reasonCountsFor } from "./backfill-reasons.js";
 import { blockedBackfillResult } from "./backfill-result.js";
 import { emptyStubReofferPlan, loadStubReofferPlan, reopenStubbedSessions, } from "./backfill-stub-reoffer.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,14 +52,17 @@ 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 scan = await scanBackfillSessions({
         command,
@@ -131,6 +135,9 @@ async function scanBackfillSessions(options) {
         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
@@ -198,6 +205,8 @@ function selectBackfillCandidates(options) {
         ...(options.codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
         ...(options.claudeAttribution?.results.map(normalizeClaudeCandidate) ?? []),
     ]
+        .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));

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

@@ -2,6 +2,7 @@ import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, writeRawEvidenceCursor,
 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 };
 }
@@ -53,8 +54,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 +65,8 @@ 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)))),
     };
     if (plan.sessions.size > 0) {
         console.error("[backfill] redaction-stubbed sessions re-offered", JSON.stringify({

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.157");
     return 0;
   }
 

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,135 @@
+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;
+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,
+    };
+    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 selected = local.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,
+    };
+    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 });
+    }
+    return local;
+}
+/**
+ * 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/package.json

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