@bli-cockpit/cli 0.2.11 → 0.2.13

package/dist/autostart.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths } from "./local-state.js";
+import { savedDiscoveryLimitArgs } from "./discovery-limits.js";
 /** launchd LaunchAgent label; matches docs/runbooks/cockpit-launchd-sync.md. */
 export const AUTOSTART_LABEL = "com.bli.cockpit.sync";
 export const WINDOWS_AUTOSTART_TASK_NAME = "BLI Cockpit Sync";
@@ -53,6 +54,7 @@ export async function installAutostartAgent(options) {
     await mkdir(path.dirname(plistPath), { recursive: true });
     await mkdir(paths.state_dir, { recursive: true });
     await writeFile(plistPath, renderPlist({
+        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
         workDir,
         workDirs: resolvedWorkDirs,
         dashboardUrl,
@@ -127,6 +129,7 @@ export async function autostartStatus(options) {
     const cliEntryPoint = path.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     const plist = await readFile(plistPath, "utf8").catch(() => "");
     const registrationProblems = darwinAgentRegistrationProblems(plist, {
+        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
         workDirs: resolvedWorkDirs,
         dashboardUrl,
         intervalSeconds,
@@ -165,6 +168,7 @@ async function installWindowsTask(options) {
     const cliEntryPoint = path.win32.resolve(options.cliEntryPoint ?? process.argv[1] ?? "");
     await mkdir(path.dirname(scriptPath), { recursive: true });
     await writeFile(scriptPath, `${UTF8_BOM}${renderWindowsSyncScript({
+        discoveryArgs: await savedDiscoveryLimitArgs(homeDir),
         workDirs: resolvedWorkDirs,
         dashboardUrl,
         nodeExecutable,
@@ -290,6 +294,7 @@ async function windowsTaskStatus(options) {
     }
     else if (options.repoRoots && options.repoRoots.length > 0) {
         const expectedScript = `${UTF8_BOM}${renderWindowsSyncScript({
+            discoveryArgs: await savedDiscoveryLimitArgs(options.homeDir),
             workDirs: normalizeWindowsWorkDirs(options.repoRoots),
             dashboardUrl: options.dashboardUrl ?? DEFAULT_DASHBOARD_URL,
             nodeExecutable: path.win32.resolve(options.nodeExecutable ?? process.execPath),
@@ -337,9 +342,10 @@ function renderWindowsSyncScript(options) {
     const dashboardArgs = options.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
         : ` --dashboard-url ${powershellLiteral(options.dashboardUrl)}`;
+    const discoveryArgs = options.discoveryArgs.length > 0 ? ` ${options.discoveryArgs.join(" ")}` : "";
     const commands = options.workDirs.flatMap((root) => [
         "try {",
-        `  & $nodeExecutable $cliEntryPoint sync --workspace ${powershellLiteral(root)}${dashboardArgs} --json`,
+        `  & $nodeExecutable $cliEntryPoint sync --workspace ${powershellLiteral(root)}${dashboardArgs}${discoveryArgs} --json`,
         "  if ($LASTEXITCODE -ne 0) { $exitCode = $LASTEXITCODE }",
         "} catch {",
         "  [Console]::Error.WriteLine($_.Exception.Message)",
@@ -532,6 +538,7 @@ function renderPlist(options) {
         dashboardUrl: options.dashboardUrl,
         nodeExecutable: options.nodeExecutable,
         cliEntryPoint: options.cliEntryPoint,
+        discoveryArgs: options.discoveryArgs,
     });
     return [
         '<?xml version="1.0" encoding="UTF-8"?>',
@@ -569,7 +576,8 @@ function renderDarwinSyncCommand(options) {
     const dashboardArg = options.dashboardUrl === DEFAULT_DASHBOARD_URL
         ? ""
         : ` --dashboard-url ${shellQuote(options.dashboardUrl)}`;
-    const commands = options.workDirs.map((root) => `${shellQuote(options.nodeExecutable)} ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg} --json || exit_code=1`);
+    const discoveryArg = options.discoveryArgs.length > 0 ? ` ${options.discoveryArgs.join(" ")}` : "";
+    const commands = options.workDirs.map((root) => `${shellQuote(options.nodeExecutable)} ${shellQuote(options.cliEntryPoint)} sync --workspace ${shellQuote(root)}${dashboardArg}${discoveryArg} --json || exit_code=1`);
     return ["exit_code=0", ...commands, 'exit "$exit_code"'].join("; ");
 }
 function darwinAgentRegistrationProblems(plist, expected) {
@@ -583,6 +591,7 @@ function darwinAgentRegistrationProblems(plist, expected) {
         problems.push(`cadence is not ${expected.intervalSeconds} seconds`);
     }
     const expectedCommand = renderDarwinSyncCommand({
+        discoveryArgs: expected.discoveryArgs,
         workDirs: expected.workDirs,
         dashboardUrl: expected.dashboardUrl,
         nodeExecutable: expected.nodeExecutable,

package/dist/commands/backfill.js

@@ -1,4 +1,4 @@
-import { containsSecretLikeContent, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+import { containsSecretLikeContent, NO_UPLOAD_ATTEMPT_RECORDED, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import os from "node:os";
@@ -1081,11 +1081,14 @@ async function syncBackfillBatch(options) {
 }
 function buildBackfillSessionReport(options) {
     const uploadByKey = new Map();
+    // BLI-2107: an outcome that names a failure but has no pointer used to be
+    // dropped on the floor here, taking its reason with it.
+    const noUploadReasonBySessionId = new Map();
     for (const sync of options.syncResults) {
         if (sync.status !== "uploaded")
             continue;
         for (const outcome of sync.raw_evidence_outcomes) {
-            if (!outcome.codex_session_id || !outcome.raw_evidence_pointer_id)
+            if (!outcome.codex_session_id)
                 continue;
             const source = outcome.kind === "claude_jsonl"
                 ? "claude_code"
@@ -1094,9 +1097,16 @@ function buildBackfillSessionReport(options) {
                     : null;
             if (!source)
                 continue;
+            if (!outcome.raw_evidence_pointer_id) {
+                if (outcome.reason) {
+                    noUploadReasonBySessionId.set(outcome.codex_session_id, outcome.reason);
+                }
+                continue;
+            }
             uploadByKey.set(`${source}:${outcome.codex_session_id}`, {
                 upload_state: outcome.upload_state,
                 raw_evidence_pointer_id: outcome.raw_evidence_pointer_id,
+                reason: outcome.reason,
             });
         }
     }
@@ -1143,9 +1153,19 @@ function buildBackfillSessionReport(options) {
                 ? {
                     raw_evidence_pointer_id: upload.raw_evidence_pointer_id,
                     upload_state: upload.upload_state,
+                    ...(upload.upload_state === "upload_failed"
+                        ? { upload_reason: upload.reason ?? NO_UPLOAD_ATTEMPT_RECORDED }
+                        : {}),
                 }
                 : isRawEvidenceUploadableAttributionState(candidate.state)
-                    ? { upload_state: "not_uploaded" }
+                    ? {
+                        upload_state: "not_uploaded",
+                        // BLI-2107: same rule as live sync — an attributed session with
+                        // no pointer always says why, even when the answer is that this
+                        // path never recorded one.
+                        upload_reason: noUploadReasonBySessionId.get(candidate.session_id) ??
+                            NO_UPLOAD_ATTEMPT_RECORDED,
+                    }
                     : {}),
         };
     });

package/dist/commands/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { autostartStatus, installAutostartAgent } from "../autostart.js";
+import { savedDiscoveryLimitArgs } from "../discovery-limits.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { backfillCompletionCovers, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, } from "../local-state.js";
@@ -314,8 +315,12 @@ async function fixSyncState(context) {
     if (roots.length === 0) {
         return fail("sync-fresh", "no_roots", "sync has no saved workspace roots");
     }
+    // The remembered limits have to ride along, or the doctor's own verification
+    // sync scans differently from every other run and can fail closed on a
+    // machine the operator already fixed by hand (BLI-2362).
+    const discoveryArgs = await savedDiscoveryLimitArgs(context.command.homeDir);
     for (const repoRoot of roots) {
-        const args = ["sync", "--json", "--workspace", repoRoot];
+        const args = ["sync", "--json", "--workspace", repoRoot, ...discoveryArgs];
         if (context.command.dashboardUrl !== DEFAULT_DASHBOARD_URL) {
             args.push("--dashboard-url", context.command.dashboardUrl);
         }

package/dist/commands/local.js

@@ -15,7 +15,8 @@ import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WIN
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
 import { backfillCompletionCovers, emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCompletionMarker, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { acquireSyncLock } from "../sync-lock.js";
-import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, collectionRootPathAliases, discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
+import { collectionRootPathAliases, discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
+import { resolveDiscoveryLimits, saveDiscoveryLimits, } from "../discovery-limits.js";
 import { runAttributedWorktreeSync, matchesLiveSyncWorktree, } from "./session-sync.js";
 import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, resolveOnboardingRoots, rootRejectionExplanation, } from "../onboarding-roots.js";
 import { rawEvidenceGcSummary, runRawEvidenceLocalGc, } from "../raw-evidence-gc.js";
@@ -58,6 +59,10 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
         writeLine(io.stderr, localCommandHelp());
         return 1;
     }
+    // A limit typed on the command line is remembered for every later run,
+    // including the scheduled one nobody types into (BLI-2362). Done here so it
+    // applies to whichever command carried the flag.
+    await rememberDiscoveryLimits(command);
     try {
         switch (command.kind) {
             case "install":
@@ -1430,6 +1435,7 @@ async function runOnboard(command, io) {
         const worktrees = await discoverCommandWorktrees(collectionRoots, {
             maxDepth: command.maxDepth,
             maxRepos: command.maxRepos,
+            homeDir: command.homeDir,
             allowEmpty: true,
         }, io);
         if (worktrees.length > 1) {
@@ -1782,14 +1788,22 @@ function cursorStatusLine(sync) {
 const ALL_SESSION_SCAN_WINDOW_MINUTES = 20 * 365 * 24 * 60;
 const SESSION_SCAN_OVERRIDE_LIMIT = 10_000;
 async function discoverCommandWorktrees(repoRoot, discovery = {}, io) {
-    const maxWorktrees = discovery.maxRepos ?? DEFAULT_DISCOVERY_MAX_REPOS;
+    // What the operator typed this run, else what they typed some previous run,
+    // else the built-in defaults (BLI-2362).
+    const limits = await resolveDiscoveryLimits(discovery, discovery.homeDir);
+    const maxWorktrees = limits.maxRepos;
     const roots = Array.isArray(repoRoot)
         ? repoRoot
         : [repoRoot ?? process.cwd()];
     const result = await discoverGitWorktreesInRootsWithStatus(roots, {
-        maxDepth: discovery.maxDepth ?? DEFAULT_DISCOVERY_MAX_DEPTH,
+        maxDepth: limits.maxDepth,
         maxWorktrees,
     });
+    if (io && result.unreadable_dirs.length > 0) {
+        // Never silently dropped: anything under these folders is missing from the
+        // scan, so say so even when the run otherwise succeeds.
+        writeLine(io.stderr, unreadableDirectoriesMessage(result.unreadable_dirs));
+    }
     const worktrees = result.worktrees;
     if (!result.complete) {
         // Sync fails closed here ON PURPOSE, and that is not the bug. Advancing a
@@ -1801,7 +1815,7 @@ async function discoverCommandWorktrees(repoRoot, discovery = {}, io) {
         const message = incompleteDiscoveryMessage({
             result,
             roots,
-            maxDepth: discovery.maxDepth ?? DEFAULT_DISCOVERY_MAX_DEPTH,
+            maxDepth: limits.maxDepth,
             maxRepos: maxWorktrees,
             found: worktrees.length,
         });
@@ -1814,6 +1828,31 @@ async function discoverCommandWorktrees(repoRoot, discovery = {}, io) {
     }
     return worktrees;
 }
+/**
+ * Persists `--max-depth` / `--max-repos` when a command carried them, so the
+ * number survives into the background sync and the doctor's own sync — neither
+ * of which has anywhere to type one (BLI-2362). Best-effort: failing to record
+ * a preference must never fail the command the operator actually asked for.
+ */
+async function rememberDiscoveryLimits(command) {
+    const limits = command;
+    if (limits.maxDepth === undefined && limits.maxRepos === undefined)
+        return;
+    await saveDiscoveryLimits({ maxDepth: limits.maxDepth, maxRepos: limits.maxRepos }, limits.homeDir).catch(() => undefined);
+}
+/**
+ * Says which folders could not be opened, and therefore what the scan could not
+ * see. Reported without failing the run — an unreadable folder cannot be fixed
+ * by retrying, so blocking on one would strand the machine (BLI-2362).
+ */
+function unreadableDirectoriesMessage(unreadable) {
+    return [
+        `WARNING: ${unreadable.length} folder(s) could not be opened, so anything inside them was not scanned:`,
+        ...unreadable.map((dir) => `  ${dir.path} (${dir.code})`),
+        "Collection continued for everything else. If a repo is missing from Cockpit,",
+        "check the permissions on the folders above.",
+    ].join("\n");
+}
 /**
  * Names the roots that could not be covered and hands back a command that
  * actually fixes it, with this machine's numbers already filled in.
@@ -2039,7 +2078,7 @@ async function runLogout(command, io) {
     return 0;
 }
 async function runStart(command, io) {
-    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);
+    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos, homeDir: command.homeDir }, io);
     if (worktrees.length > 1) {
         const contexts = await Promise.all(worktrees.map((worktree) => startLocalWorkContext({
             homeDir: command.homeDir,
@@ -2176,13 +2215,25 @@ async function runSyncWithHealthReceipt(command, io) {
         };
     }
     try {
-        const exitCode = await runSyncLocked(command, io);
+        const { exitCode, failureReasons } = await runSyncLocked(command, io);
+        if (exitCode === 0) {
+            return {
+                exitCode,
+                completion: { step: "sync_complete", status: "ok" },
+            };
+        }
+        // A sync that fails by exit code says exactly as much as one that throws.
+        // It used to say `sync_failed` and nothing else, so 100% of recorded
+        // failure rows carried a null detail and the real reason was reachable only
+        // by running `cockpit status` on the machine itself (BLI-2526).
+        const reasonText = failureReasons.join("; ");
         return {
             exitCode,
             completion: {
                 step: "sync_complete",
-                status: exitCode === 0 ? "ok" : "fail",
-                ...(exitCode === 0 ? {} : { error_code: "sync_failed" }),
+                status: "fail",
+                error_code: classifySyncHealthError(reasonText),
+                error_detail: redactedSyncErrorDetail(reasonText),
             },
         };
     }
@@ -2225,11 +2276,25 @@ export function redactedSyncErrorDetail(error) {
         ? `${text.slice(0, SYNC_ERROR_DETAIL_MAX_CHARS - 1)}…`
         : text;
 }
+/**
+ * Turn a finished run into an exit code and the reasons behind it.
+ *
+ * One place, so a future return path cannot reintroduce a code with no reason.
+ * The reasons come from the run itself — the code that decided `ok` is false is
+ * the only code that knows why.
+ */
+function syncResult(run) {
+    return {
+        exitCode: run.ok ? 0 : 1,
+        failureReasons: run.ok ? [] : run.failure_reasons,
+    };
+}
 async function runSyncLocked(command, io) {
     const collectionRoots = await resolveSyncCollectionRoots(command);
     const worktrees = await discoverCommandWorktrees(collectionRoots, {
         maxDepth: command.maxDepth,
         maxRepos: command.maxRepos,
+        homeDir: command.homeDir,
         allowEmpty: true,
     }, io);
     const run = await runAttributedWorktreeSync({
@@ -2254,7 +2319,7 @@ async function runSyncLocked(command, io) {
                 codex_sessions: run.summary,
                 raw_evidence_gc: gc,
             }, null, 2));
-            return run.ok ? 0 : 1;
+            return syncResult(run);
         }
         writeLine(run.ok ? io.stdout : io.stderr, `Cockpit parent sync ${runStatus} ${run.outcomes.filter((outcome) => outcome.sync.status === "uploaded").length}/${run.outcomes.length} worktree(s).`);
         for (const outcome of run.outcomes) {
@@ -2266,7 +2331,7 @@ async function runSyncLocked(command, io) {
         writeAgentSessionSummary(io, run.summary);
         if (gc && !gc.skipped)
             writeLine(io.stdout, rawEvidenceGcSummary(gc));
-        return run.ok ? 0 : 1;
+        return syncResult(run);
     }
     const result = run.outcomes[0]?.sync;
     if (!result) {
@@ -2282,7 +2347,7 @@ async function runSyncLocked(command, io) {
             codex_sessions: run.summary,
             raw_evidence_gc: gc,
         }, null, 2));
-        return run.ok ? 0 : 1;
+        return syncResult(run);
     }
     if (run.ok) {
         writeLine(io.stdout, "Cockpit ambient envelope uploaded.");
@@ -2297,18 +2362,18 @@ async function runSyncLocked(command, io) {
         writeLine(io.stdout, cursorStatusLine(result));
         if (gc && !gc.skipped)
             writeLine(io.stdout, rawEvidenceGcSummary(gc));
-        return 0;
+        return syncResult(run);
     }
     if (result.status === "uploaded") {
         writeLine(io.stderr, "Cockpit ambient upload was accepted, but session collection is partial; retry `cockpit sync`.");
         writeAgentSessionSummary(io, run.summary);
-        return 1;
+        return syncResult(run);
     }
     writeLine(io.stderr, "Cockpit ambient upload failed; safe retry metadata was spooled.");
     writeLine(io.stderr, `Ticket: ${displayTicketId(result.ticket_id)}`);
     writeLine(io.stderr, `Failure: ${result.failure_reason}`);
     writeLine(io.stderr, `Retry: ${result.retry_command}`);
-    return 1;
+    return syncResult(run);
 }
 async function resolveSyncCollectionRoots(command) {
     const explicitRoots = normalizeCollectionRoots(command.repoRoot ? [command.repoRoot] : []);
@@ -2472,7 +2537,7 @@ async function runSyncRawEvidenceGc(command, io) {
 }
 async function runStatus(command, io) {
     const backfillCursor = await inspectBackfillCursor(command.homeDir);
-    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);
+    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos, homeDir: command.homeDir }, io);
     if (worktrees.length > 1) {
         const statuses = await Promise.all(worktrees.map(async (worktree) => ({
             ...(await inspectLocalCollectorStatus({
@@ -2703,7 +2768,7 @@ function sessionsWindowLine(window) {
 async function runSessions(command, io) {
     const now = new Date();
     const homeDir = command.homeDir ?? os.homedir();
-    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);
+    const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos, homeDir: command.homeDir }, io);
     const window = await sessionsScanWindow(command, now);
     const wantCodex = command.source !== "claude";
     const wantClaude = command.source !== "codex";

package/dist/commands/public-root.js

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

package/dist/commands/session-sync.js

@@ -6,7 +6,7 @@
 import os from "node:os";
 import path from "node:path";
 import { getCollectorRuntimePaths, readLocalCollectorConfig, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "../local-state.js";
-import { CODEX_SESSION_ATTRIBUTION_STATE_RANK, } from "@bli-cockpit/telemetry-core";
+import { CODEX_SESSION_ATTRIBUTION_STATE_RANK, NO_UPLOAD_ATTEMPT_RECORDED, } from "@bli-cockpit/telemetry-core";
 import { flushPendingCodexSessionReports, LocalUploadBlockedError, queueCodexSessionReport, syncLocalAmbientEnvelope, } from "../upload.js";
 import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
 import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
@@ -15,6 +15,14 @@ import { CLAUDE_CURSOR_FILENAME, countStaleSessions, emptyRawEvidenceCursorState
 import { normalizeCollectionRoots } from "../root-normalization.js";
 import { clearSourceRetryFailure, readLocalUploadSpoolState, recordSourceRetryFailure, } from "../spool/local-spool.js";
 import { isLiveRawEvidenceSyncAttribution, } from "../raw-evidence-attribution-policy.js";
+/**
+ * The label used when a sync fails and nothing on the way there said why.
+ *
+ * A deliberate sentinel rather than a fallback to `sync_failed`: it means the
+ * gate is real but its reason is unrecorded, which is a bug in this file, and
+ * it should be visible as one instead of blending into the generic bucket.
+ */
+export const SYNC_FAILED_WITHOUT_REASON = "sync_failed_reason_not_recorded";
 const CLAUDE_FIRST_RUN_BACKFILL_MINUTES = 14 * 24 * 60;
 const CLAUDE_DAMP_GROWTH_BYTES = 256 * 1024;
 const CLAUDE_DAMP_MAX_AGE_MS = 6 * 60 * 60 * 1000;
@@ -414,20 +422,56 @@ export async function runAttributedWorktreeSync(options) {
         growthDamped: dampedClaudePointers.size,
         report,
     });
-    ok =
-        ok &&
-            !codexAttribution.session_limit_applied &&
-            !claudeAttribution.session_limit_applied &&
-            outcomes.every(({ sync }) => sync.raw_evidence_failed_count === 0 &&
-                !sync.raw_evidence_retry_required &&
-                sync.raw_evidence_deferred_byte_budget === 0 &&
-                sync.raw_evidence_deferred_object_budget === 0) &&
-            codexAttributionReadFailureCount(codexAttribution) === 0 &&
-            claudeAttributionReadFailureCount(claudeAttribution) === 0 &&
-            sourceScanRetryReason("codex", codexAttribution) === null &&
-            sourceScanRetryReason("claude_code", claudeAttribution) === null &&
-            (!reportRequired || report.posted);
-    return { ok, outcomes, codexAttribution, claudeAttribution, summary };
+    // Same conditions as before, one per line, each writing down its own reason.
+    // The old version was a single boolean chain: correct, and completely mute.
+    const failureReasons = new Set();
+    const fail = (condition, reason) => {
+        if (condition)
+            failureReasons.add(reason);
+    };
+    for (const { worktree, sync } of outcomes) {
+        if (sync.status !== "uploaded") {
+            // The spooled reason is the most specific thing anyone has, so lead with
+            // it and name the worktree it belongs to — a fleet failure is usually one
+            // repo, and "which one" is the first question asked.
+            failureReasons.add(sync.status === "spooled" && sync.failure_reason
+                ? `${worktree.worktree_label}:${sync.failure_reason}`
+                : `${worktree.worktree_label}:upload_${sync.status}`);
+        }
+        for (const reason of sync.raw_evidence_failure_reasons ?? []) {
+            failureReasons.add(`raw_evidence:${reason}`);
+        }
+        for (const reason of sync.raw_evidence_retry_reasons ?? []) {
+            failureReasons.add(`raw_evidence_retry:${reason}`);
+        }
+        fail(sync.raw_evidence_deferred_byte_budget > 0, "deferred_byte_budget");
+        fail(sync.raw_evidence_deferred_object_budget > 0, "deferred_object_budget");
+    }
+    fail(codexAttribution.session_limit_applied, "codex_session_limit_applied");
+    fail(claudeAttribution.session_limit_applied, "claude_session_limit_applied");
+    fail(codexAttributionReadFailureCount(codexAttribution) > 0, "codex_session_read_failed");
+    fail(claudeAttributionReadFailureCount(claudeAttribution) > 0, "claude_session_read_failed");
+    const codexScanRetry = sourceScanRetryReason("codex", codexAttribution);
+    if (codexScanRetry)
+        failureReasons.add(`codex_scan:${codexScanRetry}`);
+    const claudeScanRetry = sourceScanRetryReason("claude_code", claudeAttribution);
+    if (claudeScanRetry)
+        failureReasons.add(`claude_scan:${claudeScanRetry}`);
+    fail(reportRequired && !report.posted, `session_report_unposted:${report.reason ?? "unknown"}`);
+    // `ok` may already be false from the per-worktree loop above; the outcome
+    // scan re-derives that, so the two agree by construction.
+    ok = ok && failureReasons.size === 0;
+    if (!ok && failureReasons.size === 0) {
+        failureReasons.add(SYNC_FAILED_WITHOUT_REASON);
+    }
+    return {
+        ok,
+        failure_reasons: [...failureReasons].sort(),
+        outcomes,
+        codexAttribution,
+        claudeAttribution,
+        summary,
+    };
 }
 export const ATTRIBUTION_STATE_RANK = CODEX_SESSION_ATTRIBUTION_STATE_RANK;
 function normalizeCodexResult(result) {
@@ -474,7 +518,7 @@ function normalizeClaudeResult(result) {
  * session's upload state (D3). Damped Claude sessions report `reused_existing`
  * carrying their prior durable pointer.
  */
-function buildAgentSessionReport(options) {
+export function buildAgentSessionReport(options) {
     const normalized = [
         ...options.codexResults.map(normalizeCodexResult),
         ...options.claudeResults.map(normalizeClaudeResult),
@@ -495,11 +539,23 @@ function buildAgentSessionReport(options) {
     // Main-file outcomes only (D3): a sidecar making it must never mark a session
     // uploaded when the main did not.
     const uploadByKey = new Map();
+    // BLI-2107: why a session got no pointer, keyed the same way. The reasons
+    // already existed — file_too_large, deferred_byte_budget, the redaction
+    // guards — but only as aggregate skip counts in the health report, so no
+    // individual session could say what happened to it.
+    const noUploadReasonByKey = new Map();
+    // A worktree sync that did not finish carries no per-session outcomes, and
+    // WorktreeSyncOutcome does not record which sessions it was going to cover.
+    // So this pass knows only that it was degraded, not which session each
+    // failure belonged to — and says exactly that rather than picking one.
+    let anySyncIncomplete = false;
     for (const outcome of options.outcomes) {
-        if (outcome.sync.status !== "uploaded")
+        if (outcome.sync.status !== "uploaded") {
+            anySyncIncomplete = true;
             continue;
+        }
         for (const upload of outcome.sync.raw_evidence_outcomes) {
-            if (!upload.codex_session_id || !upload.raw_evidence_pointer_id)
+            if (!upload.codex_session_id)
                 continue;
             const source = upload.kind === "claude_jsonl"
                 ? "claude_code"
@@ -508,7 +564,15 @@ function buildAgentSessionReport(options) {
                     : null;
             if (!source)
                 continue; // sidecars and other kinds do not set session state
-            uploadByKey.set(`${source}:${upload.codex_session_id}`, upload);
+            const key = `${source}:${upload.codex_session_id}`;
+            if (!upload.raw_evidence_pointer_id) {
+                // An outcome with no pointer is a failure that named itself. Keep the
+                // reason even though there is nothing to point at.
+                if (upload.reason)
+                    noUploadReasonByKey.set(key, upload.reason);
+                continue;
+            }
+            uploadByKey.set(key, upload);
         }
     }
     return [...bestByKey.values()].map((result) => {
@@ -548,6 +612,13 @@ function buildAgentSessionReport(options) {
                 ? {
                     raw_evidence_pointer_id: upload.raw_evidence_pointer_id,
                     upload_state: upload.upload_state,
+                    // A failed upload names itself; a successful one has nothing to
+                    // explain.
+                    ...(upload.upload_state === "upload_failed"
+                        ? {
+                            upload_reason: upload.reason ?? NO_UPLOAD_ATTEMPT_RECORDED,
+                        }
+                        : {}),
                 }
                 : priorDurablePointer
                     ? {
@@ -556,7 +627,19 @@ function buildAgentSessionReport(options) {
                     }
                     : result.state === "attributed" ||
                         result.state === "attributed_fallback"
-                        ? { upload_state: "not_uploaded" }
+                        ? {
+                            upload_state: "not_uploaded",
+                            // BLI-2107: `not_uploaded` used to be the branch of last
+                            // resort, recording that nothing happened and never why. It
+                            // now always carries a cause, even when the cause is that we
+                            // have none — a session labelled NO_UPLOAD_ATTEMPT_RECORDED
+                            // is a path that still needs instrumenting, and saying so is
+                            // the point.
+                            upload_reason: noUploadReasonByKey.get(key) ??
+                                (anySyncIncomplete
+                                    ? "sync_incomplete_this_pass"
+                                    : NO_UPLOAD_ATTEMPT_RECORDED),
+                        }
                         : {}),
         };
     });

package/dist/discovery-limits.js

@@ -0,0 +1,89 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, } from "./repo-identity.js";
+import { getCollectorRuntimePaths } from "./local-state.js";
+const SCHEMA_VERSION = "cockpit-discovery-limits.v1";
+// A depth beyond this is a typo rather than a workspace, and an unbounded walk
+// on a huge tree is its own outage. Same for the repo cap.
+const MAX_ALLOWED_DEPTH = 64;
+const MAX_ALLOWED_REPOS = 5000;
+function discoveryLimitsFile(homeDir) {
+    return path.join(getCollectorRuntimePaths(homeDir).state_dir, "discovery-limits.json");
+}
+function sanitizeLimit(value, ceiling) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        return undefined;
+    if (value < 1 || value > ceiling)
+        return undefined;
+    return value;
+}
+/**
+ * Reads the remembered limits. Never throws: a corrupt file falls back to the
+ * defaults rather than taking collection down, because failing to read a tuning
+ * knob is not a reason to stop collecting.
+ */
+export async function readSavedDiscoveryLimits(homeDir = os.homedir()) {
+    try {
+        const raw = await fs.readFile(discoveryLimitsFile(homeDir), "utf8");
+        const parsed = JSON.parse(raw);
+        return {
+            max_depth: sanitizeLimit(parsed.max_depth, MAX_ALLOWED_DEPTH),
+            max_repos: sanitizeLimit(parsed.max_repos, MAX_ALLOWED_REPOS),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Remembers limits an operator passed explicitly. Only writes the ones actually
+ * supplied, so raising the depth does not quietly reset a repo cap someone set
+ * earlier for their own reasons.
+ */
+export async function saveDiscoveryLimits(limits, homeDir = os.homedir()) {
+    const maxDepth = sanitizeLimit(limits.maxDepth, MAX_ALLOWED_DEPTH);
+    const maxRepos = sanitizeLimit(limits.maxRepos, MAX_ALLOWED_REPOS);
+    if (maxDepth === undefined && maxRepos === undefined)
+        return;
+    const existing = await readSavedDiscoveryLimits(homeDir);
+    const next = {
+        schema_version: SCHEMA_VERSION,
+        max_depth: maxDepth ?? existing.max_depth,
+        max_repos: maxRepos ?? existing.max_repos,
+        updated_at: new Date().toISOString(),
+    };
+    const file = discoveryLimitsFile(homeDir);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, `${JSON.stringify(next, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+/**
+ * The limits a scan should actually use: what the operator typed this run,
+ * else what they typed some previous run, else the built-in defaults.
+ */
+export async function resolveDiscoveryLimits(command, homeDir = os.homedir()) {
+    const saved = await readSavedDiscoveryLimits(homeDir);
+    return {
+        maxDepth: command.maxDepth ?? saved.max_depth ?? DEFAULT_DISCOVERY_MAX_DEPTH,
+        maxRepos: command.maxRepos ?? saved.max_repos ?? DEFAULT_DISCOVERY_MAX_REPOS,
+    };
+}
+/**
+ * The flags a generated background command needs so a scheduled run scans the
+ * same way an operator's manual run did. Empty when the machine is on the
+ * defaults, which keeps the common plist/Task Scheduler command unchanged.
+ */
+export async function savedDiscoveryLimitArgs(homeDir = os.homedir()) {
+    const saved = await readSavedDiscoveryLimits(homeDir);
+    const args = [];
+    if (saved.max_depth !== undefined) {
+        args.push("--max-depth", String(saved.max_depth));
+    }
+    if (saved.max_repos !== undefined) {
+        args.push("--max-repos", String(saved.max_repos));
+    }
+    return args;
+}

package/dist/evidence-upload-client.js

@@ -1,4 +1,4 @@
-import { RAW_EVIDENCE_UPLOAD_DEFAULT_CHUNK_BYTES, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, RAW_EVIDENCE_UPLOAD_MAX_OBJECTS_PER_BEGIN, RawEvidenceLegacyUploadResponseSchema, RawEvidenceRedactionMetadataSchema, RawEvidenceUploadBeginResponseSchema, RawEvidenceUploadCommitResponseSchema, } from "@bli-cockpit/telemetry-core";
+import { RAW_EVIDENCE_UPLOAD_DEFAULT_CHUNK_BYTES, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, RAW_EVIDENCE_UPLOAD_MAX_OBJECTS_PER_BEGIN, RawEvidenceLegacyUploadResponseSchema, RawEvidenceRedactionMetadataSchema, RawEvidenceUploadBeginResponseSchema, RawEvidenceUploadCommitResponseSchema, isPermanentUploadFailure, } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 const DEFAULT_MAX_ATTEMPTS = 3;
@@ -214,6 +214,14 @@ async function uploadOneObject(options, entry, disposition, chunkSizeBytes) {
         object_key: objectKey,
     });
     if (!commit.ok) {
+        // The server can tell us this object will be refused again. Take its reason
+        // verbatim so the label names the cause ("storage rejected 116 MB") instead
+        // of the transport ("commit_failed_http_500"), which is all the fleet could
+        // say for the 57 days of BLI-2528.
+        const permanent = permanentCommitRejection(commit.body);
+        if (permanent) {
+            return failedOutcome(entry.file, permanent, uploadedChunks);
+        }
         const detail = safeFailureDetail(commit.body);
         return failedOutcome(entry.file, `commit_failed_http_${commit.status}${detail ? `_${detail}` : ""}`, uploadedChunks);
     }
@@ -376,6 +384,24 @@ function failedOutcome(file, reason, uploadedChunks = 0) {
         uploaded_chunk_count: uploadedChunks,
     };
 }
+/**
+ * The server's verdict that repeating this commit is pointless, or null.
+ *
+ * Two conditions, both required: the response says `retryable: false`, and the
+ * reason is one this collector has classified as permanent. The second check is
+ * the important one. A newer dashboard could declare a reason this CLI has never
+ * heard of, and quietly abandoning an object on a word we cannot interpret is
+ * exactly the silent drop the fleet contract forbids — so an unclassified reason
+ * falls through to the ordinary retry path and stays visible.
+ */
+function permanentCommitRejection(body) {
+    if (!body || typeof body !== "object")
+        return null;
+    if (body.retryable !== false)
+        return null;
+    const reason = safeFailureDetail(body);
+    return reason && isPermanentUploadFailure(reason) ? reason : null;
+}
 function safeFailureDetail(body) {
     if (!body || typeof body !== "object")
         return null;

package/dist/repo-identity.js

@@ -31,6 +31,12 @@ const SKIPPED_DIR_NAMES = new Set([
  */
 export const DEFAULT_DISCOVERY_MAX_DEPTH = 20;
 export const DEFAULT_DISCOVERY_MAX_REPOS = 200;
+/** Caps the reported list so one pathological tree cannot dominate a receipt. */
+const MAX_REPORTED_UNREADABLE_DIRS = 25;
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === "string" ? code : "UNKNOWN";
+}
 export async function resolveRepoWorktreeIdentity(repoRoot) {
     const requestedPath = path.resolve(repoRoot);
     const gitRoot = await runGit(["rev-parse", "--show-toplevel"], requestedPath);
@@ -89,6 +95,7 @@ export async function discoverGitWorktreesWithStatus(root, options = {}) {
     const stack = [{ dir: resolvedRoot, depth: 0 }];
     const visited = new Set();
     const incompleteReasons = new Set();
+    const unreadableDirs = [];
     while (stack.length > 0) {
         if (discovered.size >= maxWorktrees) {
             incompleteReasons.add("max_worktrees_reached");
@@ -107,7 +114,18 @@ export async function discoverGitWorktreesWithStatus(root, options = {}) {
             discovered.set(identity.worktree_fingerprint, identity);
             continue;
         }
-        const entries = await fs.readdir(current.dir, { withFileTypes: true }).catch(() => []);
+        // A failed read is recorded, never swallowed: anything beneath this folder
+        // is missing from the scan, and the operator has to be able to see that.
+        let entries;
+        try {
+            entries = await fs.readdir(current.dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (unreadableDirs.length < MAX_REPORTED_UNREADABLE_DIRS) {
+                unreadableDirs.push({ path: current.dir, code: errorCode(error) });
+            }
+            continue;
+        }
         if (current.depth >= maxDepth) {
             if (entries.some((entry) => entry.isDirectory() && !shouldSkipDirectory(entry.name))) {
                 incompleteReasons.add("max_depth_reached");
@@ -130,6 +148,7 @@ export async function discoverGitWorktreesWithStatus(root, options = {}) {
         incomplete_reasons: [...incompleteReasons].sort(),
         // Single-root scanner: the only root in play is the one it was handed.
         incomplete_roots: incompleteReasons.size === 0 ? [] : [path.resolve(root)],
+        unreadable_dirs: unreadableDirs,
     };
 }
 /**
@@ -147,6 +166,7 @@ export async function discoverGitWorktreesInRootsWithStatus(roots, options = {})
     const discovered = new Map();
     const incompleteReasons = new Set();
     const incompleteRoots = new Set();
+    const unreadableDirs = [];
     for (const root of roots) {
         const result = await discoverGitWorktreesWithStatus(root, {
             ...options,
@@ -156,6 +176,11 @@ export async function discoverGitWorktreesInRootsWithStatus(roots, options = {})
             incompleteReasons.add(reason);
             incompleteRoots.add(root);
         }
+        for (const dir of result.unreadable_dirs) {
+            if (unreadableDirs.length >= MAX_REPORTED_UNREADABLE_DIRS)
+                break;
+            unreadableDirs.push(dir);
+        }
         for (const worktree of result.worktrees) {
             if (discovered.size >= maxWorktrees) {
                 if (!discovered.has(worktree.worktree_fingerprint)) {
@@ -174,6 +199,7 @@ export async function discoverGitWorktreesInRootsWithStatus(roots, options = {})
         complete: incompleteReasons.size === 0,
         incomplete_reasons: [...incompleteReasons].sort(),
         incomplete_roots: [...incompleteRoots].sort(),
+        unreadable_dirs: unreadableDirs,
     };
 }
 /**
@@ -242,6 +268,9 @@ async function expandLinkedWorktrees(identities, maxWorktrees, allowedRoots) {
         worktrees,
         complete: incompleteReasons.length === 0,
         incomplete_reasons: incompleteReasons,
+        // Expansion asks git for its own worktree list; it never walks folders, so
+        // it has no unreadable directories of its own to report.
+        unreadable_dirs: [],
         // Linked-worktree expansion is not scoped to one root; callers merge this
         // into a result that already knows which roots were involved.
         incomplete_roots: [],

package/dist/upload.js

@@ -1,4 +1,4 @@
-import { AgentImageArtifactReportRequestSchema, CODEX_SESSION_REPORT_MAX_SESSIONS, CodexSessionAttributionReportResponseSchema, EvidenceCompletenessPayloadSchema, TelemetryIngestEnvelopeSchema, TelemetryIngestEventDtoSchema, } from "@bli-cockpit/telemetry-core";
+import { AgentImageArtifactReportRequestSchema, CODEX_SESSION_REPORT_MAX_SESSIONS, CodexSessionAttributionReportResponseSchema, EvidenceCompletenessPayloadSchema, TelemetryIngestEnvelopeSchema, TelemetryIngestEventDtoSchema, isPermanentUploadFailure, } from "@bli-cockpit/telemetry-core";
 import path from "node:path";
 import { getCollectorRuntimePaths, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, readLocalWorkContextForRepo, } from "./local-state.js";
 import { runLocalSourceCollectors } from "./adapters/local-sources.js";
@@ -236,6 +236,27 @@ export async function syncLocalAmbientEnvelope(options = {}) {
                 retry_command: "cockpit sync",
             });
         }
+        else {
+            // No retry to queue, but a permanently rejected object still has to say
+            // so. `recordUploadBlocked` names the reason without spooling a retry —
+            // the machine reports the failure instead of promising a fix it cannot
+            // deliver, and `cockpit status` stops reading clean.
+            const permanentReason = permanentEvidenceFailureReason(uploadOutcomes);
+            if (permanentReason) {
+                await recordUploadBlocked(paths, {
+                    attemptedAt,
+                    reason: permanentReason,
+                });
+                // stderr, which launchd captures to `sync.err.log`, so an unattended
+                // machine leaves a dated record of the objects it gave up on. Reason
+                // labels and counts only — never a path or a byte of content.
+                console.error("[cockpit-sync] raw evidence permanently rejected", JSON.stringify({
+                    attempted_at: attemptedAt,
+                    reason: permanentReason,
+                    object_count: permanentFailedOutcomes(uploadOutcomes).length,
+                }));
+            }
+        }
         return {
             status: "uploaded",
             dashboard_url: built.dashboard_url,
@@ -307,8 +328,37 @@ function retrySourcesForFailedSync(options, facts) {
     }
     return [...sources];
 }
+/**
+ * The failed uploads a later attempt could still rescue.
+ *
+ * An object storage has already refused on its own terms is not one of them,
+ * and counting it as one is what kept Edward's Mac in `retry_pending` through
+ * 13 consecutive syncs that were never going to end differently (BLI-2528).
+ */
+function retryableFailedOutcomes(outcomes) {
+    return outcomes.filter((outcome) => outcome.upload_state === "upload_failed" &&
+        !isPermanentUploadFailure(outcome.reason));
+}
+/** Failed uploads that no retry can rescue, kept so they can still be named. */
+function permanentFailedOutcomes(outcomes) {
+    return outcomes.filter((outcome) => outcome.upload_state === "upload_failed" &&
+        isPermanentUploadFailure(outcome.reason));
+}
+/**
+ * The reason to show for objects that failed for good.
+ *
+ * Returns null when there are none. These never queue a retry, but they must
+ * never disappear either: a machine with a permanently rejected object has
+ * missing collection, and a status that reads clean would hide it.
+ */
+function permanentEvidenceFailureReason(outcomes) {
+    const reasons = new Set(permanentFailedOutcomes(outcomes).map((outcome) => outcome.reason ?? "unknown"));
+    if (reasons.size === 0)
+        return null;
+    return `raw_evidence_permanently_rejected:${[...reasons].sort().join(",")}`;
+}
 function hasRetryableEvidenceGap(facts, outcomes) {
-    if (outcomes.some((outcome) => outcome.upload_state === "upload_failed")) {
+    if (retryableFailedOutcomes(outcomes).length > 0) {
         return true;
     }
     if (!facts)
@@ -326,10 +376,8 @@ function hasRetryableEvidenceGap(facts, outcomes) {
 }
 function retryableEvidenceGapReason(facts, outcomes) {
     const reasons = new Set();
-    for (const outcome of outcomes) {
-        if (outcome.upload_state === "upload_failed") {
-            reasons.add(outcome.reason ?? "upload_failed");
-        }
+    for (const outcome of retryableFailedOutcomes(outcomes)) {
+        reasons.add(outcome.reason ?? "upload_failed");
     }
     if (facts) {
         if (facts.deferred_byte_budget_count > 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "private": false,
   "type": "module",
   "bin": {
@@ -26,6 +26,6 @@
     "test": "node dist/cli.js --help && node ../../scripts/assert-public-cli-routing.mjs && node ../../scripts/assert-public-package-pack.mjs --workspace=@bli-cockpit/cli"
   },
   "dependencies": {
-    "@bli-cockpit/telemetry-core": "0.1.15"
+    "@bli-cockpit/telemetry-core": "0.1.17"
   }
 }