@bli-cockpit/cli 0.2.0 → 0.2.2

package/dist/commands/local.js

@@ -5,21 +5,25 @@ import path from "node:path";
 import { createCollectorServer } from "../server.js";
 import { inspectAgentRules, installAgentRules, uninstallAgentRules, } from "../agent-rules.js";
 import { runBackfillCommand } from "./backfill.js";
+import { runDoctor } from "./doctor.js";
 import { inspectBackfillLock } from "../backfill-lock.js";
 import { parseLocalArgs, normalizeUrl } from "./local-args.js";
 import { autostartStatus, installAutostartAgent, uninstallAutostartAgent, } from "../autostart.js";
-import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext, } from "../local-state.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, inspectLocalCollectorStatus, installLocalCollector, logoutLocalCollector, pairLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, startLocalWorkContext, } from "../local-state.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";
 import { backfillCompletionMarkerPath, readBackfillCursor, } from "../cursors/backfill-cursor.js";
 import { acquireSyncLock } from "../sync-lock.js";
 import { discoverGitWorktrees } from "../repo-identity.js";
 import { runAttributedWorktreeSync, } from "./session-sync.js";
-import { COLLECTION_ROOT_REQUIRED, resolveOnboardingRoots, } from "../onboarding-roots.js";
+import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, resolveOnboardingRoots, rootRejectionExplanation, } from "../onboarding-roots.js";
+import { rawEvidenceGcSummary, runRawEvidenceLocalGc, } from "../raw-evidence-gc.js";
 export const rootCommandNames = new Set([
     "onboard",
     "update",
     "upgrade",
+    "do-everything",
+    "fix",
     "install",
     "login",
     "pair",
@@ -57,6 +61,11 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runOnboard(command, io);
             case "update":
                 return await runUpdate(command, io);
+            case "doctor":
+                return await runDoctor(command, io, {
+                    reportInstallEvents: reportInstallEventsBestEffort,
+                    selfUpdate: runSelfUpdate,
+                });
             case "login":
                 return await runLogin(command, io);
             case "logout":
@@ -90,10 +99,12 @@ export function localCommandHelp(command) {
     if (command)
         return localSubcommandHelp(command);
     return [
-        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
-        "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--no-auth] [--json]",
+        "  cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
         "  cockpit upgrade [same flags as update]",
-        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--json]",
+        "  cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--dry-run] [--json]",
+        "  cockpit fix [same flags as do-everything]",
+        "  cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
         "  cockpit login [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit pair [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--no-auth] [--json]",
         "  cockpit logout",
@@ -115,7 +126,7 @@ function localSubcommandHelp(command) {
         [
             "onboard",
             [
-                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--branch <name>] [--no-auth] [--json]",
+                "Usage: cockpit onboard [--ticket <id>] [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--branch <name>] [--no-auth] [--json]",
                 "",
                 "Installs, pairs, starts work context(s), syncs once, and prints readiness proof.",
                 "If --workspace is a parent folder, scans child git repos/worktrees and rolls them up by repo.",
@@ -129,7 +140,7 @@ function localSubcommandHelp(command) {
         [
             "install",
             [
-                "Usage: cockpit install [--dashboard-url <url>] [--workspace <path>] [--json]",
+                "Usage: cockpit install [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--json]",
                 "",
                 "Writes local collector config. Pair with `cockpit login`, then run `cockpit start` when work begins.",
                 "`--repo <path>` remains supported as a backward-compatible alias.",
@@ -139,7 +150,7 @@ function localSubcommandHelp(command) {
         [
             "update",
             [
-                "Usage: cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--no-auth] [--json]",
+                "Usage: cockpit update [--email <owner@email>] [--device-name <name>] [--dashboard-url <url>] [--workspace <path>] [--allow-home-root] [--no-auth] [--json]",
                 "",
                 "Updates the global public CLI from npm, then reruns `cockpit onboard`",
                 "with the same setup flags so pairing, saved roots, agent rules,",
@@ -155,6 +166,24 @@ function localSubcommandHelp(command) {
                 "Alias for `cockpit update`.",
             ],
         ],
+        [
+            "do-everything",
+            [
+                "Usage: cockpit do-everything [--workspace <path>] [--dashboard-url <url>] [--dry-run] [--json]",
+                "",
+                "Converges an already-onboarded intern machine: latest CLI, auth, saved roots, autostart, backfill, raw-evidence GC, and sync freshness.",
+                "`cockpit fix` is an alias.",
+                "--dry-run prints the checks and would-fix steps without writing config, plists, cursors, or install telemetry.",
+            ],
+        ],
+        [
+            "fix",
+            [
+                "Usage: cockpit fix [same flags as cockpit do-everything]",
+                "",
+                "Alias for `cockpit do-everything`.",
+            ],
+        ],
         [
             "login",
             [
@@ -294,49 +323,97 @@ function isLocalHelpRequest(argv) {
     return argv.length === 2 && (argv[1] === "--help" || argv[1] === "-h");
 }
 async function runInstall(command, io) {
-    const result = await installLocalCollector(command);
+    const installEvents = [];
+    const finish = async (code) => {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            command: "install",
+            events: installEvents,
+            json: command.json,
+            io,
+        });
+        return code;
+    };
+    const resolved = resolveInstallCommandRoots(command);
+    if (resolved.homeRootOptIn) {
+        addInstallEvent(installEvents, "home_root_optin", "ok");
+    }
+    const result = await installLocalCollector(resolved.command);
+    addInstallEvent(installEvents, "install", "ok");
     if (command.json) {
         writeLine(io.stdout, JSON.stringify(result, null, 2));
-        return 0;
+        return finish(0);
     }
     writeLine(io.stdout, "Cockpit local collector installed.");
     writeLine(io.stdout, `Config: ${result.paths.config_file}`);
     writeLine(io.stdout, `Session: ${result.paths.session_file}`);
     writeLine(io.stdout, "Auth: missing; upload stays local-only until pairing/login.");
     writeLine(io.stdout, "Next: run `cockpit login`, then `cockpit start` inside the repo; add `--ticket <id>` only when ticket work begins.");
-    return 0;
+    return finish(0);
+}
+function resolveInstallCommandRoots(command) {
+    const detailed = normalizeRootsDetailed([command.repoRoot ?? process.cwd()], {
+        homeDir: command.homeDir,
+        allowHomeRoot: command.allowHomeRoot,
+    });
+    if (detailed.roots.length > 0) {
+        const root = detailed.roots[0];
+        return {
+            command: {
+                ...command,
+                repoRoot: root,
+            },
+            homeRootOptIn: Boolean(command.allowHomeRoot) &&
+                path.resolve(root) === path.resolve(command.homeDir ?? os.homedir()),
+        };
+    }
+    if (detailed.rejected.length > 0) {
+        throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${rootRejectionExplanation(detailed.rejected[0], command)}`);
+    }
+    throw new Error(`${COLLECTION_ROOT_REQUIRED}: ${missingCollectionRootMessage(command)}`);
 }
 async function runUpdate(command, io) {
+    const installEvents = [];
+    const finish = async (code) => {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            command: "update",
+            events: installEvents,
+            json: command.json,
+            io,
+        });
+        return code;
+    };
     const exec = io.exec ?? defaultExec();
-    const installArgs = [
-        "install",
-        "-g",
-        "@bli-cockpit/cli@latest",
-        "--prefer-online",
-    ];
-    if (!command.json) {
-        writeLine(io.stdout, "Updating Cockpit CLI from npm...");
+    try {
+        await runSelfUpdate(io, { json: command.json });
     }
-    const install = await exec("npm", installArgs);
-    writeExecOutput(io, install, { stdout: !command.json, stderr: true });
-    if (install.code !== 0) {
+    catch (error) {
+        if (!(error instanceof SelfUpdateError))
+            throw error;
+        addInstallEvent(installEvents, "npm_install", "fail", error.eacces
+            ? "npm_install_eacces"
+            : "npm_install_failed");
         if (command.json) {
             writeLine(io.stdout, JSON.stringify({
                 status: "blocked",
                 step: "npm_install",
-                command: `npm ${installArgs.join(" ")}`,
-                exit_code: install.code,
+                command: `npm ${SELF_UPDATE_INSTALL_ARGS.join(" ")}`,
+                exit_code: error.result.code,
             }, null, 2));
         }
         else {
             writeLine(io.stderr, "BLOCKED: npm install failed; Cockpit CLI was not refreshed.");
-            if (isNpmEaccesFailure(install.stderr)) {
+            if (error.eacces) {
                 writeLine(io.stderr, "Fix Homebrew npm ownership once: sudo chown -R $(whoami) /opt/homebrew/lib/node_modules/@bli-cockpit /opt/homebrew/bin/cockpit");
                 writeLine(io.stderr, "Do not use `sudo npm i -g`; it makes the ownership problem come back.");
             }
         }
-        return install.code || 1;
+        return finish(error.result.code || 1);
     }
+    addInstallEvent(installEvents, "npm_install", "ok");
     if (!command.json) {
         writeLine(io.stdout, "Cockpit CLI updated. Rechecking onboarding...");
     }
@@ -345,7 +422,36 @@ async function runUpdate(command, io) {
         ...updateOnboardArgs(command),
     ]);
     writeExecOutput(io, onboard, { stdout: true, stderr: true });
-    return onboard.code;
+    addInstallEvent(installEvents, "onboard_rerun", onboard.code === 0 ? "ok" : "fail", onboard.code === 0 ? undefined : updateOnboardFailureCode(onboard));
+    return finish(onboard.code);
+}
+const SELF_UPDATE_INSTALL_ARGS = [
+    "install",
+    "-g",
+    "@bli-cockpit/cli@latest",
+    "--prefer-online",
+];
+export class SelfUpdateError extends Error {
+    result;
+    eacces;
+    constructor(result) {
+        super("npm install failed; Cockpit CLI was not refreshed.");
+        this.name = "SelfUpdateError";
+        this.result = result;
+        this.eacces = isNpmEaccesFailure(result.stderr);
+    }
+}
+export async function runSelfUpdate(io, options = {}) {
+    const exec = io.exec ?? defaultExec();
+    if (!options.json) {
+        writeLine(io.stdout, "Updating Cockpit CLI from npm...");
+    }
+    const install = await exec("npm", [...SELF_UPDATE_INSTALL_ARGS]);
+    writeExecOutput(io, install, { stdout: !options.json, stderr: true });
+    if (install.code !== 0) {
+        throw new SelfUpdateError(install);
+    }
+    return { updated: true, version: LOCAL_COLLECTOR_VERSION };
 }
 async function runRelease(command, io) {
     const releaseRoot = await findPublicReleaseRoot(process.cwd());
@@ -459,6 +565,8 @@ function updateOnboardArgs(command) {
         args.push("--max-depth", String(command.maxDepth));
     if (command.maxRepos !== undefined)
         args.push("--max-repos", String(command.maxRepos));
+    if (command.allowHomeRoot)
+        args.push("--allow-home-root");
     if (command.json)
         args.push("--json");
     return args;
@@ -466,6 +574,17 @@ function updateOnboardArgs(command) {
 function isNpmEaccesFailure(stderr) {
     return /EACCES|permission denied/i.test(stderr);
 }
+function updateOnboardFailureCode(result) {
+    const output = `${result.stdout}\n${result.stderr}`;
+    if (output.includes(COLLECTION_ROOT_REQUIRED))
+        return COLLECTION_ROOT_REQUIRED;
+    if (/pairing|approval|device_pairing/i.test(output))
+        return "pairing_timeout";
+    if (/sync_blocked|spooled|upload failed|network_or_ingest/i.test(output)) {
+        return "sync_blocked";
+    }
+    return "onboard_rerun_failed";
+}
 function updateCollectionRoots(command) {
     const roots = command.collectionRoots?.length
         ? command.collectionRoots
@@ -482,6 +601,108 @@ function updateCollectionRoots(command) {
     }
     return deduped;
 }
+function addInstallEvent(events, step, status, errorCode) {
+    events.push({
+        step,
+        status,
+        ...(errorCode ? { error_code: sanitizeInstallErrorCode(errorCode) } : {}),
+    });
+}
+function addOnboardFailureEvent(events, blocker) {
+    const step = onboardFailureStep(blocker, events);
+    const existing = events.find((event) => event.step === step && event.status === "fail");
+    if (existing)
+        return;
+    addInstallEvent(events, step, "fail", blocker);
+}
+function addAutostartInstallEvent(events, result) {
+    if (!result) {
+        addInstallEvent(events, "autostart", "skipped", "runner_unavailable");
+        return;
+    }
+    if (result.status === "unsupported") {
+        addInstallEvent(events, "autostart", "skipped", "unsupported");
+        return;
+    }
+    addInstallEvent(events, "autostart", result.loaded === false ? "fail" : "ok", result.loaded === false ? "autostart_load_failed" : undefined);
+}
+function onboardFailureStep(blocker, events) {
+    if (blocker === COLLECTION_ROOT_REQUIRED)
+        return "install";
+    if (blocker === "device_pairing")
+        return "pair";
+    if (blocker === "work_context" || blocker === "ticket_binding" || blocker === "ticket") {
+        return "work_context";
+    }
+    if (blocker === "network_or_ingest")
+        return "sync";
+    if (blocker === "install")
+        return "install";
+    const lastIncomplete = ["install", "auth", "pair", "work_context", "sync"].find((step) => !events.some((event) => event.step === step));
+    return lastIncomplete ?? "sync";
+}
+function sanitizeInstallErrorCode(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/gu, "_")
+        .replace(/^_+|_+$/gu, "")
+        .slice(0, 120);
+    return normalized || "unknown";
+}
+export async function reportInstallEventsBestEffort(options) {
+    if (options.events.length === 0)
+        return;
+    const paths = getCollectorRuntimePaths(options.homeDir);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => null);
+    if (!session ||
+        session.session_state !== "valid" ||
+        typeof session.device_token !== "string" ||
+        !session.device_token) {
+        return;
+    }
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const response = await options.io.fetch(`${options.dashboardUrl}/api/ambient/install-events`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${session.device_token}`,
+            },
+            body: JSON.stringify({
+                cli_version: LOCAL_COLLECTOR_VERSION,
+                command: options.command,
+                os_platform: os.platform(),
+                events: options.events.slice(0, 40),
+            }),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`http_${response.status}`);
+        }
+    }
+    catch (error) {
+        if (options.json) {
+            writeLine(options.io.stderr, `Install event telemetry skipped: ${classifyInstallTelemetryError(error)}`);
+        }
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+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";
+}
 function writeExecOutput(io, result, options) {
     if (options.stdout)
         writeRaw(io.stdout, result.stdout);
@@ -537,12 +758,29 @@ function onboardingRootPrompt(io) {
     return {
         confirm: async (message) => yesByDefault(await readLine(io, message)),
         input: (message) => readLine(io, message),
+        message: (message) => writeLine(io.stdout, message),
     };
 }
 function yesByDefault(raw) {
     const answer = raw.trim().split(/\s+/u)[0]?.toLowerCase() ?? "";
     return answer !== "n" && answer !== "no";
 }
+const OTP_CODE_PROMPT = [
+    "Email code needed:",
+    "  Check your latest Cockpit email for a 6- to 10-digit code.",
+    "What you can do:",
+    "  1) Paste the code here.",
+    "  2) No code yet: wait for the resend window, then rerun this command.",
+    "  3) Can't use email: rerun with --no-auth for manual approval.",
+    "Code: ",
+].join("\n");
+const OTP_INVALID_MESSAGE = [
+    "Email code was not accepted:",
+    "  Cockpit expects digits only, length 6 to 10.",
+    "What you can do:",
+    "  1) Rerun and paste the latest email code.",
+    "  2) Use manual approval: cockpit onboard --no-auth --email <you@buildlaunchiterate.ca>",
+].join("\n");
 async function resolveOnboardEmail(command, roots, config, io) {
     if (command.claimedOwnerEmail)
         return command.claimedOwnerEmail;
@@ -576,11 +814,17 @@ async function resolveInteractiveLoginEmail(command, io) {
     return promptOnboardEmail(io);
 }
 async function requestPairingAccessToken(input, io) {
+    return (await requestPairingAccessTokenDetailed(input, io)).accessToken;
+}
+async function requestPairingAccessTokenDetailed(input, io) {
     if (!input.email ||
         input.noAuth ||
         input.json ||
         !isInteractiveStdin(io)) {
-        return undefined;
+        return {
+            status: "skipped",
+            errorCode: authSkippedReason(input, io),
+        };
     }
     try {
         const fetchImpl = io.fetch;
@@ -590,23 +834,43 @@ async function requestPairingAccessToken(input, io) {
             ? start.resend_after_seconds
             : 60;
         writeLine(io.stdout, `Code sent; valid 1h, resend in ${resendAfter}s by rerunning this command.`);
-        const code = (await readLine(io, "Enter the 6-digit code: ")).trim();
-        if (!/^\d{6}$/.test(code)) {
-            throw new Error("OTP code must be 6 digits.");
+        const code = (await readLine(io, OTP_CODE_PROMPT)).trim();
+        if (!/^\d{6,10}$/.test(code)) {
+            throw new Error(OTP_INVALID_MESSAGE);
         }
         const verified = await postOtpVerify(fetchImpl, input.dashboardUrl, input.email, code);
         if (typeof verified.access_token !== "string" || !verified.access_token) {
             throw new Error("OTP verified but dashboard returned no access token.");
         }
         writeLine(io.stdout, `Signed in as ${input.email}.`);
-        return verified.access_token;
+        return { status: "ok", accessToken: verified.access_token };
     }
     catch (error) {
         writeLine(io.stderr, `Auth step skipped: ${errorMessage(error)}`);
         writeLine(io.stderr, "Continuing with manual dashboard approval.");
-        return undefined;
+        return { status: "fail", errorCode: classifyAuthError(error) };
     }
 }
+function authSkippedReason(input, io) {
+    if (!input.email)
+        return "email_missing";
+    if (input.noAuth)
+        return "no_auth";
+    if (input.json)
+        return "json_mode";
+    if (!isInteractiveStdin(io))
+        return "non_interactive";
+    return "auth_skipped";
+}
+function classifyAuthError(error) {
+    const message = errorMessage(error);
+    if (/\b(otp|code|digit|invalid)\b/i.test(message))
+        return "otp_invalid";
+    if (/fetch|network|ENOTFOUND|ECONNREFUSED|HTTP/i.test(message)) {
+        return "network_or_auth";
+    }
+    return "auth_failed";
+}
 async function pairLocalCollectorWithAuthFallback(options, io) {
     try {
         return await pairLocalCollector(options);
@@ -790,6 +1054,18 @@ function backgroundSyncLine(result) {
     return result.status;
 }
 async function runOnboard(command, io) {
+    const installEvents = [];
+    const finish = async (code) => {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl: command.dashboardUrl,
+            command: "onboard",
+            events: installEvents,
+            json: command.json,
+            io,
+        });
+        return code;
+    };
     let install = null;
     let pair = null;
     let sync = null;
@@ -813,6 +1089,7 @@ async function runOnboard(command, io) {
             explicitRoots: command.collectionRoots ?? (command.repoRoot ? [command.repoRoot] : []),
             config: existingConfig,
             interactive,
+            allowHomeRoot: command.allowHomeRoot,
             prompt: interactive ? onboardingRootPrompt(io) : undefined,
         });
         const collectionRoots = rootsResult.roots;
@@ -831,6 +1108,9 @@ async function runOnboard(command, io) {
         if (!command.json) {
             writeLine(io.stdout, `Collecting from: ${collectionRoots.join(", ")}`);
         }
+        if (rootsResult.homeRootOptIn) {
+            addInstallEvent(installEvents, "home_root_optin", "ok");
+        }
         const claimedOwnerEmail = await resolveOnboardEmail(resolvedCommand, collectionRoots, existingConfig, io);
         install = await installLocalCollector({
             homeDir: command.homeDir,
@@ -840,6 +1120,7 @@ async function runOnboard(command, io) {
             dashboardUrl: command.dashboardUrl,
             deviceName: command.deviceName,
         });
+        addInstallEvent(installEvents, "install", "ok");
         if (!command.json) {
             writeLine(io.stdout, "1/5 Installed local collector.");
             writeLine(io.stdout, `Config: ${install.paths.config_file}`);
@@ -852,6 +1133,8 @@ async function runOnboard(command, io) {
         const installedSession = await readOnboardSessionReuseCandidate(command.homeDir);
         const canReuseInstalledSession = canReuseOnboardSession(installedSession, claimedOwnerEmail, command.dashboardUrl);
         if (installedStatus.session_state === "valid" && canReuseInstalledSession) {
+            addInstallEvent(installEvents, "auth", "skipped", "existing_session");
+            addInstallEvent(installEvents, "pair", "skipped", "existing_session");
             if (!command.json) {
                 writeLine(io.stdout, "2/5 Existing valid device session found; pairing skipped.");
             }
@@ -863,12 +1146,13 @@ async function runOnboard(command, io) {
                     writeLine(io.stdout, "2/5 Existing valid device session does not match requested owner or dashboard; pairing again.");
                 }
             }
-            const pairingAccessToken = await requestPairingAccessToken({
+            const authResult = await requestPairingAccessTokenDetailed({
                 dashboardUrl: command.dashboardUrl,
                 email: claimedOwnerEmail,
                 noAuth: command.noAuth,
                 json: command.json,
             }, io);
+            addInstallEvent(installEvents, "auth", authResult.status, authResult.errorCode);
             pair = await pairLocalCollectorWithAuthFallback({
                 homeDir: command.homeDir,
                 dashboardUrl: command.dashboardUrl,
@@ -876,12 +1160,13 @@ async function runOnboard(command, io) {
                 deviceName: command.deviceName,
                 pollIntervalMs: command.pollIntervalMs,
                 timeoutMs: command.timeoutMs,
-                pairingAccessToken,
+                pairingAccessToken: authResult.accessToken,
                 fetch: io.fetch,
                 onPairStarted: command.json
                     ? undefined
                     : (request) => writePairingInstructions(io, request),
             }, io);
+            addInstallEvent(installEvents, "pair", "ok");
             if (!command.json) {
                 writeLine(io.stdout, "2/5 Device paired.");
                 writeLine(io.stdout, `User: ${pair.session.email ?? pair.session.auth_subject_id}`);
@@ -891,9 +1176,13 @@ async function runOnboard(command, io) {
         const worktrees = await discoverCommandWorktrees(collectionRoots, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);
         if (worktrees.length > 1) {
             const multi = await runMultiRepoOnboard(resolvedCommand, io, worktrees);
+            addInstallEvent(installEvents, "work_context", "ok");
+            addInstallEvent(installEvents, "sync", multi.ok ? "ok" : "fail", multi.ok ? undefined : "sync_blocked");
             if (multi.ok) {
                 agentRules = await refreshOnboardAgentRules(resolvedCommand, collectionRoots, io);
+                addInstallEvent(installEvents, "agent_rules", "ok");
                 autostart = await refreshOnboardAutostart(resolvedCommand, collectionRoots, io);
+                addAutostartInstallEvent(installEvents, autostart);
             }
             if (command.json) {
                 writeLine(io.stdout, JSON.stringify({
@@ -919,7 +1208,7 @@ async function runOnboard(command, io) {
                     backfillHint,
                 });
             }
-            return multi.ok ? 0 : 1;
+            return finish(multi.ok ? 0 : 1);
         }
         const worktreeRoot = worktrees[0]?.repo_root ?? primaryRoot;
         const context = await startLocalWorkContext({
@@ -935,6 +1224,7 @@ async function runOnboard(command, io) {
             writeLine(io.stdout, `Ticket: ${context.active_ticket_id ?? "general ambient"}`);
             writeLine(io.stdout, `Context: ${context.work_context_id}`);
         }
+        addInstallEvent(installEvents, "work_context", "ok");
         const run = await runAttributedWorktreeSync({
             homeDir: command.homeDir,
             dashboardUrl: command.dashboardUrl,
@@ -952,6 +1242,7 @@ async function runOnboard(command, io) {
             branch: command.branch,
         });
         if (sync.status !== "uploaded") {
+            addInstallEvent(installEvents, "sync", "fail", "sync_blocked");
             if (command.json) {
                 writeLine(io.stdout, JSON.stringify({
                     ...onboardResult("blocked", resolvedCommand, install, pair, sync, status),
@@ -965,11 +1256,14 @@ async function runOnboard(command, io) {
                 writeLine(io.stderr, `Failure: ${sync.failure_reason}`);
                 writeLine(io.stderr, `Retry: ${sync.retry_command}`);
             }
-            return 1;
+            return finish(1);
         }
+        addInstallEvent(installEvents, "sync", "ok");
         if (command.json) {
             agentRules = await refreshOnboardAgentRules(resolvedCommand, collectionRoots, io);
+            addInstallEvent(installEvents, "agent_rules", "ok");
             autostart = await refreshOnboardAutostart(resolvedCommand, collectionRoots, io);
+            addAutostartInstallEvent(installEvents, autostart);
             writeLine(io.stdout, JSON.stringify({
                 ...onboardResult("pass", resolvedCommand, install, pair, sync, status),
                 collection_roots: collectionRoots,
@@ -979,7 +1273,7 @@ async function runOnboard(command, io) {
                 backfill_hint: backfillHint,
                 codex_sessions: run.summary,
             }, null, 2));
-            return 0;
+            return finish(0);
         }
         writeLine(io.stdout, "4/5 Ambient metadata uploaded.");
         writeLine(io.stdout, `HTTP: ${sync.http_status}`);
@@ -994,7 +1288,9 @@ async function runOnboard(command, io) {
         writeLine(io.stdout, "PASS: Cockpit collector is ready for harvest.");
         writeLine(io.stdout, `Open: ${command.dashboardUrl}/my-work`);
         agentRules = await refreshOnboardAgentRules(resolvedCommand, collectionRoots, io);
+        addInstallEvent(installEvents, "agent_rules", "ok");
         autostart = await refreshOnboardAutostart(resolvedCommand, collectionRoots, io);
+        addAutostartInstallEvent(installEvents, autostart);
         writeOnboardLiveStatus(io, resolvedCommand, collectionRoots, {
             pair,
             status,
@@ -1004,7 +1300,7 @@ async function runOnboard(command, io) {
             initialSyncOk: true,
             backfillHint,
         });
-        return 0;
+        return finish(0);
     }
     catch (error) {
         const message = errorMessage(error);
@@ -1017,7 +1313,8 @@ async function runOnboard(command, io) {
             }).catch(() => null)
             : null;
         const blocker = classifyOnboardBlocker(message);
-        const nextStep = nextStepForOnboardBlocker(blocker);
+        addOnboardFailureEvent(installEvents, blocker);
+        const nextStep = nextStepForOnboardBlocker(blocker, command);
         if (command.json) {
             writeLine(io.stdout, JSON.stringify({
                 ...onboardResult("blocked", command, install, pair, sync, status),
@@ -1032,7 +1329,7 @@ async function runOnboard(command, io) {
             writeLine(io.stderr, `BLOCKED: ${message}`);
             writeLine(io.stderr, `Next: ${nextStep}`);
         }
-        return 1;
+        return finish(1);
     }
 }
 function canReuseOnboardSession(session, claimedOwnerEmail, dashboardUrl) {
@@ -1317,10 +1614,10 @@ function classifyOnboardBlocker(message) {
         return "ticket_binding";
     return "unknown";
 }
-function nextStepForOnboardBlocker(blocker) {
+function nextStepForOnboardBlocker(blocker, options = {}) {
     switch (blocker) {
         case COLLECTION_ROOT_REQUIRED:
-            return "Run `cockpit onboard --workspace <path>` or rerun in a terminal and confirm the collection root.";
+            return missingCollectionRootMessage(options);
         case "ticket":
         case "ticket_binding":
             return "Run `cockpit start --ticket <id>` when actual ticket work begins, then run `cockpit sync`.";
@@ -1435,6 +1732,7 @@ async function runSyncLocked(command, io) {
     });
     if (worktrees.length > 1) {
         const rows = run.outcomes.map((outcome) => worktreeSyncRow(outcome, run));
+        const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
         if (command.json) {
             writeLine(io.stdout, JSON.stringify({
                 mode: "multi_repo",
@@ -1442,6 +1740,7 @@ async function runSyncLocked(command, io) {
                 results: run.outcomes.map((outcome) => outcome.sync),
                 repos: rows,
                 codex_sessions: run.summary,
+                raw_evidence_gc: gc,
             }, null, 2));
             return run.ok ? 0 : 1;
         }
@@ -1453,14 +1752,17 @@ async function runSyncLocked(command, io) {
             writeLine(uploaded ? io.stdout : io.stderr, `- ${worktree.repo_label}/${worktree.worktree_label} (${worktree.branch}) head:${shortSha(sync.head_sha ?? worktree.head_sha)} ${sync.status} objects:${sync.raw_evidence_uploaded_object_count} chunks:${sync.raw_evidence_uploaded_chunk_count} reused:${sync.raw_evidence_reused_count} failed:${sync.raw_evidence_failed_count} cursor:${sync.cursor_tracked_object_count}${failureSuffix}`);
         }
         writeAgentSessionSummary(io, run.summary);
+        if (gc && !gc.skipped)
+            writeLine(io.stdout, rawEvidenceGcSummary(gc));
         return run.ok ? 0 : 1;
     }
     const result = run.outcomes[0]?.sync;
     if (!result) {
         throw new Error("Sync produced no result for the repo worktree.");
     }
+    const gc = result.status === "uploaded" ? await runSyncRawEvidenceGc(command, io) : null;
     if (command.json) {
-        writeLine(io.stdout, JSON.stringify({ ...result, codex_sessions: run.summary }, null, 2));
+        writeLine(io.stdout, JSON.stringify({ ...result, codex_sessions: run.summary, raw_evidence_gc: gc }, null, 2));
         return result.status === "uploaded" ? 0 : 1;
     }
     if (result.status === "uploaded") {
@@ -1474,6 +1776,8 @@ async function runSyncLocked(command, io) {
         writeLine(io.stdout, rawEvidenceSyncLine(result));
         writeAgentSessionSummary(io, run.summary);
         writeLine(io.stdout, cursorStatusLine(result));
+        if (gc && !gc.skipped)
+            writeLine(io.stdout, rawEvidenceGcSummary(gc));
         return 0;
     }
     writeLine(io.stderr, "Cockpit ambient upload failed; safe retry metadata was spooled.");
@@ -1482,6 +1786,9 @@ async function runSyncLocked(command, io) {
     writeLine(io.stderr, `Retry: ${result.retry_command}`);
     return 1;
 }
+async function runSyncRawEvidenceGc(command, io) {
+    return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
+}
 async function runStatus(command, io) {
     const backfillCursor = await inspectBackfillCursor(command.homeDir);
     const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);