@bli-cockpit/cli 0.2.99 → 0.2.101

package/dist/agent-rules.js

@@ -141,13 +141,14 @@ export function cockpitAgentRulesBlock(options = {}) {
         ? `- Only applies when the current working directory is inside the Tower-onboarded workspace/repo: \`${scopePaths[0]}\`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.`
         : scopePaths.length > 1
             ? `- Only applies when the current working directory is inside one of these Tower-onboarded workspace roots: ${scopePaths.map((scopePath) => `\`${scopePath}\``).join(", ")}. Outside those folders, do not run Tower ticket binding or sync commands for private chats or unrelated repos.`
-            : "- Only applies when the current working directory is inside the workspace/repo that ran `cockpit onboard` or `cockpit agent-rules install`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.";
+            : "- Only applies when the current working directory is inside the workspace/repo that ran `cockpit doctor` or `cockpit agent-rules install`. Outside that folder, do not run Tower ticket binding or sync commands for private chats or unrelated repos.";
     return [
         MANAGED_BLOCK_START,
         "## Tower Ticket Binding",
         "",
         scopeLine,
         "- Ticketed work (implement / debug / review / PR / ship): run `cockpit start --ticket <ticket-id> --workspace \"$PWD\"` before the first code edit (the flag is `--ticket`). No ticket ID visible → search Linear first; none exists and the work is ticket-worthy → create a narrow Linear ticket, then bind.",
+        "- If setup or collection needs repair, run `cockpit doctor`. It repairs this machine and prints any remaining action.",
         "- Truly no ticket → say the session stays in general ambient capture; never invent one.",
         "- After the first meaningful checkpoint, run `cockpit sync --workspace \"$PWD\" --json`.",
         "",

package/dist/backfill-lock.js

@@ -54,7 +54,7 @@ export async function inspectBackfillLock(paths, now = new Date()) {
         now.getTime() - record.heartbeat_ms > BACKFILL_LOCK_STALE_TAKEOVER_MS) {
         return { held: false, held_since: null };
     }
-    return { held: true, held_since: record.heartbeat_at };
+    return { held: true, held_since: record.heartbeat_at, pid: record.pid };
 }
 export function backfillLockPath(paths) {
     return path.join(paths.cursors_dir, BACKFILL_LOCK_FILENAME);

package/dist/commands/backfill-checkpoint.js

@@ -77,8 +77,10 @@ export function advanceBackfillCursorThroughResolvedPrefix(options) {
             .sort(compareBackfillCandidates);
         for (const candidate of remaining) {
             const key = candidateCursorKey(candidate);
-            if (options.retryableCandidateKeys.has(key))
+            if (options.retryableCandidateKeys.has(key) &&
+                !options.deterministicSkipCandidateKeys?.has(key)) {
                 break;
+            }
             const resolved = isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null)
                 ? options.durableCandidateKeys.has(key)
                 : true;

package/dist/commands/backfill-issues.js

@@ -2,6 +2,10 @@
  * Everything the scan could not account for cleanly, in one ledger — the
  * module that exists so a session is never silently dropped.
  *
+ * What any of those records MEAN for the run — retryable versus a deliberate
+ * cap, and therefore what blocks completion — lives in the sibling
+ * `backfill-skip-policy.ts`, and every name it owns is re-exported from here.
+ *
  * Scope is the load-bearing distinction. A global issue means discovery may
  * have hidden a session at any mtime, so no source watermark is safe to
  * advance; a candidate issue only stops the contiguous cursor prefix at the
@@ -79,39 +83,6 @@ function scanIssuePriority(scope) {
         return 1;
     return 2;
 }
-export function retryableCandidateKeys(candidates) {
-    return new Set(candidates
-        .filter((candidate) => candidate.reason === "file_read_failed" ||
-        candidate.reason === "repo_not_on_disk" ||
-        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
-            !candidate.worktree) ||
-        Boolean(candidate.claude?.main_file_oversized) ||
-        (candidate.claude?.sidecars_capped ?? 0) > 0 ||
-        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
-            sidecar.skipped_reason === "file_too_large")))
-        .map(candidateCursorKey));
-}
-/**
- * A main session file whose only story is "too large to upload under the
- * current cap" (BLI-2727). This mirrors exactly the two branches in
- * `countReadOnlyGuards` that emit the `file_too_large` reason, so a candidate
- * is in this set if and only if it contributed to that scan issue's count —
- * one predicate, no drift between "why the issue fired" and "which candidate
- * caused it". Deterministic and non-retryable: rerunning backfill cannot
- * resolve it (only a larger cap or a smaller file can), so unlike a transient
- * read failure it must never poison completion or a batch's success.
- */
-export function oversizedBackfillCandidateKeys(candidates) {
-    const keys = new Set();
-    for (const candidate of candidates) {
-        if ((candidate.source === "claude_code" &&
-            candidate.claude?.main_file_oversized) ||
-            candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
-            keys.add(candidateCursorKey(candidate));
-        }
-    }
-    return keys;
-}
 // --- Scan issue ledger --------------------------------------------------
 //
 // `scan.issues` is the running ledger of everything the scan could not
@@ -161,27 +132,6 @@ export function addReadOnlyGuardIssues(issues, guardCounts) {
         });
     }
 }
-// BLI-2727: a deterministic, labeled oversized skip must never poison
-// completion — it is a permanent, non-retryable fact about the file, not an
-// in-flight problem a rerun can fix. `scan.issues`/`retryable_candidate_keys`
-// still carry it (so it's never silently dropped from reporting); every
-// completion-gating computation excludes it explicitly instead, by filtering
-// through `blockingScanIssues` below.
-//
-// Two scan issues describe the exact same oversized-main candidates:
-// `backfillScanIssues` pushes the Claude-specific `claude_main_file_too_large`
-// (from `claude?.main_file_oversized`) and `countReadOnlyGuards` (via
-// `addReadOnlyGuardIssues` above) separately pushes the source-agnostic
-// `file_too_large` (same predicate as `oversizedBackfillCandidateKeys`, so
-// this list can never drift from it). Both must be excluded from
-// completion-gating together.
-const OVERSIZED_SCAN_ISSUE_REASONS = new Set([
-    "file_too_large",
-    "claude_main_file_too_large",
-]);
-export function blockingScanIssues(issues) {
-    return issues.filter((issue) => !OVERSIZED_SCAN_ISSUE_REASONS.has(issue.reason));
-}
 async function countUnreadableClaudeSidecarDirs(candidates) {
     let unreadable = 0;
     for (const candidate of candidates) {
@@ -262,4 +212,7 @@ export async function countReadOnlyGuards(candidates) {
 }
 export function increment(counts, key) {
     counts.set(key, (counts.get(key) ?? 0) + 1);
-}
+}
+// Re-exported so every caller keeps importing the skip policy from
+// `./backfill-issues.js` regardless of which sibling decides it.
+export { blockingScanIssues, cappedSidecarCount, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, } from "./backfill-skip-policy.js";

package/dist/commands/backfill-report.js

@@ -4,7 +4,7 @@ import { readLocalWorkContextForRepo, startLocalWorkContext, } from "../local-st
 import { postCodexSessionReport, } from "../upload.js";
 import { candidateCursorKey } from "./backfill-candidates.js";
 import { advanceBackfillCursorThroughResolvedPrefix, recordBackfillDurableSessionPointers, } from "./backfill-checkpoint.js";
-import { blockingScanIssues } from "./backfill-issues.js";
+import { blockingScanIssues, cappedSidecarCount } from "./backfill-issues.js";
 import { backfillResultBaseArgs, baseBackfillResult, emptyReport, } from "./backfill-result.js";
 import { buildBackfillSessionReport } from "./backfill-session-report.js";
 /**
@@ -111,7 +111,7 @@ function sessionReportFailureReason(posted) {
  * past a session the server never recorded can never be walked back.
  */
 async function checkpointResolvedBackfillProgress(ctx, upload) {
-    const { paths, scan, cursor, now } = ctx;
+    const { paths, scan, cursor, now, deterministicSkipCandidateKeys } = ctx;
     if (upload.durableCandidateKeys.size > 0) {
         await recordBackfillDurableSessionPointers({
             paths,
@@ -125,6 +125,10 @@ async function checkpointResolvedBackfillProgress(ctx, upload) {
         candidates: scan.candidates,
         durableCandidateKeys: upload.durableCandidateKeys,
         retryableCandidateKeys: scan.retryable_candidate_keys,
+        // BLI-4303: a permanent cap must not stop the prefix either, or the cursor
+        // stalls at the first sidecar-capped session for good and every later run
+        // re-walks the same history.
+        deterministicSkipCandidateKeys,
         discoveryComplete: !scan.issues.some((issue) => issue.scope === "global"),
         now,
     });
@@ -141,13 +145,13 @@ async function checkpointResolvedBackfillProgress(ctx, upload) {
  * that no rerun can resolve and completion must not wait on forever.
  */
 function summarizeBackfillCompletion(options) {
-    const { scan, oversizedCandidateKeys } = options.ctx;
+    const { scan, deterministicSkipCandidateKeys } = options.ctx;
     const { upload, posted } = options;
     const unresolvedUploadableKeys = new Set(upload.uploadable
         .filter((candidate) => !upload.durableCandidateKeys.has(candidateCursorKey(candidate)))
         .map(candidateCursorKey));
-    const unresolvedUploadableBlocking = [...unresolvedUploadableKeys].filter((key) => !oversizedCandidateKeys.has(key)).length;
-    const unresolvedRetryableBlocking = [...scan.retryable_candidate_keys].filter((key) => !oversizedCandidateKeys.has(key)).length;
+    const unresolvedUploadableBlocking = [...unresolvedUploadableKeys].filter((key) => !deterministicSkipCandidateKeys.has(key)).length;
+    const unresolvedRetryableBlocking = [...scan.retryable_candidate_keys].filter((key) => !deterministicSkipCandidateKeys.has(key)).length;
     const remaining = countRemainingHistory({
         scan,
         unresolvedUploadableKeys,
@@ -164,7 +168,7 @@ function summarizeBackfillCompletion(options) {
     let failureReason = options.failureReason;
     if (!failureReason && completionBlocked) {
         const retryableCandidateReason = scan.candidates.find((candidate) => scan.retryable_candidate_keys.has(candidateCursorKey(candidate)) &&
-            !oversizedCandidateKeys.has(candidateCursorKey(candidate)))?.reason;
+            !deterministicSkipCandidateKeys.has(candidateCursorKey(candidate)))?.reason;
         failureReason =
             blockingIssues[0]?.reason ??
                 (unresolvedUploadableBlocking > 0
@@ -211,6 +215,7 @@ function countRemainingHistory(options) {
  */
 async function writeAllHistoryCompletionMarker(ctx) {
     const { paths, cursor, sources, scopedCursor, scan, oversizedCandidateKeys, now } = ctx;
+    const cappedSidecars = cappedSidecarCount(scan.candidates);
     recordBackfillScanCoverage(cursor, sources, now, now);
     await writeBackfillCursor(paths, cursor);
     const oversizedCandidates = scan.candidates.filter((candidate) => oversizedCandidateKeys.has(candidateCursorKey(candidate)));
@@ -231,6 +236,17 @@ async function writeAllHistoryCompletionMarker(ctx) {
                 },
             }
             : {}),
+        // BLI-4303: additive on the same schema version, so an older marker simply
+        // omits it. A cap that is now excused from completion has to be visible
+        // wherever completion is claimed.
+        ...(cappedSidecars > 0
+            ? {
+                sidecar_cap_skips: {
+                    reason: "claude_sidecar_limit_applied",
+                    count: cappedSidecars,
+                },
+            }
+            : {}),
     });
 }
 /** The `--json` payload: every stage's numbers merged onto the scan's baseline. */

package/dist/commands/backfill-scan.js

@@ -16,7 +16,7 @@ import { emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCu
 import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
 import { getCollectorRuntimePaths } from "../local-state.js";
 import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
-import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
+import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, deterministicSkipCandidateKeys, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
 import { reasonCountsFor } from "./backfill-reasons.js";
 import { blockedBackfillResult } from "./backfill-result.js";
 import { resolveBackfillScope } from "./backfill-scope.js";
@@ -73,6 +73,7 @@ export async function scanBackfillRun(command, io, now) {
         scan,
         reasonCounts,
         oversizedCandidateKeys: oversizedBackfillCandidateKeys(scan.candidates),
+        deterministicSkipCandidateKeys: deterministicSkipCandidateKeys(scan.candidates),
     };
 }
 /**

package/dist/commands/backfill-skip-policy.js

@@ -0,0 +1,134 @@
+/**
+ * Which candidates a rerun could actually resolve, and which are a cap.
+ *
+ * The sibling ledger (`backfill-issues.ts`) records everything the scan could
+ * not account for; this module answers the only question the rest of the run
+ * asks about those records: does the thing block completion, or is it a
+ * permanent fact about the file that no rerun can change. The distinction is
+ * load-bearing in three places at once — completion, the cursor's contiguous
+ * prefix, and whether a batch counts as failed — so it has one owner.
+ *
+ *   retryableCandidateKeys           a rerun still owes this session something
+ *   oversizedBackfillCandidateKeys   the file is past the upload cap (BLI-2727)
+ *   deterministicSkipCandidateKeys   oversized, or sidecar-capped and nothing
+ *                                    else wrong with it (BLI-4303)
+ *   blockingScanIssues               the ledger minus the deliberate caps
+ *   cappedSidecarCount               what the sidecar cap left behind
+ *
+ * Every name here is re-exported from `./backfill-issues.js`, the address its
+ * callers already know.
+ */
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { candidateCursorKey } from "./backfill-candidates.js";
+export function retryableCandidateKeys(candidates) {
+    return new Set(candidates
+        .filter((candidate) => candidate.reason === "file_read_failed" ||
+        candidate.reason === "repo_not_on_disk" ||
+        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+            !candidate.worktree) ||
+        Boolean(candidate.claude?.main_file_oversized) ||
+        (candidate.claude?.sidecars_capped ?? 0) > 0 ||
+        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed" ||
+            sidecar.skipped_reason === "file_too_large")))
+        .map(candidateCursorKey));
+}
+/**
+ * A main session file whose only story is "too large to upload under the
+ * current cap" (BLI-2727). This mirrors exactly the two branches in
+ * `countReadOnlyGuards` that emit the `file_too_large` reason, so a candidate
+ * is in this set if and only if it contributed to that scan issue's count —
+ * one predicate, no drift between "why the issue fired" and "which candidate
+ * caused it". Deterministic and non-retryable: rerunning backfill cannot
+ * resolve it (only a larger cap or a smaller file can), so unlike a transient
+ * read failure it must never poison completion or a batch's success.
+ */
+export function oversizedBackfillCandidateKeys(candidates) {
+    const keys = new Set();
+    for (const candidate of candidates) {
+        if ((candidate.source === "claude_code" &&
+            candidate.claude?.main_file_oversized) ||
+            candidate.byte_size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+            keys.add(candidateCursorKey(candidate));
+        }
+    }
+    return keys;
+}
+// BLI-2727: a deterministic, labeled oversized skip must never poison
+// completion — it is a permanent, non-retryable fact about the file, not an
+// in-flight problem a rerun can fix. `scan.issues`/`retryable_candidate_keys`
+// still carry it (so it's never silently dropped from reporting); every
+// completion-gating computation excludes it explicitly instead, by filtering
+// through `blockingScanIssues` below.
+//
+// Two scan issues describe the exact same oversized-main candidates:
+// `backfillScanIssues` pushes the Claude-specific `claude_main_file_too_large`
+// (from `claude?.main_file_oversized`) and `countReadOnlyGuards` (via
+// `addReadOnlyGuardIssues` above) separately pushes the source-agnostic
+// `file_too_large` (same predicate as `oversizedBackfillCandidateKeys`, so
+// this list can never drift from it). Both must be excluded from
+// completion-gating together.
+//
+// BLI-4303 adds the third member of the same class, and it is the one that
+// kept the reference Mac's `backfill-complete` row red forever:
+// `claude_sidecar_limit_applied` counts helper transcripts past
+// `CLAUDE_SESSION_MAX_SIDECAR_FILES`, a fixed constant. It is exactly as
+// permanent as an oversized file — no rerun can produce the 41st sidecar of a
+// session whose cap is 40 — yet it gated completion, so the all-history
+// marker could never be written on a machine that uses subagents heavily
+// (513 capped sidecars there). A cap is a collection boundary, not a failure;
+// raising it is a separate decision, and until then it is a labeled fact that
+// travels in the marker and in what doctor says.
+const DETERMINISTIC_SKIP_SCAN_ISSUE_REASONS = new Set([
+    "file_too_large",
+    "claude_main_file_too_large",
+    "claude_sidecar_limit_applied",
+]);
+export function blockingScanIssues(issues) {
+    return issues.filter((issue) => !DETERMINISTIC_SKIP_SCAN_ISSUE_REASONS.has(issue.reason));
+}
+/**
+ * How many helper transcripts this run left behind purely because of the
+ * per-session sidecar cap (BLI-4303). Metadata only — a count, no paths — and
+ * it is what the completion marker and doctor's green row say out loud so an
+ * excused skip is never a silent one.
+ */
+export function cappedSidecarCount(candidates) {
+    return candidates.reduce((total, candidate) => total + (candidate.claude?.sidecars_capped ?? 0), 0);
+}
+/**
+ * Candidates whose ONLY unfinished business is a cap this collector applies on
+ * purpose (BLI-4303): the oversized-main set above, plus a session that hit the
+ * per-session sidecar cap and has nothing else wrong with it.
+ *
+ * The second half carries a condition the first does not, deliberately: a
+ * sidecar-capped session still uploads its main transcript, so it can and must
+ * earn a durable pointer. If anything ELSE about it is retryable — an
+ * unreadable file, a repo that is not on disk, an uploadable state with no
+ * worktree, a sidecar that could not be read — it is not excused, because then
+ * a rerun genuinely has work to do on it.
+ */
+export function deterministicSkipCandidateKeys(candidates) {
+    const keys = oversizedBackfillCandidateKeys(candidates);
+    for (const candidate of candidates) {
+        if (!isSidecarCapOnlyCandidate(candidate))
+            continue;
+        keys.add(candidateCursorKey(candidate));
+    }
+    return keys;
+}
+function isSidecarCapOnlyCandidate(candidate) {
+    const cappedSidecars = candidate.claude?.sidecars_capped ?? 0;
+    const oversizedSidecars = Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_too_large"));
+    if (cappedSidecars === 0 && !oversizedSidecars)
+        return false;
+    return !hasRetryableProblem(candidate);
+}
+/** The parts of `retryableCandidateKeys` a rerun could actually resolve. */
+function hasRetryableProblem(candidate) {
+    return (candidate.reason === "file_read_failed" ||
+        candidate.reason === "repo_not_on_disk" ||
+        (isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null) &&
+            !candidate.worktree) ||
+        Boolean(candidate.claude?.sidecar_files.some((sidecar) => sidecar.skipped_reason === "file_read_failed")));
+}

package/dist/commands/careers.js

@@ -0,0 +1,16 @@
+import { askAgentDoor, emitAgentDoor, failAgentDoor, openAgentDoor } from './agent-door.js';
+export async function runCareers(command, io) {
+    const door = await openAgentDoor('careers', command, io);
+    const query = new URLSearchParams();
+    if (command.role)
+        query.set('role', command.role);
+    if (command.minScore !== undefined)
+        query.set('min_score', String(command.minScore));
+    if (command.since)
+        query.set('since', command.since);
+    const path = command.action === 'list' ? `/api/careers/applications?${query}` : `/api/careers/applications/${encodeURIComponent(command.id)}${command.action === 'rescreen' ? '/rescreen' : ''}`;
+    const answer = await askAgentDoor(door, { path, method: command.action === 'rescreen' ? 'POST' : 'GET', label: `careers ${command.action}`, timeoutMs: 60_000 });
+    if (!answer.ok)
+        return failAgentDoor(door, '[careers]', answer.reason, answer.detail);
+    return emitAgentDoor(door, answer.body);
+}

package/dist/commands/doctor-access.js

@@ -1,5 +1,7 @@
+import { sendCollectorHeartbeatBestEffort } from "./heartbeat.js";
+import { isInteractiveDoctorFix } from "./doctor-report.js";
 import { describeError } from "../health-detail.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, readLocalCollectorSessionFile, toSessionReference, } from "../local-state.js";
 import { normalizeCollectionRoots } from "../root-normalization.js";
 import { detectSecondCockpitInstall } from "../second-install.js";
 import { hardStop, needsFix, ok, skipped } from "./doctor-report.js";
@@ -12,6 +14,21 @@ import { hardStop, needsFix, ok, skipped } from "./doctor-report.js";
  * operator decide.
  */
 export async function fixAuthState(context, state) {
+    const renewed = await sendCollectorHeartbeatBestEffort({
+        homeDir: context.command.homeDir,
+        dashboardUrl: context.command.dashboardUrl,
+        roots: await doctorRoots(context),
+        facts: { status: "skipped", reason: "doctor_auth_renewal" },
+        io: context.io,
+    });
+    if (renewed) {
+        context.authVerified = true;
+        const checked = await context.deps.readAuth(context);
+        if (checked.status === "ok")
+            return checked;
+    }
+    if (!isInteractiveDoctorFix(context))
+        return { ...state, nextAction: "cockpit login" };
     const code = await context.deps.runLogin(context).catch((error) => {
         // Exit code 1 with no reason at all is what an operator saw when doctor
         // tried and failed to repair their auth — the same output as a login that
@@ -24,6 +41,7 @@ export async function fixAuthState(context, state) {
     });
     if (code !== 0)
         return state;
+    context.authVerified = true;
     const checked = await context.deps.readAuth(context);
     return checked.status === "ok" ? checked : state;
 }
@@ -42,11 +60,14 @@ export async function fixRootState(context, state) {
     return checked.status === "ok" ? checked : state;
 }
 export async function readAuthState(context) {
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
-    if (session?.session_state === "valid" &&
+    if (session && toSessionReference(session).session_state === "valid" &&
         typeof session.device_token === "string" &&
         session.device_token) {
+        if (!context.command.checkOnly && !context.command.dryRun && !context.authVerified) {
+            return needsFix("authed", "token_validation_required", "checking that the saved device token is accepted");
+        }
         return ok("authed", "device_token_present", "this machine is signed in");
     }
     return hardStop("authed", "pairing_required", [
@@ -58,10 +79,11 @@ export async function readAuthState(context) {
     ].join("\n"));
 }
 export async function readRootState(context) {
-    const paths = getCollectorRuntimePaths();
+    const paths = getCollectorRuntimePaths(context.command.homeDir);
     const config = await readLocalCollectorConfig(paths).catch(() => null);
     const roots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
-    if (roots.length > 0) {
+    const requested = normalizeCollectionRoots(context.command.collectionRoots ?? (context.command.repoRoot ? [context.command.repoRoot] : []));
+    if (roots.length > 0 && requested.every((root) => roots.includes(root))) {
         return {
             ...ok("roots-ok", "saved_roots_present", `saved roots: ${roots.join(", ")}`),
             roots,
@@ -72,7 +94,7 @@ export async function readRootState(context) {
         "What you can do:",
         `  1) Run \`${onboardOneLiner(context.command)}\` to save the workspace roots again.`,
         "  2) If this is the wrong folder, rerun from the BLI workspace or pass `--workspace <path>`.",
-        "  3) There is no `--repair` flag; the onboard-rerun is the repair path.",
+        "  3) Run `cockpit doctor` interactively to choose approved roots.",
     ].join("\n"));
 }
 /**
@@ -107,12 +129,14 @@ export async function checkSingleInstallState(context) {
     ].join("\n"));
 }
 export async function doctorRoots(context) {
+    if (context.command.collectionRoots?.length)
+        return context.command.collectionRoots;
     if (context.command.repoRoot)
         return [context.command.repoRoot];
-    return savedRoots();
+    return savedRoots(context.command.homeDir);
 }
-export async function savedRoots() {
-    const config = await readLocalCollectorConfig(getCollectorRuntimePaths()).catch(() => null);
+export async function savedRoots(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
     return normalizeCollectionRoots(config?.default_repo_paths ?? []);
 }
 function onboardOneLiner(command) {
@@ -120,7 +144,7 @@ function onboardOneLiner(command) {
     const dashboard = command.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
         : ` --dashboard-url ${shellQuote(command.dashboardUrl)}`;
-    return `cockpit onboard --workspace ${shellQuote(workspace)}${dashboard}`;
+    return `cockpit doctor --workspace ${shellQuote(workspace)}${dashboard}`;
 }
 function shellQuote(value) {
     if (value === "$PWD")

package/dist/commands/doctor-lock-wait.js

@@ -0,0 +1,46 @@
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { inspectSyncLock } from "../sync-lock.js";
+const BUSY = new Set(["sync_already_running", "backfill_already_running", "live_sync_paused_during_backfill"]);
+/** Retry the operation itself: its existing exclusive lock acquisition owns the
+ * handoff. Merely observing a free lock never grants permission to collect. */
+export async function withDoctorLockWait(context, run, timing = { now: () => Date.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+    const started = timing.now();
+    const limit = (context.command.lockWaitSeconds ?? 600) * 1000;
+    let nextProgress = 0;
+    let row = await run();
+    while (BUSY.has(row.code)) {
+        const paths = getCollectorRuntimePaths(context.command.homeDir);
+        const sync = await inspectSyncLock(paths);
+        const backfill = await inspectBackfillLock(paths);
+        const owner = backfill.held
+            ? { pid: backfill.pid, heartbeat_at: backfill.held_since }
+            : sync;
+        const elapsed = timing.now() - started;
+        if (elapsed >= limit) {
+            const pid = owner?.pid;
+            let name = "unknown process";
+            if (pid && pid > 0 && context.io.exec) {
+                const result = process.platform === "win32"
+                    ? await context.io.exec("tasklist", ["/FI", `PID eq ${pid}`, "/FO", "CSV", "/NH"])
+                    : await context.io.exec("ps", ["-p", String(pid), "-o", "comm="]);
+                if (result.code === 0 && result.stdout.trim())
+                    name = result.stdout.trim().split("\n")[0] ?? name;
+            }
+            return { ...row, status: "needs_fix", code: "lock_wait_timeout", nextAction: "cockpit doctor --lock-wait 600", message: `Waited ${Math.round(elapsed / 1000)}s for the collection lock; owner pid ${pid ?? "unknown"}, ${name}. Run \`cockpit doctor --lock-wait 600\`.` };
+        }
+        if (elapsed >= nextProgress) {
+            const seconds = Math.floor(elapsed / 1000);
+            console.error(`[doctor] ${row.id} waiting`, JSON.stringify({ reason: row.code, owner_pid: owner?.pid ?? null, heartbeat_at: owner?.heartbeat_at ?? null, elapsed_seconds: seconds }));
+            context.io.stderr.write(`waiting for the background sync to finish, ${Math.floor(seconds / 60)}m${seconds % 60}s\n`);
+            nextProgress = elapsed + 30_000;
+        }
+        await timing.sleep(Math.min(1000, limit - elapsed));
+        // A live heartbeat means there is no point spawning a collector yet.
+        const currentSync = await inspectSyncLock(paths);
+        const currentBackfill = await inspectBackfillLock(paths);
+        if (!currentSync?.held && !currentBackfill.held)
+            row = await run();
+    }
+    return row;
+}