@bli-cockpit/cli 0.2.4 → 0.2.5

package/README.md

@@ -160,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.
 
@@ -180,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.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",
@@ -671,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" ||
@@ -678,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) {
@@ -1742,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) {
@@ -1775,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({
@@ -2015,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.4",
+  "version": "0.2.5",
   "private": false,
   "type": "module",
   "bin": {