@bli-cockpit/cli 0.2.237 → 0.2.238

package/dist/commands/agent-setup.js

@@ -46,6 +46,47 @@ export function claudeDefaultEffort(model) {
 const claudeFamily = (model) => /opus|sonnet|haiku/i.exec(model ?? "")?.[0].toLowerCase() ?? null;
 /** Bounded, explicit locations only. Never recurse through a home or read env files. */
 export async function collectAgentSetup(home, platform = process.platform, io = files, now = new Date()) {
+    const reader = createSetupReader(home, platform, io);
+    const { paths, join, read, list, json } = reader;
+    const resolveVersion = createVersionResolver(reader, platform, io);
+    // Everything slow starts together: both `--version` checks (up to 5 s each) and
+    // both transcript samples run side by side, so the whole step costs one wait.
+    const observe = async (tool) => {
+        const samples = await io.transcripts?.(tool, home).catch(() => []) ?? [];
+        return observeTranscripts(tool, samples);
+    };
+    const claudeObserving = observe("claude"), codexObserving = observe("codex");
+    const [claudeVersion, codexVersion, claudeObserved, codexObserved] = await Promise.all([resolveVersion("claude", claudeObserving), resolveVersion("codex", codexObserving), claudeObserving, codexObserving]);
+    const codexHooks = await json(".codex", "hooks.json");
+    const claudePlugins = await json(".claude", "plugins", "installed_plugins.json");
+    const { pluginSkills, pluginAgents, pluginInventoryUnknown } = await readPluginInventory(claudePlugins, paths, io);
+    const claudeSkills = await list(".claude", "skills");
+    const claudeAgents = await list(".claude", "agents");
+    const sharedSkills = await list(".agents", "skills");
+    const codexSkills = await list(".codex", "skills");
+    const systemSkills = await list(".codex", "skills", ".system");
+    const claudeSettings = await json(".claude", "settings.json");
+    const claudeConfig = await json(".claude.json");
+    const toml = await read(join(".codex", "config.toml"));
+    // Read only simple quoted scalar values. Complex TOML is unknown, not guessed.
+    const rootToml = toml?.split(/^\s*\[/m)[0] ?? "";
+    const scalar = (key) => safeName(new RegExp(`^${key}\\s*=\\s*"([^"\\n]+)"\\s*(?:#.*)?$`, "m").exec(rootToml)?.[1]);
+    const codexMcp = readCodexMcp(toml);
+    const claudeMcp = readClaudeMcp(claudeConfig);
+    const instructions = await readInstructionFiles(join, io);
+    const result = buildSetupInventory({
+        now, platform, claudeSettings, claudeObserved, codexObserved,
+        claudeVersion, codexVersion, claudeSkills, claudeAgents, sharedSkills, codexSkills, systemSkills,
+        claudePlugins, pluginInventoryUnknown, pluginSkills, pluginAgents, claudeMcp, codexMcp,
+        toml, rootToml, scalar, codexHooks, instructions
+    });
+    const evidence = (tool) => ({ version_source: result[tool].version_source, model_basis: result[tool].model_basis, effort_basis: result[tool].effort_basis });
+    console.error("[setup] versions read", JSON.stringify({ reason: "version_resolved", claude: evidence("claude"), codex: evidence("codex"), transcript_files: { claude: claudeObserved.files, codex: codexObserved.files } }));
+    const unknownFields = [result.claude, result.codex].reduce((count, tool) => count + ["skills", "plugins", "agents", "hooks", "mcp"].filter(key => tool[key] === null).length, 0);
+    console.error("[setup] inventory read", JSON.stringify({ reason: unknownFields ? "inventory_partial" : "inventory_observed", unknown_fields: unknownFields, os: result.os, mcp_count: (result.claude.mcp?.length ?? 0) + (result.codex.mcp?.length ?? 0) }));
+    return result;
+}
+function createSetupReader(home, platform, io) {
     const paths = platform === "win32" ? path.win32 : path.posix;
     const join = (...parts) => paths.join(home, ...parts);
     const read = async (file) => {
@@ -76,8 +117,12 @@ export async function collectAgentSetup(home, platform = process.platform, io =
             return null;
         }
     };
+    return { paths, join, read, list, json };
+}
+function createVersionResolver(reader, platform, io) {
+    const { paths, join, read } = reader;
     const packageName = (tool) => tool === "claude" ? "@anthropic-ai/claude-code" : "@openai/codex";
-    const versionFromPackage = async (tool) => {
+    async function versionFromPackage(tool) {
         const parts = packageName(tool).split("/");
         // Where npm puts a global package: Windows keeps it under AppData, macOS
         // under the prefix of the node that installed it (Homebrew, /usr/local,
@@ -107,7 +152,8 @@ export async function collectAgentSetup(home, platform = process.platform, io =
             }
         }
         return null;
-    };
+    }
+    ;
     const resolveVersion = async (tool, observing) => {
         const viaCli = await io.version?.(tool, platform).catch(() => null);
         if (safeName(viaCli))
@@ -120,16 +166,9 @@ export async function collectAgentSetup(home, platform = process.platform, io =
         const viaTranscript = safeName((await observing).version);
         return viaTranscript ? { value: viaTranscript, source: "transcript" } : { value: null, source: "none" };
     };
-    // Everything slow starts together: both `--version` checks (up to 5 s each) and
-    // both transcript samples run side by side, so the whole step costs one wait.
-    const observe = async (tool) => {
-        const samples = await io.transcripts?.(tool, home).catch(() => []) ?? [];
-        return observeTranscripts(tool, samples);
-    };
-    const claudeObserving = observe("claude"), codexObserving = observe("codex");
-    const [claudeVersion, codexVersion, claudeObserved, codexObserved] = await Promise.all([resolveVersion("claude", claudeObserving), resolveVersion("codex", codexObserving), claudeObserving, codexObserving]);
-    const codexHooks = await json(".codex", "hooks.json");
-    const claudePlugins = await json(".claude", "plugins", "installed_plugins.json");
+    return resolveVersion;
+}
+async function readPluginInventory(claudePlugins, paths, io) {
     const pluginSkills = [], pluginAgents = [];
     let pluginInventoryUnknown = false;
     for (const [pluginName, installations] of Object.entries(object(claudePlugins?.plugins))) {
@@ -142,45 +181,55 @@ export async function collectAgentSetup(home, platform = process.platform, io =
                 continue;
             }
             for (const category of ["skills", "agents"]) {
-                try {
-                    const entries = names(await io.list(paths.join(directory, category)));
-                    (category === "skills" ? pluginSkills : pluginAgents).push(...entries.map(name => `${pluginName}.${name}`));
-                }
-                catch (error) {
-                    if (error.code !== "ENOENT")
-                        pluginInventoryUnknown = true;
-                }
+                const target = category === "skills" ? pluginSkills : pluginAgents;
+                if (await readPluginCategory(pluginName, directory, category, paths, io, target))
+                    pluginInventoryUnknown = true;
             }
         }
     }
-    const claudeSkills = await list(".claude", "skills");
-    const claudeAgents = await list(".claude", "agents");
-    const sharedSkills = await list(".agents", "skills");
-    const codexSkills = await list(".codex", "skills");
-    const systemSkills = await list(".codex", "skills", ".system");
-    const claudeSettings = await json(".claude", "settings.json");
-    const claudeConfig = await json(".claude.json");
-    const toml = await read(join(".codex", "config.toml"));
-    // Read only simple quoted scalar values. Complex TOML is unknown, not guessed.
-    const rootToml = toml?.split(/^\s*\[/m)[0] ?? "";
-    const scalar = (key) => safeName(new RegExp(`^${key}\\s*=\\s*"([^"\\n]+)"\\s*(?:#.*)?$`, "m").exec(rootToml)?.[1]);
-    const codexMcp = toml === null ? null : [...toml.matchAll(/^\s*\[mcp_servers\.(?:"([a-z0-9_.@+-]+)"|([a-z0-9_-]+))\]\s*$/gim)].flatMap(match => {
+    return { pluginSkills, pluginAgents, pluginInventoryUnknown };
+}
+async function readPluginCategory(pluginName, directory, category, paths, io, target) {
+    try {
+        const entries = names(await io.list(paths.join(directory, category)));
+        target.push(...entries.map(name => `${pluginName}.${name}`));
+        return false;
+    }
+    catch (error) {
+        return error.code !== "ENOENT";
+    }
+}
+function readCodexMcp(toml) {
+    return toml === null ? null : [...toml.matchAll(/^\s*\[mcp_servers\.(?:"([a-z0-9_.@+-]+)"|([a-z0-9_-]+))\]\s*$/gim)].flatMap(match => {
         const name = safeName(match[1] ?? match[2]);
         if (!name)
             return [];
         const block = toml.slice(match.index + match[0].length).split(/^\s*\[/m)[0];
         return [{ name, transport: /^\s*command\s*=/m.test(block) ? "stdio" : /^\s*url\s*=/m.test(block) ? "http" : "unknown" }];
     }).slice(0, 500);
+}
+function readClaudeMcp(claudeConfig) {
     const claudeServers = [object(claudeConfig?.mcpServers), ...Object.values(object(claudeConfig?.projects)).map(project => object(object(project).mcpServers))];
-    const claudeMcp = claudeConfig === null ? null : claudeServers.flatMap(servers => Object.entries(servers)).flatMap(([key, value]) => {
+    return claudeConfig === null ? null : claudeServers.flatMap(servers => Object.entries(servers)).flatMap(([key, value]) => {
         const name = safeName(key);
         if (!name)
             return [];
         const config = object(value);
-        const transport = config.type === "sse" ? "sse" : config.type === "http" || config.url ? "http" : config.command ? "stdio" : "unknown";
+        const transport = readClaudeMcpTransport(config);
         return [{ name, transport }];
     }).slice(0, 500);
-    const instructions = await Promise.all(["CLAUDE.md", "AGENTS.md"].map(async (name) => {
+}
+function readClaudeMcpTransport(config) {
+    if (config.type === "sse")
+        return "sse";
+    if (config.type === "http" || config.url)
+        return "http";
+    if (config.command)
+        return "stdio";
+    return "unknown";
+}
+async function readInstructionFiles(join, io) {
+    return await Promise.all(["CLAUDE.md", "AGENTS.md"].map(async (name) => {
         const file = join(name === "CLAUDE.md" ? ".claude" : ".codex", name);
         try {
             const content = await io.read(file);
@@ -190,6 +239,9 @@ export async function collectAgentSetup(home, platform = process.platform, io =
             return { name, exists: error.code === "ENOENT" ? false : null, sha256: null, bytes: null };
         }
     }));
+}
+function buildSetupInventory(input) {
+    const { now, platform, claudeSettings, claudeObserved, codexObserved, claudeVersion, codexVersion, claudeSkills, claudeAgents, sharedSkills, codexSkills, systemSkills, claudePlugins, pluginInventoryUnknown, pluginSkills, pluginAgents, claudeMcp, codexMcp, toml, rootToml, scalar, codexHooks, instructions } = input;
     // Model: what the person set, else what their sessions actually ran most.
     const claudeSetModel = safeName(claudeSettings?.model), codexSetModel = scalar("model");
     const claudeModel = claudeSetModel ?? claudeObserved.model;
@@ -198,25 +250,24 @@ export async function collectAgentSetup(home, platform = process.platform, io =
     const claudeDefaultFor = claudeSetModel && claudeFamily(claudeSetModel) !== claudeFamily(claudeObserved.model) ? claudeSetModel : claudeObserved.model ?? claudeSetModel;
     const claudeSetEffort = safeName(claudeSettings?.effortLevel), codexSetEffort = scalar("model_reasoning_effort");
     const claudeDefault = claudeSetEffort ? null : claudeDefaultEffort(claudeDefaultFor);
-    const result = AgentSetupSchema.parse({
+    return AgentSetupSchema.parse({
         checked_at: now.toISOString(), os: platform === "darwin" || platform === "win32" ? platform : "other", cli_version: LOCAL_COLLECTOR_VERSION,
-        claude: { version: claudeVersion.value, version_source: claudeVersion.source,
+        claude: {
+            version: claudeVersion.value, version_source: claudeVersion.source,
             model: claudeModel, model_basis: claudeSetModel ? "set" : claudeModel ? "used" : "none",
             effort: claudeSetEffort ?? claudeDefault, effort_basis: claudeSetEffort ? "set" : "default",
             skills: claudeSkills === null || pluginInventoryUnknown ? null : names([...claudeSkills, ...pluginSkills]), agents: claudeAgents === null || pluginInventoryUnknown ? null : names([...claudeAgents, ...pluginAgents]),
             plugins: claudePlugins === null ? null : names(Object.keys(object(claudePlugins.plugins))),
-            hooks: claudeSettings === null ? null : names(Object.keys(object(claudeSettings.hooks))), mcp: claudeMcp },
-        codex: { version: codexVersion.value, version_source: codexVersion.source,
+            hooks: claudeSettings === null ? null : names(Object.keys(object(claudeSettings.hooks))), mcp: claudeMcp
+        },
+        codex: {
+            version: codexVersion.value, version_source: codexVersion.source,
             model: codexSetModel ?? codexObserved.model, model_basis: codexSetModel ? "set" : codexObserved.model ? "used" : "none",
             effort: codexSetEffort ?? codexObserved.effort, effort_basis: codexSetEffort ? "set" : codexObserved.effort ? "observed" : "default",
             skills: codexSkills === null || sharedSkills === null || systemSkills === null ? null : names([...(codexSkills ?? []), ...(sharedSkills ?? []), ...(systemSkills ?? [])]),
             agents: toml === null ? null : names([...toml.matchAll(/^\s*\[agents\.([a-z0-9_-]+)\]\s*$/gim)].map(match => match[1])),
             plugins: toml === null ? null : names([...toml.matchAll(/^\s*\[plugins\."([a-z0-9_@.+-]+)"\]\s*$/gim)].map(match => match[1])),
-            hooks: codexHooks === null && !/^notify\s*=/m.test(rootToml) ? null : names([...(codexHooks === null ? [] : Object.keys(object(codexHooks.hooks))), ...(/^notify\s*=/m.test(rootToml) ? ["notify"] : [])]), mcp: codexMcp }, instructions,
+            hooks: codexHooks === null && !/^notify\s*=/m.test(rootToml) ? null : names([...(codexHooks === null ? [] : Object.keys(object(codexHooks.hooks))), ...(/^notify\s*=/m.test(rootToml) ? ["notify"] : [])]), mcp: codexMcp
+        }, instructions,
     });
-    const evidence = (tool) => ({ version_source: result[tool].version_source, model_basis: result[tool].model_basis, effort_basis: result[tool].effort_basis });
-    console.error("[setup] versions read", JSON.stringify({ reason: "version_resolved", claude: evidence("claude"), codex: evidence("codex"), transcript_files: { claude: claudeObserved.files, codex: codexObserved.files } }));
-    const unknownFields = [result.claude, result.codex].reduce((count, tool) => count + ["skills", "plugins", "agents", "hooks", "mcp"].filter(key => tool[key] === null).length, 0);
-    console.error("[setup] inventory read", JSON.stringify({ reason: unknownFields ? "inventory_partial" : "inventory_observed", unknown_fields: unknownFields, os: result.os, mcp_count: (result.claude.mcp?.length ?? 0) + (result.codex.mcp?.length ?? 0) }));
-    return result;
 }

package/dist/commands/autostart-heal.js

@@ -78,6 +78,9 @@ async function healDetached(command, io, deps) {
         // BLI-12828: absent is created now; only a deliberate uninstall stops it.
         return { status: "skipped", reason: "autostart_uninstalled_by_operator" };
     }
+    return writeAndVerifyRegistration(command, exec, platform, roots, before.status);
+}
+async function writeAndVerifyRegistration(command, exec, platform, roots, beforeStatus) {
     let written;
     try {
         written = await writeDarwinAutostartPlist({
@@ -107,6 +110,9 @@ async function healDetached(command, io, deps) {
             detail: redactedHealthDetail(reregistered.detail ?? "").slice(0, DETAIL_MAX_CHARS),
         };
     }
+    return verifyRegistration(command, exec, platform, roots, beforeStatus, written.node_path_reason);
+}
+async function verifyRegistration(command, exec, platform, roots, beforeStatus, nodePathReason) {
     // Verify against what launchd returns, not against what we sent it
     // (BLI-2541). A bootstrap that exits 0 and a registration that reads back
     // healthy are two different claims.
@@ -127,8 +133,8 @@ async function healDetached(command, io, deps) {
     }
     return {
         status: "ok",
-        reason: before.status === "absent" ? "autostart_created" : "autostart_healed",
-        detail: `node_path_reason=${written.node_path_reason}`,
+        reason: beforeStatus === "absent" ? "autostart_created" : "autostart_healed",
+        detail: `node_path_reason=${nodePathReason}`,
     };
 }
 async function waitForParentExit(parentPid, deps) {

package/dist/commands/autostart-reading.js

@@ -117,6 +117,9 @@ async function stateFor(result, roots, options) {
             ...detail,
         };
     }
+    return readRegisteredRuntime(roots, options);
+}
+async function readRegisteredRuntime(roots, options) {
     // BLI-3553: "loaded" only means the scheduler accepted the registration. It
     // says nothing about whether the binary that registration names still exists
     // — and `brew upgrade node` deletes exactly that. Ask the filesystem about

package/dist/commands/backfill-evidence-outcomes.js

@@ -50,17 +50,20 @@ function summarizeEvidenceOutcomesBySession(sync) {
         else if (outcome.raw_evidence_pointer_id &&
             (outcome.upload_state === "uploaded" ||
                 outcome.upload_state === "reused_existing")) {
-            if (outcome.kind === "codex_jsonl" || outcome.kind === "claude_jsonl") {
-                summary.durableMainCount += 1;
-            }
-            else if (outcome.kind === "claude_jsonl_sidecar") {
-                summary.durableSidecarCount += 1;
-            }
+            countDurableEvidence(summary, outcome);
         }
         outcomesBySession.set(key, summary);
     }
     return outcomesBySession;
 }
+function countDurableEvidence(summary, outcome) {
+    if (outcome.kind === "codex_jsonl" || outcome.kind === "claude_jsonl") {
+        summary.durableMainCount += 1;
+    }
+    else if (outcome.kind === "claude_jsonl_sidecar") {
+        summary.durableSidecarCount += 1;
+    }
+}
 /** Sidecars this session owes a pointer for; one already skipped at scan time is not owed. */
 function expectedSidecarCount(candidate) {
     if (candidate.source !== "claude_code")

package/dist/commands/backfill-issues.js

@@ -71,6 +71,9 @@ function addCandidateScanIssues(issues, candidates, omittedCandidateCount) {
     countScanIssue(issues, "candidate_worktree_unavailable", candidates.filter((candidate) => isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) && candidate.worktree === null).length, "candidate");
     countScanIssue(issues, "claude_main_file_too_large", candidates.filter((candidate) => candidate.source === "claude_code" &&
         candidate.claude?.main_file_oversized).length, "candidate");
+    addClaudeSidecarIssues(issues, candidates);
+}
+function addClaudeSidecarIssues(issues, candidates) {
     countScanIssue(issues, "claude_sidecar_limit_applied", candidates.reduce((total, candidate) => total + (candidate.claude?.sidecars_capped ?? 0), 0), "candidate");
     countScanIssue(issues, "claude_sidecar_file_unreadable", candidates.reduce((total, candidate) => total +
         (candidate.claude?.sidecar_files.filter((sidecar) => sidecar.skipped_reason === "file_read_failed" ||

package/dist/commands/backfill-scan.js

@@ -44,28 +44,7 @@ export async function scanBackfillRun(command, io, now) {
         };
     }
     const { collectionRoots, sources, worktreeDiscovery } = scope;
-    const storedCursor = command.dryRun
-        ? emptyBackfillCursorState()
-        : await readBackfillCursor(paths);
-    const scopedCursor = prepareBackfillCursorForScope(storedCursor, collectionRoots, sources);
-    const cursor = scopedCursor.cursor;
-    const pointerlessTerminalSessions = await loadPointerlessTerminalSessions(paths, sources);
-    // 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.
-    // 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 { scopedCursor, cursor, pointerlessTerminalSessions, stubReoffer, stubCursorHashes } = await reopenUndeliveredHistory(command, io, paths, scope);
     const scan = await scanBackfillSessions({
         command,
         homeDir: command.homeDir ?? os.homedir(),
@@ -99,6 +78,32 @@ export async function scanBackfillRun(command, io, now) {
         deterministicSkipCandidateKeys: deterministicSkipCandidateKeys(scan.candidates),
     };
 }
+async function reopenUndeliveredHistory(command, io, paths, scope) {
+    const { collectionRoots, sources } = scope;
+    const storedCursor = command.dryRun
+        ? emptyBackfillCursorState()
+        : await readBackfillCursor(paths);
+    const scopedCursor = prepareBackfillCursorForScope(storedCursor, collectionRoots, sources);
+    const cursor = scopedCursor.cursor;
+    const pointerlessTerminalSessions = await loadPointerlessTerminalSessions(paths, sources);
+    // 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.
+    // 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);
+    return { scopedCursor, cursor, pointerlessTerminalSessions, stubReoffer, stubCursorHashes };
+}
 /**
  * Finishes the scan's ledger before anything acts on it: adds what repo
  * discovery could not enumerate, reads every candidate file once to find the

package/dist/commands/backfill-upload.js

@@ -21,15 +21,7 @@ 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, 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 || command.stubPass
-        ? plannedBatches.flatMap((batch) => batch.candidates.map((candidate) => ({
-            worktree: batch.worktree, candidates: [candidate],
-        })))
-        : plannedBatches;
+    const batches = planUploadBatches(command, uploadable);
     const rawEvidenceBudget = {
         remainingBytes: RAW_EVIDENCE_DEFAULT_BYTE_BUDGET,
         remainingObjects: RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET,
@@ -38,29 +30,8 @@ export async function uploadBackfillBatches(command, io, lock, ctx) {
     let consecutiveFailures = 0;
     let blockedAt;
     let failureReason = blockingScanIssues(ctx.scan.issues)[0]?.reason;
-    const stoppedAt = (what, index) => ({
-        what,
-        batch_index: index + 1,
-        batch_total: batches.length,
-        done: tally.done,
-        total: uploadable.length,
-    });
-    const reportProgress = () => {
-        if (!command.onProgress)
-            return;
-        const unresolved = new Set([
-            ...uploadable.map(candidateCursorKey).filter((key) => !tally.durableCandidateKeys.has(key)),
-            ...ctx.scan.retryable_candidate_keys,
-        ]);
-        command.onProgress({
-            processed: tally.done,
-            uploaded: tally.backfilledSessions,
-            remaining: unresolved.size + ctx.scan.omitted_candidate_count + ctx.scan.issues
-                .filter((issue) => issue.scope === "global")
-                .reduce((total, issue) => total + issue.count, 0),
-            elapsedMs: Date.now() - ctx.now.getTime(),
-        });
-    };
+    const stoppedAt = (what, index) => describeBatchStop(what, index, batches.length, tally.done, uploadable.length);
+    const reportProgress = () => reportBackfillProgress(command, ctx, uploadable, tally);
     reportProgress();
     // BLI-11091: outside-root sessions upload under a synthetic workspace that
     // only exists once something needs it (a dry run never gets here).
@@ -69,15 +40,10 @@ export async function uploadBackfillBatches(command, io, lock, ctx) {
         await ensureOutsideRootsWorkspace(outsideWorkspace);
     for (const [index, batch] of batches.entries()) {
         await lock.handle.heartbeat();
-        if (command.deadlineMs !== undefined && Date.now() >= command.deadlineMs) {
-            blockedAt = stoppedAt("backfill time budget reached", index);
-            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 }));
+        const before = await stopBeforeBatch(command, index, batches.length);
+        if (before) {
+            blockedAt = stoppedAt(before.what, index);
+            failureReason = before.reason;
             break;
         }
         const outcome = await uploadOneBackfillBatch(command, io, ctx, batch, rawEvidenceBudget);
@@ -88,30 +54,73 @@ export async function uploadBackfillBatches(command, io, lock, ctx) {
             writeLine(io.stdout, `Uploaded ${tally.done}/${uploadable.length} (batch ${index + 1}/${batches.length})`);
         }
         await yieldToEventLoop();
-        if (outcome.deferred) {
-            blockedAt = stoppedAt("raw evidence budget exhausted", index);
-            failureReason = "deferred_budget_exhausted";
-            break;
-        }
-        // BLI-12832: the disk gate refused a copy. Every later batch would be
-        // refused the same way, so stop here; the cursor only advanced through
-        // sessions that earned a durable pointer, and the next run starts from
-        // the same place once room returns.
-        const stagingDeferred = stagingDeferredFiles(rawEvidenceBudget.staging);
-        if (stagingDeferred > 0) {
-            blockedAt = stoppedAt("staging paused: not enough room to copy more evidence", index);
-            failureReason = "deferred_budget_exhausted";
-            console.error("[backfill] stopped, the staging gate is holding new copies", JSON.stringify({ reason: "staging_deferred", files_deferred: stagingDeferred, batch_index: index + 1 }));
-            break;
-        }
-        if (consecutiveFailures >= BACKFILL_MAX_CONSECUTIVE_FAILURES) {
-            blockedAt = stoppedAt("consecutive upload failures", index);
-            failureReason = failedBatchReason(outcome.sync, outcome.missingDurableMain);
+        const after = stopAfterBatch(outcome, rawEvidenceBudget, consecutiveFailures, index);
+        if (after) {
+            blockedAt = stoppedAt(after.what, index);
+            failureReason = after.reason;
             break;
         }
     }
     return { ...tally, uploadable, batches, blockedAt, failureReason };
 }
+function planUploadBatches(command, uploadable) {
+    // 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);
+    return command.deadlineMs !== undefined || command.onProgress || command.stubPass
+        ? plannedBatches.flatMap((batch) => batch.candidates.map((candidate) => ({
+            worktree: batch.worktree, candidates: [candidate],
+        })))
+        : plannedBatches;
+}
+function describeBatchStop(what, index, batchTotal, done, total) {
+    return { what, batch_index: index + 1, batch_total: batchTotal, done, total };
+}
+function reportBackfillProgress(command, ctx, uploadable, tally) {
+    if (!command.onProgress)
+        return;
+    const unresolved = new Set([
+        ...uploadable.map(candidateCursorKey).filter((key) => !tally.durableCandidateKeys.has(key)),
+        ...ctx.scan.retryable_candidate_keys,
+    ]);
+    command.onProgress({
+        processed: tally.done,
+        uploaded: tally.backfilledSessions,
+        remaining: unresolved.size + ctx.scan.omitted_candidate_count + ctx.scan.issues
+            .filter((issue) => issue.scope === "global")
+            .reduce((total, issue) => total + issue.count, 0),
+        elapsedMs: Date.now() - ctx.now.getTime(),
+    });
+}
+async function stopBeforeBatch(command, index, batchCount) {
+    if (command.deadlineMs !== undefined && Date.now() >= command.deadlineMs) {
+        return { what: "backfill time budget reached", reason: "deferred_budget_exhausted" };
+    }
+    if (command.stubPass?.shouldYield && (await command.stubPass.shouldYield())) {
+        console.error("[collector stubs] stub pass yielded the collection lock to a waiting backfill", JSON.stringify({ reason: "backfill_waiting", sessions_done: index, sessions_left: batchCount - index }));
+        return { what: "yielded to a waiting backfill", reason: "yielded_to_backfill" };
+    }
+    return null;
+}
+function stopAfterBatch(outcome, rawEvidenceBudget, consecutiveFailures, index) {
+    if (outcome.deferred) {
+        return { what: "raw evidence budget exhausted", reason: "deferred_budget_exhausted" };
+    }
+    // BLI-12832: the disk gate refused a copy. Every later batch would be
+    // refused the same way, so stop here; the cursor only advanced through
+    // sessions that earned a durable pointer, and the next run starts from
+    // the same place once room returns.
+    const stagingDeferred = stagingDeferredFiles(rawEvidenceBudget.staging);
+    if (stagingDeferred > 0) {
+        console.error("[backfill] stopped, the staging gate is holding new copies", JSON.stringify({ reason: "staging_deferred", files_deferred: stagingDeferred, batch_index: index + 1 }));
+        return { what: "staging paused: not enough room to copy more evidence", reason: "deferred_budget_exhausted" };
+    }
+    if (consecutiveFailures >= BACKFILL_MAX_CONSECUTIVE_FAILURES) {
+        return { what: "consecutive upload failures", reason: failedBatchReason(outcome.sync, outcome.missingDurableMain) };
+    }
+    return null;
+}
 /** Uploads one batch and judges it; every judgement here is a named predicate. */
 async function uploadOneBackfillBatch(command, io, ctx, batch, rawEvidenceBudget) {
     const sync = await syncBackfillBatch({

package/dist/commands/backfill.js

@@ -121,27 +121,12 @@ export async function runBackfill(command, io) {
     // 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. 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 } };
-    }
-    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 = await waitForCollectionLock(command, paths, lock);
+    if (!collectionLock) {
+        return lockHeldResult(command, scanned, {
+            failureReason: "sync_lock_held",
+            what: "sync collection lock held",
+        });
     }
     try {
         // Backfill and scheduled/manual sync share upload spool and raw-evidence
@@ -161,4 +146,24 @@ export async function runBackfill(command, io) {
         await collectionLock.handle.release();
         await lock.handle.release();
     }
+}
+async function waitForCollectionLock(command, paths, lock) {
+    if (command.stubPass) {
+        return { handle: { release: async () => undefined } };
+    }
+    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 null;
+        }
+        return waited.lock;
+    }
 }

package/dist/commands/brief-done.js

@@ -63,6 +63,10 @@ export async function runBriefDone(command, io) {
         writeFailure(command, io, body.error ?? "not_saved", body.reply ?? body.error ?? "It did not save.");
         return 1;
     }
+    writeTickSuccess(command, io, body, done, found);
+    return 0;
+}
+function writeTickSuccess(command, io, body, done, found) {
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(body));
     }
@@ -76,7 +80,6 @@ export async function runBriefDone(command, io) {
         item_key: found.itemKey,
         has_ticket: found.ticketIdentifier != null,
     })}`);
-    return 0;
 }
 /** The page, with its claim ids, so an item can be checked before anything is sent. */
 async function readThePage(dashboardUrl, deviceToken, io, log) {