@bli-cockpit/cli 0.2.28 → 0.2.29

package/dist/commands/backfill.js

@@ -1163,6 +1163,13 @@ async function syncBackfillBatch(options) {
         })),
         claudeAttributionScan: options.claudeAttribution ?? undefined,
         rawEvidenceBudget: options.rawEvidenceBudget,
+        // `cockpit backfill` is only ever an operator asking — by hand, through
+        // onboarding, through doctor, or by running the retry command Cockpit
+        // printed. The delivery-backoff window is the scheduler's cadence, so it
+        // does not gate this pass: honouring it here made the retry that follows a
+        // failed commit a 15-minute no-op that reported
+        // `durable_session_pointer_missing` and never named the hold (BLI-3118).
+        evidenceDeliveryMode: "operator_retry",
         fetch: options.fetchImpl,
     };
     try {

package/dist/commands/cli-io.js

@@ -0,0 +1,92 @@
+import { createCapturedExecRunner, createInteractiveExecRunner, } from "../process-runner.js";
+export function writeLine(stream, text) {
+    stream.write(`${text}\n`);
+}
+/** Writes text through unchanged, adding only the trailing newline it lacks. */
+export function writeRaw(stream, text) {
+    if (!text)
+        return;
+    stream.write(text);
+    if (!text.endsWith("\n"))
+        stream.write("\n");
+}
+export function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function writeExecOutput(io, result, options) {
+    if (options.stdout)
+        writeRaw(io.stdout, result.stdout);
+    if (options.stderr)
+        writeRaw(io.stderr, result.stderr);
+}
+export function isInteractiveStdin(io) {
+    return Boolean(io.stdin.isTTY);
+}
+/**
+ * Reads one line from stdin after writing a prompt. Shared by the onboard email
+ * prompt and the autostart prompt; callers gate on `isInteractiveStdin` first so
+ * headless / piped / spawned runs never block on input.
+ */
+export async function readLine(io, prompt) {
+    io.stdout.write(prompt);
+    io.stdin.setEncoding("utf8");
+    return new Promise((resolve) => {
+        const onData = (chunk) => {
+            io.stdin.removeListener("data", onData);
+            io.stdin.pause();
+            resolve(chunk);
+        };
+        io.stdin.resume();
+        io.stdin.on("data", onData);
+    });
+}
+/** Enter means yes: only an explicit `n`/`no` declines. */
+export function yesByDefault(raw) {
+    const answer = raw.trim().split(/\s+/u)[0]?.toLowerCase() ?? "";
+    return answer !== "n" && answer !== "no";
+}
+/** Collects what a nested command writes instead of letting it reach the user. */
+export function bufferedWritable(chunks) {
+    return {
+        write(chunk) {
+            chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+            return true;
+        },
+    };
+}
+export function replayCaptured(stream, chunks) {
+    for (const chunk of chunks)
+        stream.write(chunk);
+}
+/** Captured `--json` stdout, parsed when it is JSON and handed back raw when it is not. */
+export function parseCapturedJson(chunks) {
+    const text = chunks.join("").trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function defaultExec() {
+    return createCapturedExecRunner();
+}
+export function defaultInteractiveExec() {
+    return createInteractiveExecRunner();
+}
+export function defaultIo() {
+    if (!globalThis.fetch) {
+        throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
+    }
+    return {
+        stdin: process.stdin,
+        stdout: process.stdout,
+        stderr: process.stderr,
+        env: process.env,
+        fetch: globalThis.fetch.bind(globalThis),
+        exec: defaultExec(),
+        interactiveExec: defaultInteractiveExec(),
+    };
+}

package/dist/commands/collection-report.js

@@ -0,0 +1,135 @@
+import { writeLine } from "./cli-io.js";
+import { matchesLiveSyncWorktree, } from "./session-sync.js";
+export function shortSha(value) {
+    return value ? value.slice(0, 12) : "unknown";
+}
+export function displayTicketId(ticketId) {
+    return ticketId ?? "general ambient";
+}
+export function displayWorkLabel(status) {
+    if (status.work_label && status.work_id)
+        return `${status.work_label} (${status.work_id})`;
+    return status.work_label ?? status.work_id ?? "no active work context";
+}
+function sourceFunnelLine(label, counts) {
+    const readFailures = counts.read_failures > 0 ? `, read_failures ${counts.read_failures}` : "";
+    return `${label} sessions: attributed ${counts.attributed}, fallback ${counts.attributed_fallback}, ambiguous ${counts.ambiguous}, unattributed ${counts.unattributed}, skipped ${counts.skipped}, stale ${counts.stale}${readFailures}`;
+}
+function attributionReportLine(summary) {
+    return summary.report_posted
+        ? "Attribution report: recorded"
+        : `Attribution report: skipped (${summary.report_reason})`;
+}
+/**
+ * One funnel line per source, an anomaly diagnostics line only when something
+ * is nonzero (clean syncs stay one line per source), and the report line.
+ * Counts only — project-dir slugs encode full local paths and never print
+ * (B.4 §5).
+ */
+export function writeAgentSessionSummary(io, summary) {
+    writeLine(io.stdout, sourceFunnelLine("Codex", summary.codex));
+    writeLine(io.stdout, sourceFunnelLine("Claude", summary.claude));
+    const claudeDiagnostics = claudeDiagnosticsLine(summary);
+    if (claudeDiagnostics)
+        writeLine(io.stdout, claudeDiagnostics);
+    writeLine(io.stdout, attributionReportLine(summary));
+}
+function claudeDiagnosticsLine(summary) {
+    // Anomaly-only (D34): sidecars_collected/uploaded are normal-operation
+    // counters and must NOT trigger this line, or a healthy orchestrated sync
+    // prints it 48×/day in launchd logs. Clean syncs stay one line per source.
+    const claude = summary.claude;
+    const parts = [];
+    if (claude.sidecars_skipped)
+        parts.push(`sidecars_skipped ${claude.sidecars_skipped}`);
+    if (claude.sidecars_capped)
+        parts.push(`sidecars_capped ${claude.sidecars_capped}`);
+    if (claude.sidecars_failed)
+        parts.push(`sidecars_failed ${claude.sidecars_failed}`);
+    if (claude.mains_oversized)
+        parts.push(`mains_oversized ${claude.mains_oversized}`);
+    if (claude.oversized_lines_skipped)
+        parts.push(`oversized_lines_skipped ${claude.oversized_lines_skipped}`);
+    if (claude.project_dirs_skipped)
+        parts.push(`project_dirs_skipped ${claude.project_dirs_skipped}`);
+    if (claude.sessions_schema_drift)
+        parts.push(`schema_drift ${claude.sessions_schema_drift}`);
+    if (claude.growth_damped)
+        parts.push(`growth_damped ${claude.growth_damped}`);
+    if (claude.first_run_backfill)
+        parts.push("first_run_backfill");
+    if (summary.files_deferred_byte_budget)
+        parts.push(`deferred_byte_budget ${summary.files_deferred_byte_budget}`);
+    if (summary.files_deferred_object_budget)
+        parts.push(`deferred_object_budget ${summary.files_deferred_object_budget}`);
+    return parts.length > 0 ? `Claude diagnostics: ${parts.join(", ")}` : null;
+}
+export function rawEvidenceSyncLine(sync) {
+    const failures = sync.raw_evidence_failure_reasons.length > 0
+        ? ` failures: ${sync.raw_evidence_failure_reasons.join(",")}`
+        : "";
+    const retries = sync.raw_evidence_retry_reasons.length > 0
+        ? ` retry_required: ${sync.raw_evidence_retry_reasons.join(",")}`
+        : "";
+    // A held object and a nine-day-old first failure both belong on this line.
+    // Neither used to appear anywhere, which is how a 1,030-attempt loop stayed
+    // invisible (BLI-3066).
+    const held = sync.raw_evidence_delivery_held_count > 0
+        ? ` held: ${sync.raw_evidence_delivery_held_count}`
+        : "";
+    const stuck = sync.raw_evidence_stuck_object_count > 0
+        ? ` stuck: ${sync.raw_evidence_stuck_object_count} (worst ${sync.raw_evidence_max_delivery_attempts} attempt(s) since ${sync.raw_evidence_oldest_delivery_failure_at ?? "unknown"})`
+        : "";
+    return `Raw evidence: uploaded ${sync.raw_evidence_uploaded_object_count} object(s) in ${sync.raw_evidence_uploaded_chunk_count} chunk(s), reused ${sync.raw_evidence_reused_count}, failed ${sync.raw_evidence_failed_count}${held}${stuck}${failures}${retries}`;
+}
+export function cursorStatusLine(sync) {
+    return `Cursor: ${sync.cursor_tracked_object_count} durable object(s) tracked`;
+}
+/**
+ * One line that cannot say "fine" while an object has never been accepted.
+ * Named reasons, worst attempt count, and the date it started.
+ */
+export function stuckEvidenceLine(status) {
+    if (status.stuck_evidence_object_count === 0)
+        return "none";
+    return `${status.stuck_evidence_object_count} object(s), ${status.stuck_evidence_held_count} held, worst ${status.stuck_evidence_max_attempts} attempt(s) since ${status.stuck_evidence_oldest_failure_at ?? "unknown"} (${status.stuck_evidence_reasons.join(",") || "unknown"})`;
+}
+/** The `--json` row for one synced worktree, shared by onboard and sync. */
+export function worktreeSyncRow(outcome, run) {
+    const { worktree, context, sync } = outcome;
+    const matchesWorktree = (result) => matchesLiveSyncWorktree(result, worktree);
+    const codexSessionCount = run.codexAttribution.results.filter(matchesWorktree).length;
+    const claudeSessionCount = run.claudeAttribution.results.filter(matchesWorktree).length;
+    const attributedSessionCount = codexSessionCount + claudeSessionCount;
+    return {
+        repo_label: context?.repo_label ?? worktree.repo_label,
+        repo_fingerprint: context?.repo_fingerprint ?? worktree.repo_fingerprint,
+        worktree_label: context?.worktree_label ?? worktree.worktree_label,
+        worktree_fingerprint: context?.worktree_fingerprint ?? worktree.worktree_fingerprint,
+        branch: context?.branch ?? worktree.branch,
+        head_sha: sync.head_sha ?? worktree.head_sha,
+        work_context_id: context?.work_context_id ?? sync.work_context_id,
+        upload_status: sync.status,
+        raw_evidence_file_count: sync.raw_evidence_file_count,
+        raw_evidence_uploaded_object_count: sync.raw_evidence_uploaded_object_count,
+        raw_evidence_uploaded_chunk_count: sync.raw_evidence_uploaded_chunk_count,
+        raw_evidence_reused_count: sync.raw_evidence_reused_count,
+        raw_evidence_failed_count: sync.raw_evidence_failed_count,
+        raw_evidence_failure_reasons: sync.raw_evidence_failure_reasons,
+        raw_evidence_retry_required: sync.raw_evidence_retry_required,
+        raw_evidence_retry_reasons: sync.raw_evidence_retry_reasons,
+        attributed_session_count: attributedSessionCount,
+        codex_session_count: codexSessionCount,
+        claude_session_count: claudeSessionCount,
+        cursor_tracked_object_count: sync.cursor_tracked_object_count,
+        failure_reason: sync.status === "spooled" ? sync.failure_reason : null,
+    };
+}
+/** Green only when the whole run is green; an accepted upload with partial collection is `partial`. */
+export function attributedSyncRunStatus(run) {
+    if (run.ok)
+        return "uploaded";
+    return run.outcomes.every((outcome) => outcome.sync.status === "uploaded")
+        ? "partial"
+        : "spooled";
+}

package/dist/commands/collection-roots.js

@@ -0,0 +1,153 @@
+/**
+ * The folders this machine is allowed to collect from: resolving them, saving
+ * them, and reading them back to prove setup actually worked.
+ *
+ * Widening the boundary is a consent decision a person makes, never a fix an
+ * agent applies — so everything here either asks or reports, and the read-back
+ * fails loudly rather than handing over a machine that will never collect.
+ * Split out of commands/local.ts (BLI-3104); moved verbatim.
+ */
+import os from "node:os";
+import path from "node:path";
+import { stat } from "node:fs/promises";
+import { isInteractiveStdin, readLine, writeLine, yesByDefault } from "./cli-io.js";
+import { COLLECTION_ROOT_REQUIRED, resolveOnboardingRoots, } from "../onboarding-roots.js";
+import { getCollectorRuntimePaths, installLocalCollector, readLocalCollectorConfig, } from "../local-state.js";
+import { collectionRootPathAliases } from "../repo-identity.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+export function onboardingRootPrompt(io) {
+    return {
+        confirm: async (message) => yesByDefault(await readLine(io, message)),
+        input: (message) => readLine(io, message),
+        message: (message) => writeLine(io.stdout, message),
+    };
+}
+export async function resolveOnboardingRootsForCommand(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
+    const interactive = !command.json && isInteractiveStdin(io);
+    const rootsResult = await resolveOnboardingRoots({
+        homeDir: command.homeDir,
+        explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
+        config: existingConfig,
+        interactive,
+        allowHomeRoot: command.allowHomeRoot,
+        prompt: interactive ? onboardingRootPrompt(io) : undefined,
+    });
+    const collectionRoots = rootsResult.roots;
+    const primaryRoot = collectionRoots[0];
+    if (!primaryRoot) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: no collection root confirmed.`);
+    }
+    const replaceRepoRoots = rootsResult.source === "prompt" &&
+        !command.collectionRoots?.length &&
+        (existingConfig?.default_repo_paths.length ?? 0) > 0;
+    return {
+        existingConfig,
+        rootsResult,
+        collectionRoots,
+        primaryRoot,
+        replaceRepoRoots,
+    };
+}
+export async function persistOnboardingRootConfig(command, resolution) {
+    const result = await installLocalCollector({
+        homeDir: command.homeDir,
+        repoRoot: resolution.primaryRoot,
+        repoRoots: resolution.collectionRoots,
+        replaceRepoRoots: resolution.replaceRepoRoots,
+        dashboardUrl: command.dashboardUrl,
+        deviceName: command.deviceName,
+    });
+    await assertCollectionRootPersisted(command.homeDir);
+    return result;
+}
+/**
+ * Setup does not get to claim success on its own say-so.
+ *
+ * Onboarding used to write the config and report success without ever reading
+ * it back. Savina's onboard did exactly that, persisted nothing, and every
+ * scheduled sync afterwards threw `collection_root_required` into a log nobody
+ * reads — twelve consecutive failures, six days at 3 uploaded of 195, found
+ * only by hand-querying the database. BLI-1986 fixed one path into that state;
+ * this closes the state itself.
+ *
+ * So we read the config back through the SAME resolution the scheduled sync
+ * will use, and fail here — in front of a human who can still fix it — rather
+ * than silently handing back a machine that will never collect.
+ */
+export async function assertCollectionRootPersisted(homeDir) {
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(homeDir)).catch(() => null);
+    const saved = normalizeCollectionRoots(config?.default_repo_paths ?? []);
+    if (saved.length === 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootNotPersistedMessage(homeDir)}`);
+    }
+    // Present in the file is not the same as usable. A root that no longer
+    // exists on disk resolves to nothing at sync time, which is the same silent
+    // dead end arriving one step later.
+    const usable = [];
+    for (const root of saved) {
+        if (await directoryExists(root))
+            usable.push(root);
+    }
+    if (usable.length === 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${collectionRootMissingOnDiskMessage(saved, homeDir)}`);
+    }
+    return usable;
+}
+/**
+ * Keep both spellings when an existing root is reached through a filesystem
+ * alias such as macOS `/var` -> `/private/var`. Deleted child paths cannot be
+ * realpathed later, so either transcript spelling must remain inside the same
+ * operator-approved physical root.
+ */
+export async function collectionRootConsentAliases(roots) {
+    return normalizeCollectionRoots(await collectionRootPathAliases(roots));
+}
+// Placeholders like <path-to-your-work-folder> make a person stop and think.
+// These print real, paste-able commands with this machine's actual paths in
+// them, so the fix is a copy away rather than a puzzle.
+function collectionRootNotPersistedMessage(homeDir) {
+    const home = path.resolve(homeDir ?? os.homedir());
+    return [
+        "Setup finished without saving a collection root, so this machine would never collect anything.",
+        "Nothing was saved, so nothing is broken — setup just did not finish.",
+        "",
+        "Fix it by running ONE of these:",
+        "",
+        "  # Sync everything on this machine (what most people want on a work laptop)",
+        "  cockpit do-everything --allow-home-root",
+        "",
+        "  # Or sync one folder — replace the path with where your projects live",
+        `  cockpit do-everything --workspace ${path.join(home, "BLI")}`,
+        "",
+        "  # Or answer the folder question interactively",
+        "  cockpit do-everything",
+        "",
+        "Then check it worked:",
+        "  cockpit status",
+    ].join("\n");
+}
+function collectionRootMissingOnDiskMessage(saved, homeDir) {
+    const home = path.resolve(homeDir ?? os.homedir());
+    return [
+        "Cockpit is set up to collect from a folder that is not on this machine:",
+        ...saved.map((root) => `  ${root}`),
+        "",
+        "That usually means the folder was renamed, moved, or deleted since setup.",
+        "",
+        "Fix it by running ONE of these:",
+        "",
+        "  # Point Cockpit at where your projects actually live now",
+        `  cockpit do-everything --workspace ${path.join(home, "BLI")}`,
+        "",
+        "  # Or sync everything on this machine and stop worrying about the path",
+        "  cockpit do-everything --allow-home-root",
+        "",
+        "Not sure where your projects are? This lists the folders Cockpit can see:",
+        "  cockpit status",
+    ].join("\n");
+}
+async function directoryExists(dir) {
+    return stat(dir).then((stats) => stats.isDirectory(), () => false);
+}

package/dist/commands/install-receipts.js

@@ -0,0 +1,193 @@
+/**
+ * Receipts: what this machine tells the dashboard about how a command went.
+ *
+ * Every step of `install`, `onboard`, `update` and every `sync` tick records a
+ * named step result here, and the outbox delivers them best-effort. A failure
+ * that names itself is the whole point — "it failed" is not a result, and a
+ * receipt nobody can act on is why BLI-2526 and BLI-2542 exist.
+ *
+ * Split out of commands/local.ts (BLI-3104) — moved verbatim; the step names,
+ * error codes and redaction rules are a server-side contract.
+ */
+import os from "node:os";
+import { errorMessage, writeLine } from "./cli-io.js";
+import { maskLocalIdentifiers, redactedHealthDetail, } from "../health-detail.js";
+import { getCollectorRuntimePaths, readLocalCollectorSessionFile, LOCAL_COLLECTOR_VERSION, } from "../local-state.js";
+import { redactSecretLikeContent } from "@bli-cockpit/telemetry-core";
+import { COLLECTION_ROOT_REQUIRED } from "../onboarding-roots.js";
+import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
+export function addInstallEvent(events, step, status, errorCode, 
+// BLI-2542: the bucket alone cannot be acted on. Callers that hold the reason
+// pass it; it is redacted at this boundary, not at the call site.
+errorMessage) {
+    const detail = errorMessage ? redactedHealthDetail(errorMessage) : "";
+    const code = errorCode ? sanitizeInstallErrorCode(errorCode) : undefined;
+    events.push({
+        step,
+        status,
+        ...(code ? { error_code: code } : {}),
+        ...(detail && detail !== code ? { error_detail: detail } : {}),
+    });
+}
+export function sanitizeInstallErrorCode(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 120);
+    return normalized || "unknown";
+}
+/**
+ * Posts pending install events. Also the collector's only per-tick listening
+ * post: the response carries the server-published `min_cli_version` floor
+ * (BLI-2678), so the last one observed is returned for the scheduled
+ * self-update step to act on. Every early-out returns null — no receipt, no
+ * floor.
+ */
+export async function reportInstallEventsBestEffort(options) {
+    if (options.events.length === 0)
+        return null;
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    try {
+        await enqueueInstallEventEntry(paths, {
+            dashboardUrl: options.dashboardUrl,
+            cliVersion: LOCAL_COLLECTOR_VERSION,
+            command: options.command,
+            osPlatform: os.platform(),
+            events: options.events.map((event) => ({
+                step: event.step.trim().slice(0, 120),
+                status: event.status,
+                ...(event.error_code
+                    ? { error_code: sanitizeInstallErrorCode(event.error_code) }
+                    : {}),
+                // Already redacted and capped at the point it was produced; bounded
+                // again here because this mapping is what the server contract sees.
+                ...(event.error_detail
+                    ? {
+                        error_detail: event.error_detail
+                            .trim()
+                            .slice(0, SYNC_ERROR_DETAIL_MAX_CHARS),
+                    }
+                    : {}),
+                ...(event.at ? { at: event.at } : {}),
+            })),
+        });
+    }
+    catch {
+        if (options.json) {
+            writeLine(options.io.stderr, "Install event outbox unavailable: local_write_failed");
+        }
+        return null;
+    }
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (!session ||
+        session.session_state !== "valid" ||
+        typeof session.device_token !== "string" ||
+        !session.device_token) {
+        return null;
+    }
+    const pending = (await readPendingInstallEventEntries(paths)).slice(0, 20);
+    const failures = [];
+    let observedMinCliVersion = null;
+    for (let offset = 0; offset < pending.length; offset += 5) {
+        await Promise.all(pending.slice(offset, offset + 5).map(async (entry) => {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 5_000);
+            try {
+                const response = await options.io.fetch(`${entry.dashboard_url}/api/ambient/install-events`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${session.device_token}`,
+                    },
+                    body: JSON.stringify({
+                        cli_version: entry.cli_version,
+                        command: entry.command,
+                        os_platform: entry.os_platform,
+                        events: entry.events,
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    throw new Error(`http_${response.status}`);
+                }
+                const receipt = (await response
+                    .json()
+                    .catch(() => null));
+                if (typeof receipt?.min_cli_version === "string" &&
+                    receipt.min_cli_version.trim()) {
+                    observedMinCliVersion = receipt.min_cli_version.trim();
+                }
+                await removeInstallEventEntry(paths, entry.outbox_id);
+            }
+            catch (error) {
+                const failureReason = classifyInstallTelemetryError(error);
+                failures.push(failureReason);
+                await recordInstallEventAttemptFailure(paths, entry, {
+                    attemptedAt: new Date().toISOString(),
+                    failureReason,
+                }).catch(() => undefined);
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }));
+    }
+    if (options.json && failures.length > 0) {
+        writeLine(options.io.stderr, `Install event telemetry queued for retry: ${[...new Set(failures)].join(",")}`);
+    }
+    return observedMinCliVersion;
+}
+function classifyInstallTelemetryError(error) {
+    if (error instanceof Error && error.name === "AbortError") {
+        return "timeout";
+    }
+    const message = errorMessage(error);
+    const status = message.match(/http_(\d{3})/i)?.[1];
+    if (status)
+        return `http_${status}`;
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED/i.test(message))
+        return "network";
+    return "failed";
+}
+export function classifySyncHealthError(error) {
+    const message = errorMessage(error);
+    if (/auth|token|session|unauthorized|forbidden|401|403/iu.test(message)) {
+        return "auth_failed";
+    }
+    if (/fetch|network|enotfound|econnrefused|timeout/iu.test(message)) {
+        return "network_failed";
+    }
+    // Anchored on the code the collector actually throws rather than on loose
+    // vocabulary. The old test matched /collection.root|workspace|repo|worktree/
+    // against the message, so any failure that merely mentioned a repo was filed
+    // as a collection-root failure and the real reason was lost (BLI-2492).
+    if (message.includes(COLLECTION_ROOT_REQUIRED) ||
+        /collection root/iu.test(message)) {
+        return "collection_root_failed";
+    }
+    return "sync_failed";
+}
+// The bucket above is for aggregation. This is the reason — the actual message,
+// redacted on the machine that produced it, before it ever leaves.
+//
+// Error text can carry absolute paths and, on some auth failures, token-shaped
+// fragments. It goes through the same deterministic redaction the collector
+// already applies to evidence, and is capped so one pathological stack trace
+// cannot dominate a health receipt.
+export const SYNC_ERROR_DETAIL_MAX_CHARS = 600;
+export function redactedSyncErrorDetail(error) {
+    const message = errorMessage(error).replace(/\s+/gu, " ").trim();
+    const { text } = redactSecretLikeContent(message, {
+        appliedBy: "local_collector",
+    });
+    // BLI-2542: the comment above always said this text can carry absolute paths,
+    // and until now nothing removed them — secret redaction matches token shapes,
+    // not filesystem paths. Same masking the doctor receipts use, so one boundary
+    // rule covers every health receipt.
+    const masked = maskLocalIdentifiers(text);
+    return masked.length > SYNC_ERROR_DETAIL_MAX_CHARS
+        ? `${masked.slice(0, SYNC_ERROR_DETAIL_MAX_CHARS - 1)}…`
+        : masked;
+}