@bli-cockpit/cli 0.2.3 → 0.2.5

package/README.md

@@ -54,6 +54,7 @@ On a blank Mac, `npm i -g @bli-cockpit/cli && cockpit do-everything` is enough t
 | `cockpit status` | Prints install / sign-in / capture / upload health in one screen. | The "is it working?" command. Run it whenever you're unsure. |
 | `cockpit backfill --all` | Uploads your HISTORICAL Codex + Claude sessions (from before Cockpit existed on this Mac). | One-time catch-up so your past work counts too. "Backfill" = fill in the back-catalog. |
 | `cockpit sync` | Captures and uploads once, right now. This is what the background agent runs every 15 min — you almost never type it yourself. | Named for what it does: synchronize local session files up to the dashboard. |
+| `cockpit analyze` | Runs a fresh sync, then queues batch analysis of your latest uploaded sessions. It returns immediately; status and results appear in My Work. | One command when you want newly finished work uploaded and judged now. |
 | `cockpit start --ticket <id>` | Tags your CURRENT work with a Linear ticket so sessions attribute to it. `--clear-ticket` returns to general capture. | "Start (working on) X." Agents usually run this for you per the agent rules. |
 | `cockpit login` / `cockpit pair` | Just the sign-in + device-registration step, standalone (onboard already includes it). Two names, one command: `login` is what humans guess, `pair` is what the dashboard's device screen calls it. | Recovery path when a session expires or you switch accounts. |
 | `cockpit logout` | Deletes this machine's session. | The undo of login. |
@@ -93,6 +94,23 @@ cockpit onboard --no-auth
 
 `cockpit update` installs the latest public CLI and reruns onboarding checks against saved roots. `cockpit upgrade` is the same command.
 
+## Analyze latest work
+
+```bash
+cockpit analyze --workspace "$PWD"
+```
+
+`cockpit analyze` first performs the same durable upload as `cockpit sync`. It
+queues the analysis only after that upload succeeds, then exits without waiting
+for the Fireworks batch. Use `--json` for a single machine-readable object that
+contains both the sync receipt and queued job status. The dashboard button
+analyzes the latest upload already stored by the background collector; run the
+CLI command when the work ended too recently for the 15-minute background sync.
+Each person can queue analysis once every three hours, subject to the team's
+shared `$2` UTC-day judge cap. Completion can take several minutes plus the wait
+for the next 15-minute collector poll; My Work shows queued, running, done, or
+failed status while you wait.
+
 ## Parent Mode
 
 Use a parent folder such as `~/BLI` when it contains multiple repos. Cockpit scans child git repos/worktrees, creates one stable work context per worktree, and rolls them up under repo rows in the dashboard.
@@ -142,6 +160,9 @@ Local files:
 - `~/.config/bli-cockpit/config.json`: dashboard URL, device label, collection roots.
 - `~/.config/bli-cockpit/session.json`: paired device token and owner metadata.
 - `~/.local/state/bli-cockpit/spool/`: safe retry records.
+- `~/.local/state/bli-cockpit/spool/install-events/`: private atomic collector
+  health receipts waiting for authenticated delivery. Receipts contain only
+  sanitized operation metadata, never command output or transcript content.
 - `~/.local/state/bli-cockpit/cursors/`: upload/backfill cursors, no raw content.
 - `.codex-autorunner/contextspace/active_context.md`: current work context inside a repo.
 
@@ -162,6 +183,11 @@ cockpit status --workspace "$PWD" --json
 cockpit sync --workspace "$PWD" --json
 ```
 
+`status --json` includes `pending_health_receipt_count`,
+`oldest_pending_health_receipt_at`, and
+`last_health_receipt_failure_reason`. A nonzero count means Cockpit preserved a
+collector failure locally and will replay it on the next authenticated run.
+
 If `cockpit update` fails with npm `EACCES`, fix Homebrew global-package ownership once:
 
 ```bash

package/dist/commands/local-args.js

@@ -29,6 +29,8 @@ export function parseLocalArgs(argv) {
             return parseStartArgs(argv.slice(1));
         case "sync":
             return parseSyncArgs(argv.slice(1));
+        case "analyze":
+            return parseAnalyzeArgs(argv.slice(1));
         case "backfill":
             return parseBackfillArgs(argv.slice(1));
         case "status":
@@ -302,6 +304,12 @@ function parseStartArgs(args) {
     };
 }
 function parseSyncArgs(args) {
+    return parseSyncLikeArgs(args, "sync");
+}
+function parseAnalyzeArgs(args) {
+    return parseSyncLikeArgs(args, "analyze");
+}
+function parseSyncLikeArgs(args, command) {
     const values = parseNamedArgs(args, {
         allowedFlags: [
             "--home",
@@ -321,9 +329,9 @@ function parseSyncArgs(args) {
             "--max-repos",
         ],
     });
-    assertNoPositionals(values.positionals, "sync");
+    assertNoPositionals(values.positionals, command);
     return {
-        kind: "sync",
+        kind: command,
         homeDir: optionalNonEmpty(values.flags.get("--home")),
         repoRoot: optionalNonEmpty(workRootFlagValue(values)),
         dashboardUrl: optionalUrl(values.flags.get("--dashboard-url")),

package/dist/commands/local.js

@@ -18,6 +18,7 @@ import { discoverGitWorktrees } from "../repo-identity.js";
 import { runAttributedWorktreeSync, } from "./session-sync.js";
 import { COLLECTION_ROOT_REQUIRED, missingCollectionRootMessage, normalizeRootsDetailed, resolveOnboardingRoots, rootRejectionExplanation, } from "../onboarding-roots.js";
 import { rawEvidenceGcSummary, runRawEvidenceLocalGc, } from "../raw-evidence-gc.js";
+import { enqueueInstallEventEntry, readPendingInstallEventEntries, recordInstallEventAttemptFailure, removeInstallEventEntry, } from "../spool/install-event-outbox.js";
 export const rootCommandNames = new Set([
     "onboard",
     "update",
@@ -30,6 +31,7 @@ export const rootCommandNames = new Set([
     "logout",
     "start",
     "sync",
+    "analyze",
     "backfill",
     "status",
     "sessions",
@@ -76,6 +78,8 @@ export async function runLocalCockpitCli(argv, io = defaultIo()) {
                 return await runStart(command, io);
             case "sync":
                 return await runSync(command, io);
+            case "analyze":
+                return await runAnalyze(command, io);
             case "backfill":
                 return await runBackfillCommand(command, io);
             case "status":
@@ -112,6 +116,7 @@ export function localCommandHelp(command) {
         "  cockpit logout",
         "  cockpit start [--ticket <id>|--clear-ticket] [--topic <label>] [--intent <intent>] [--phase <phase>] [--workspace <path>] [--branch <name>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sync [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
+        "  cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit backfill (--since-days <n>|--all) [--source codex|claude] [--dry-run] [--max-files <n>] [--yes] [--workspace <path>] [--json]",
         "  cockpit status [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
         "  cockpit sessions [--source codex|claude] [--since-days <n>|--all] [--workspace <path>] [--max-depth <n>] [--max-repos <n>] [--json]",
@@ -236,6 +241,17 @@ function localSubcommandHelp(command) {
                 "--max-depth and --max-repos.",
             ],
         ],
+        [
+            "analyze",
+            [
+                "Usage: cockpit analyze [--workspace <path>] [--dashboard-url <url>] [--json]",
+                "",
+                "Uploads the latest local ambient evidence, then queues one analysis job.",
+                "The command returns after the batch is queued; view status and results in My Work.",
+                "Omit --dashboard-url for production; pass it only for staging/custom dashboards.",
+                "`--repo <path>` remains supported as a backward-compatible alias.",
+            ],
+        ],
         [
             "backfill",
             [
@@ -656,6 +672,28 @@ export async function reportInstallEventsBestEffort(options) {
     if (options.events.length === 0)
         return;
     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) }
+                    : {}),
+                ...(event.at ? { at: event.at } : {}),
+            })),
+        });
+    }
+    catch {
+        if (options.json) {
+            writeLine(options.io.stderr, "Install event outbox unavailable: local_write_failed");
+        }
+        return;
+    }
     const session = await readLocalCollectorSessionFile(paths).catch(() => null);
     if (!session ||
         session.session_state !== "valid" ||
@@ -663,34 +701,47 @@ export async function reportInstallEventsBestEffort(options) {
         !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)}`);
-        }
+    const pending = (await readPendingInstallEventEntries(paths)).slice(0, 20);
+    const failures = [];
+    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}`);
+                }
+                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);
+            }
+        }));
     }
-    finally {
-        clearTimeout(timeout);
+    if (options.json && failures.length > 0) {
+        writeLine(options.io.stderr, `Install event telemetry queued for retry: ${[...new Set(failures)].join(",")}`);
     }
 }
 function classifyInstallTelemetryError(error) {
@@ -1727,6 +1778,54 @@ async function runStart(command, io) {
     return 0;
 }
 async function runSync(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
+    await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [{ step: "sync_started", status: "ok" }],
+        json: command.json,
+        io,
+    });
+    try {
+        const code = await runSyncWithHealthReceipt(command, io);
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl,
+            command: "sync",
+            events: [
+                {
+                    step: "sync_complete",
+                    status: code === 0 ? "ok" : "fail",
+                    ...(code === 0 ? {} : { error_code: "sync_failed" }),
+                },
+            ],
+            json: command.json,
+            io,
+        });
+        return code;
+    }
+    catch (error) {
+        await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl,
+            command: "sync",
+            events: [
+                {
+                    step: "sync_complete",
+                    status: "fail",
+                    error_code: classifySyncHealthError(error),
+                },
+            ],
+            json: command.json,
+            io,
+        });
+        throw error;
+    }
+}
+async function runSyncWithHealthReceipt(command, io) {
     const backfillLock = await inspectBackfillLock(getCollectorRuntimePaths(command.homeDir));
     if (backfillLock.held) {
         if (command.json) {
@@ -1760,6 +1859,19 @@ async function runSync(command, io) {
         await lock.handle.release();
     }
 }
+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";
+    }
+    if (/collection.root|workspace|repo|worktree/iu.test(message)) {
+        return "collection_root_failed";
+    }
+    return "sync_failed";
+}
 async function runSyncLocked(command, io) {
     const worktrees = await discoverCommandWorktrees(command.repoRoot, { maxDepth: command.maxDepth, maxRepos: command.maxRepos }, io);
     const run = await runAttributedWorktreeSync({
@@ -1825,6 +1937,137 @@ async function runSyncLocked(command, io) {
     writeLine(io.stderr, `Retry: ${result.retry_command}`);
     return 1;
 }
+async function runAnalyze(command, io) {
+    const syncStdout = [];
+    const syncStderr = [];
+    const syncIo = {
+        ...io,
+        stdout: bufferedWritable(syncStdout),
+        stderr: bufferedWritable(syncStderr),
+    };
+    const syncCommand = {
+        ...command,
+        kind: "sync",
+        json: true,
+    };
+    const syncExitCode = await runSync(syncCommand, syncIo);
+    const syncOutput = parseCapturedJson(syncStdout);
+    if (syncExitCode !== 0 || !isUploadedSyncResult(syncOutput)) {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: syncExitCode === 0 ? "sync_not_completed" : "sync_failed",
+                sync: syncOutput,
+                error: syncStderr.join("").trim()
+                    || (syncExitCode === 0
+                        ? "Cockpit sync did not upload fresh evidence."
+                        : "Cockpit sync failed."),
+            }, null, 2));
+        }
+        else {
+            replayCaptured(io.stderr, syncStderr);
+            writeLine(io.stderr, syncExitCode === 0
+                ? "Analysis was not queued because a fresh upload did not complete."
+                : "Analysis was not queued because the latest upload failed.");
+        }
+        return syncExitCode === 0 ? 1 : syncExitCode;
+    }
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const session = await readLocalCollectorSessionFile(paths).catch(() => {
+        throw new Error("Cockpit is not signed in. Run `cockpit onboard` or `cockpit login` first.");
+    });
+    const dashboardUrl = normalizeUrl(command.dashboardUrl ?? session.dashboard_url ?? DEFAULT_DASHBOARD_URL);
+    const response = await io.fetch(`${dashboardUrl}/api/ambient/analyze`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${session.device_token}`,
+            "content-type": "application/json",
+        },
+        body: "{}",
+    });
+    const body = await readAnalyzeApiResponse(response);
+    if (!response.ok) {
+        const message = typeof body.message === "string"
+            ? body.message
+            : `Analysis request failed with HTTP ${response.status}.`;
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: "analyze_failed",
+                sync: syncOutput,
+                http_status: response.status,
+                code: typeof body.code === "string" ? body.code : null,
+                message,
+                retry_after_seconds: typeof body.retry_after_seconds === "number"
+                    ? body.retry_after_seconds
+                    : null,
+            }, null, 2));
+        }
+        else {
+            replayCaptured(io.stderr, syncStderr);
+            writeLine(io.stderr, `Analysis was not queued: ${message}`);
+        }
+        return 1;
+    }
+    const jobId = typeof body.job?.id === "string" ? body.job.id : null;
+    const jobStatus = typeof body.job?.status === "string" ? body.job.status : "pending";
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "queued",
+            sync: syncOutput,
+            job: body.job ?? null,
+            dashboard_url: `${dashboardUrl}/my-work`,
+        }, null, 2));
+        return 0;
+    }
+    replayCaptured(io.stderr, syncStderr);
+    writeLine(io.stdout, "Cockpit latest evidence uploaded.");
+    writeLine(io.stdout, "Cockpit analysis queued.");
+    if (jobId)
+        writeLine(io.stdout, `Job: ${jobId}`);
+    writeLine(io.stdout, `Status: ${jobStatus === "pending" ? "queued" : jobStatus}`);
+    writeLine(io.stdout, `Results: ${dashboardUrl}/my-work`);
+    return 0;
+}
+async function readAnalyzeApiResponse(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+function parseCapturedJson(chunks) {
+    const text = chunks.join("").trim();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isUploadedSyncResult(value) {
+    return Boolean(value
+        && typeof value === "object"
+        && !Array.isArray(value)
+        && value["status"] === "uploaded");
+}
+function bufferedWritable(chunks) {
+    return {
+        write(chunk) {
+            chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+            return true;
+        },
+    };
+}
+function replayCaptured(stream, chunks) {
+    for (const chunk of chunks)
+        stream.write(chunk);
+}
 async function runSyncRawEvidenceGc(command, io) {
     return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
 }
@@ -1869,6 +2112,8 @@ async function runStatus(command, io) {
     writeLine(io.stdout, `last_upload_success: ${status.last_upload_success_at ?? "never"}`);
     writeLine(io.stdout, `last_upload_failure: ${status.last_upload_failure_reason ?? "none"}`);
     writeLine(io.stdout, `pending_uploads: ${status.pending_upload_count}`);
+    writeLine(io.stdout, `pending_health_receipts: ${status.pending_health_receipt_count}`);
+    writeLine(io.stdout, `last_health_receipt_failure: ${status.last_health_receipt_failure_reason ?? "none"}`);
     writeLine(io.stdout, `backfill: ${backfillCursorLine(backfillCursor)}`);
     for (const detail of status.details)
         writeLine(io.stdout, `- ${detail}`);

package/dist/local-state.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { resolveRepoWorktreeIdentity, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
 import { normalizeCollectionRoots } from "./root-normalization.js";
 import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
+import { summarizeInstallEventOutbox } from "./spool/install-event-outbox.js";
 const localCollectorPackage = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 export const LOCAL_COLLECTOR_VERSION = typeof localCollectorPackage.version === "string"
     ? localCollectorPackage.version
@@ -237,7 +238,10 @@ export async function inspectLocalCollectorStatus(options = {}) {
     const identity = await resolveIdentityOrFallback(repoRoot, options.branch);
     const context = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => null);
     const branch = options.branch ?? identity.branch;
-    const uploadSpool = await summarizeLocalUploadSpool(paths);
+    const [uploadSpool, healthOutbox] = await Promise.all([
+        summarizeLocalUploadSpool(paths),
+        summarizeInstallEventOutbox(paths),
+    ]);
     const freshness = classifyCollectorFreshness(context, uploadSpool.last_upload_success_at, now);
     const uploadState = !config
         ? "not_installed"
@@ -268,6 +272,9 @@ export async function inspectLocalCollectorStatus(options = {}) {
     if (uploadSpool.pending_upload_count > 0) {
         details.push(`Upload retry pending: ${uploadSpool.pending_upload_count} safe metadata record(s) spooled. Run \`${uploadSpool.retry_command ?? "cockpit sync"}\` to retry.`);
     }
+    if (healthOutbox.pending_count > 0) {
+        details.push(`Collector health retry pending: ${healthOutbox.pending_count} sanitized receipt(s) queued since ${healthOutbox.oldest_created_at ?? "unknown"}.`);
+    }
     return {
         installed: Boolean(config),
         config_file: paths.config_file,
@@ -293,6 +300,9 @@ export async function inspectLocalCollectorStatus(options = {}) {
         last_upload_failure_reason: uploadSpool.last_upload_failure_reason,
         pending_upload_count: uploadSpool.pending_upload_count,
         upload_retry_command: uploadSpool.retry_command,
+        pending_health_receipt_count: healthOutbox.pending_count,
+        oldest_pending_health_receipt_at: healthOutbox.oldest_created_at,
+        last_health_receipt_failure_reason: healthOutbox.last_failure_reason,
         details,
     };
 }

package/dist/spool/install-event-outbox.js

@@ -0,0 +1,191 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+const OUTBOX_DIRECTORY = "install-events";
+const MAX_PENDING_ENTRIES = 100;
+const MAX_EVENTS_PER_ENTRY = 40;
+export async function enqueueInstallEventEntry(paths, options) {
+    if (options.events.length === 0)
+        return null;
+    const createdAt = (options.now ?? new Date()).toISOString();
+    const entry = {
+        schema_version: "cockpit-install-event-outbox.v1",
+        outbox_id: `install-event-${crypto.randomUUID()}`,
+        created_at: createdAt,
+        last_attempt_at: null,
+        retry_count: 0,
+        last_failure_reason: null,
+        dashboard_url: options.dashboardUrl,
+        cli_version: options.cliVersion,
+        command: options.command,
+        os_platform: options.osPlatform,
+        events: options.events.slice(0, MAX_EVENTS_PER_ENTRY).map((event) => ({
+            step: event.step,
+            status: event.status,
+            ...(event.error_code ? { error_code: event.error_code } : {}),
+            at: event.at ?? createdAt,
+        })),
+    };
+    await writeEntry(paths, entry);
+    await pruneInstallEventOutbox(paths);
+    return entry;
+}
+export async function readPendingInstallEventEntries(paths) {
+    const directory = installEventOutboxDirectory(paths);
+    const names = await fs.readdir(directory).catch(() => []);
+    const entries = [];
+    for (const name of names.filter((candidate) => candidate.endsWith(".json"))) {
+        const filePath = path.join(directory, name);
+        try {
+            const parsed = parseEntry(JSON.parse(await fs.readFile(filePath, "utf8")));
+            if (!parsed) {
+                await fs.rm(filePath, { force: true });
+                continue;
+            }
+            entries.push(parsed);
+        }
+        catch {
+            await fs.rm(filePath, { force: true }).catch(() => undefined);
+        }
+    }
+    return entries.sort((left, right) => Date.parse(left.created_at) - Date.parse(right.created_at) ||
+        left.outbox_id.localeCompare(right.outbox_id));
+}
+export async function summarizeInstallEventOutbox(paths) {
+    const entries = await readPendingInstallEventEntries(paths);
+    const attempted = entries
+        .filter((entry) => entry.last_attempt_at)
+        .sort((left, right) => Date.parse(right.last_attempt_at) - Date.parse(left.last_attempt_at))[0];
+    return {
+        pending_count: entries.length,
+        oldest_created_at: entries[0]?.created_at ?? null,
+        last_attempt_at: attempted?.last_attempt_at ?? null,
+        last_failure_reason: attempted?.last_failure_reason ?? null,
+    };
+}
+export async function recordInstallEventAttemptFailure(paths, entry, options) {
+    await writeEntry(paths, {
+        ...entry,
+        last_attempt_at: options.attemptedAt,
+        retry_count: entry.retry_count + 1,
+        last_failure_reason: options.failureReason,
+    });
+}
+export async function removeInstallEventEntry(paths, outboxId) {
+    await fs.rm(entryPath(paths, outboxId), { force: true });
+}
+export function installEventOutboxDirectory(paths) {
+    return path.join(paths.spool_dir, OUTBOX_DIRECTORY);
+}
+async function pruneInstallEventOutbox(paths) {
+    const entries = await readPendingInstallEventEntries(paths);
+    const excess = entries.slice(0, Math.max(0, entries.length - MAX_PENDING_ENTRIES));
+    await Promise.all(excess.map((entry) => removeInstallEventEntry(paths, entry.outbox_id)));
+}
+async function writeEntry(paths, entry) {
+    const directory = installEventOutboxDirectory(paths);
+    const filePath = entryPath(paths, entry.outbox_id);
+    const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomUUID()}`;
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        await fs.chmod(directory, 0o700).catch(() => undefined);
+    }
+    try {
+        await fs.writeFile(tempPath, `${JSON.stringify(entry, null, 2)}\n`, {
+            mode: 0o600,
+            flag: "wx",
+        });
+        await fs.rename(tempPath, filePath);
+        if (process.platform !== "win32") {
+            await fs.chmod(filePath, 0o600).catch(() => undefined);
+        }
+    }
+    finally {
+        await fs.rm(tempPath, { force: true }).catch(() => undefined);
+    }
+}
+function entryPath(paths, outboxId) {
+    return path.join(installEventOutboxDirectory(paths), `${safeOutboxId(outboxId)}.json`);
+}
+function safeOutboxId(value) {
+    return value.replace(/[^a-z0-9_-]/giu, "").slice(0, 120);
+}
+function parseEntry(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const command = installEventCommand(record["command"]);
+    const events = Array.isArray(record["events"])
+        ? record["events"].map(parseEvent).filter(isPresent)
+        : [];
+    if (record["schema_version"] !== "cockpit-install-event-outbox.v1" ||
+        !stringValue(record["outbox_id"]) ||
+        !stringValue(record["created_at"]) ||
+        !stringValue(record["dashboard_url"]) ||
+        !stringValue(record["cli_version"]) ||
+        !stringValue(record["os_platform"]) ||
+        !command ||
+        events.length === 0) {
+        return null;
+    }
+    return {
+        schema_version: "cockpit-install-event-outbox.v1",
+        outbox_id: stringValue(record["outbox_id"]),
+        created_at: stringValue(record["created_at"]),
+        last_attempt_at: stringValue(record["last_attempt_at"]),
+        retry_count: finiteNumber(record["retry_count"]),
+        last_failure_reason: stringValue(record["last_failure_reason"]),
+        dashboard_url: stringValue(record["dashboard_url"]),
+        cli_version: stringValue(record["cli_version"]),
+        command,
+        os_platform: stringValue(record["os_platform"]),
+        events: events.slice(0, MAX_EVENTS_PER_ENTRY),
+    };
+}
+function parseEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    const step = stringValue(record["step"]);
+    const status = installEventStatus(record["status"]);
+    const at = stringValue(record["at"]);
+    if (!step || !status || !at)
+        return null;
+    return {
+        step,
+        status,
+        ...(stringValue(record["error_code"])
+            ? { error_code: stringValue(record["error_code"]) }
+            : {}),
+        at,
+    };
+}
+function installEventCommand(value) {
+    return [
+        "onboard",
+        "update",
+        "install",
+        "login",
+        "sync",
+        "backfill",
+        "doctor",
+    ].includes(String(value))
+        ? value
+        : null;
+}
+function installEventStatus(value) {
+    return value === "ok" || value === "fail" || value === "skipped"
+        ? value
+        : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value : null;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : 0;
+}
+function isPresent(value) {
+    return value !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/cli",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "private": false,
   "type": "module",
   "bin": {