@bli-cockpit/cli 0.2.48 → 0.2.50

package/dist/local-state-identity.js

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { repoFingerprintFromLocalRoot, resolveRepoWorktreeIdentity, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+/**
+ * A folder that is not a git repo is a legitimate workspace under the
+ * session-first commandment, so this always answers with an identity: git's
+ * own when there is one, a path-derived one otherwise. Nothing may be withheld
+ * for lack of a repo.
+ */
+export async function resolveIdentityOrFallback(repoRoot, branchOverride) {
+    const resolvedRoot = await stableWorktreeRoot(repoRoot);
+    const identity = await resolveRepoWorktreeIdentity(resolvedRoot).catch(() => null);
+    if (identity) {
+        return branchOverride ? { ...identity, branch: branchOverride } : identity;
+    }
+    const repoLabel = path.basename(resolvedRoot) || "workspace";
+    const repoFingerprint = repoFingerprintFromLocalRoot(resolvedRoot);
+    const worktreeFingerprint = stableWorktreeFingerprint(resolvedRoot);
+    const branch = branchOverride ?? (await resolveGitBranch(resolvedRoot));
+    return {
+        requested_path: resolvedRoot,
+        repo_root: resolvedRoot,
+        repo_label: repoLabel,
+        repo_fingerprint: repoFingerprint,
+        repo_origin_url: null,
+        branch,
+        head_sha: null,
+        worktree_label: repoLabel,
+        worktree_fingerprint: worktreeFingerprint,
+        worktree_is_primary: true,
+    };
+}
+/**
+ * Reads HEAD directly rather than shelling out to git, because this runs on
+ * every sync tick on machines where a spawned process is the expensive part.
+ */
+export async function resolveGitBranch(repoRoot) {
+    try {
+        const gitPath = path.join(repoRoot, ".git");
+        const stat = await fs.stat(gitPath);
+        const headPath = stat.isFile()
+            ? path.join(await resolveWorktreeGitDir(gitPath), "HEAD")
+            : path.join(gitPath, "HEAD");
+        const head = (await fs.readFile(headPath, "utf8")).trim();
+        if (head.startsWith("ref: refs/heads/")) {
+            return head.slice("ref: refs/heads/".length);
+        }
+        return head ? `detached:${head.slice(0, 12)}` : "unknown";
+    }
+    catch (error) {
+        // A folder that is not a git repo is a legitimate workspace under the
+        // session-first commandment, so a missing `.git` stays quiet. A `.git`
+        // that exists and cannot be read is a different thing: every session
+        // collected from this repo gets branch `unknown` and nothing says why.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] could not read HEAD, branch recorded as unknown", JSON.stringify({
+                reason: "git_head_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return "unknown";
+    }
+}
+/** A linked worktree's `.git` is a file pointing elsewhere, so HEAD is not where it looks. */
+async function resolveWorktreeGitDir(gitFile) {
+    const raw = await fs.readFile(gitFile, "utf8");
+    const match = raw.match(/^gitdir:\s*(.+)$/m);
+    if (!match)
+        return path.dirname(gitFile);
+    const gitDir = match[1].trim();
+    return path.isAbsolute(gitDir) ? gitDir : path.resolve(path.dirname(gitFile), gitDir);
+}

package/dist/local-state-pairing.js

@@ -0,0 +1,263 @@
+import { LocalCollectorSessionFileSchema, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+import { serverFailureDetail } from "./upload-http.js";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { isMissingFileError, writeJsonFile } from "./local-state-files.js";
+import { defaultDeviceName, LOCAL_COLLECTOR_VERSION, normalizeDashboardUrl, normalizeDeviceName, normalizeOptionalEmail, readLocalCollectorConfig, } from "./local-state-config.js";
+import { toSessionReference } from "./local-state-session.js";
+/**
+ * `cockpit login` — the whole device-pairing handshake, because a machine can
+ * collect locally without it but can never upload until the dashboard has
+ * approved this device.
+ */
+export async function pairLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const config = await readConfigOrRefusePairing(paths);
+    const dashboardUrl = normalizeDashboardUrl(options.dashboardUrl ?? config.dashboard_url);
+    const device = resolvePairingDeviceIdentity(config, options);
+    await recordDeviceIdentityWhenChanged(paths, config, device);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) {
+        throw new Error("global fetch is unavailable; use Node.js 20 or newer.");
+    }
+    const startResponse = await postPairStart(fetchImpl, dashboardUrl, {
+        device_id: device.deviceId,
+        device_name: device.deviceName,
+        claimed_owner_email: device.claimedOwnerEmail,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+    }, options.pairingAccessToken);
+    options.onPairStarted?.(startResponse);
+    const sessionFile = await pollPairRequest(fetchImpl, dashboardUrl, {
+        paths,
+        startResponse,
+        pollIntervalMs: options.pollIntervalMs,
+        timeoutMs: options.timeoutMs,
+        sleep: options.sleep,
+    });
+    return {
+        status: "paired",
+        session: toSessionReference(sessionFile),
+        session_file: paths.session_file,
+        dashboard_url: dashboardUrl,
+        approve_url: startResponse.approve_url,
+    };
+}
+async function readConfigOrRefusePairing(paths) {
+    return readLocalCollectorConfig(paths).catch((error) => {
+        // "Local config missing" is correct when it is absent. A config that
+        // exists and will not parse gets the same sentence and the same useless
+        // advice — run onboard again, which will not fix it (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] collector config present but unreadable, reporting it as missing", JSON.stringify({
+                reason: "config_unreadable",
+                ...describeError(error),
+            }));
+        }
+        throw new Error("Local config missing. Run `cockpit onboard` (or `cockpit install`) first, then retry `cockpit login`.");
+    });
+}
+function resolvePairingDeviceIdentity(config, options) {
+    return {
+        deviceId: config.device_id ?? `device-${crypto.randomUUID()}`,
+        deviceName: normalizeDeviceName(options.deviceName) ??
+            config.device_name ??
+            defaultDeviceName(),
+        claimedOwnerEmail: normalizeOptionalEmail(options.claimedOwnerEmail) ??
+            config.claimed_owner_email,
+    };
+}
+/**
+ * The dashboard will approve the identity this request claims, so the config
+ * has to be holding that same identity before the request goes out.
+ */
+async function recordDeviceIdentityWhenChanged(paths, config, device) {
+    if (!config.device_id ||
+        config.device_name !== device.deviceName ||
+        (device.claimedOwnerEmail &&
+            config.claimed_owner_email !== device.claimedOwnerEmail)) {
+        await writeJsonFile(paths.config_file, {
+            ...config,
+            device_id: device.deviceId,
+            device_name: device.deviceName,
+            claimed_owner_email: device.claimedOwnerEmail,
+        });
+    }
+}
+/**
+ * `cockpit logout` — removing the session file is the whole revocation on this
+ * side, and an absent file is success, not a failure to report.
+ */
+export async function logoutLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    let removed = false;
+    try {
+        await fs.unlink(paths.session_file);
+        removed = true;
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+    return { removed, session_file: paths.session_file };
+}
+async function postPairStart(fetchImpl, dashboardUrl, body, accessToken) {
+    const response = await fetchImpl(`${dashboardUrl}/api/ambient/pair/start`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            ...(accessToken ? { "Authorization": `Bearer ${accessToken}` } : {}),
+        },
+        body: JSON.stringify(body),
+    });
+    const parsed = await readResponseJson(response);
+    if (!response.ok) {
+        throw new Error(pairFailureMessage("Pair request failed", response, parsed));
+    }
+    return parsePairStartResponse(parsed);
+}
+async function pollPairRequest(fetchImpl, dashboardUrl, options) {
+    const pollIntervalMs = options.pollIntervalMs ?? options.startResponse.poll_after_ms;
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1000;
+    const sleepImpl = options.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const response = await fetchImpl(`${dashboardUrl}/api/ambient/pair/poll`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                request_id: options.startResponse.request_id,
+                client_secret: options.startResponse.client_secret,
+            }),
+        });
+        const parsed = await readResponseJson(response);
+        if (!response.ok) {
+            throw new Error(pairFailureMessage("Pair polling failed", response, parsed));
+        }
+        const status = readStringField(parsed, "status");
+        if (status === "approved") {
+            const session = parsePairApprovedSession(parsed, options.paths.session_file);
+            await writeJsonFile(options.paths.session_file, session);
+            return session;
+        }
+        if (status === "expired") {
+            throw new Error("Pair request expired. Run `cockpit login` again.");
+        }
+        if (status === "revoked") {
+            throw new Error("Pair request was revoked. Run `cockpit login` again.");
+        }
+        if (status !== "pending") {
+            throw new Error(`Unexpected pair request status: ${status}`);
+        }
+        await sleepImpl(Math.max(250, pollIntervalMs));
+    }
+    throw new Error("Timed out waiting for dashboard approval. Run `cockpit login` again.");
+}
+/**
+ * What `cockpit login` tells the operator when pairing is refused.
+ *
+ * "Pair request failed" was the whole message — five words, while the status
+ * code sat in hand (BLI-3483). A 401 (this build's token is not accepted), a
+ * 403 (the dashboard knows the device and is refusing it), a 404 (wrong
+ * dashboard URL) and a 502 (something in front of the dashboard answered) are
+ * four different next actions, and the operator could not tell them apart.
+ * `upload.ts` has named its HTTP status since it was written; this is the same
+ * shape. The server's own words come first when it supplied any, and the status
+ * always rides at the end so it is never the thing that got dropped.
+ *
+ * Logged as well as thrown: `cockpit login` failures happen on a machine that
+ * is not collecting yet, so the terminal is the only receipt there is.
+ */
+function pairFailureMessage(fallback, response, body) {
+    const serverWords = responseErrorMessage(body, fallback);
+    console.error("[local-state] pairing request refused", JSON.stringify({
+        reason: fallback === "Pair request failed" ? "pair_start_refused" : "pair_poll_refused",
+        http_status: response.status,
+        server_reason: serverFailureDetail(body) ?? "none",
+    }));
+    return `${serverWords} (HTTP ${response.status})`;
+}
+async function readResponseJson(response) {
+    const text = await response.text();
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Pairing path. A captive portal or a proxy answering with HTML is the
+        // classic reason `cockpit login` fails on a new machine and the operator
+        // sees only "pair request failed". The body is never logged; its shape is.
+        console.error("[local-state] pairing reply was not JSON", JSON.stringify({
+            reason: "response_body_not_json",
+            http_status: response.status,
+            byte_size: text.length,
+            content_type: response.headers.get("content-type") ?? "none",
+        }));
+        return { message: text };
+    }
+}
+function parsePairStartResponse(value) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Pair request response was not an object.");
+    }
+    const record = value;
+    return {
+        request_id: requiredString(record, "request_id"),
+        user_code: requiredString(record, "user_code"),
+        approve_url: requiredString(record, "approve_url"),
+        expires_at: requiredString(record, "expires_at"),
+        poll_after_ms: requiredNumber(record, "poll_after_ms"),
+        client_secret: requiredString(record, "client_secret"),
+    };
+}
+function parsePairApprovedSession(value, sessionFilePath) {
+    if (!value || typeof value !== "object") {
+        throw new Error("Pair approval response was not an object.");
+    }
+    const session = value["session"];
+    if (!session || typeof session !== "object") {
+        throw new Error("Pair approval response did not include a session.");
+    }
+    return LocalCollectorSessionFileSchema.parse({
+        ...session,
+        session_file_path: sessionFilePath,
+    });
+}
+function responseErrorMessage(value, fallback) {
+    if (value && typeof value === "object") {
+        const record = value;
+        const message = record["message"] ?? record["error"];
+        if (typeof message === "string" && message.trim())
+            return message;
+    }
+    return fallback;
+}
+function readStringField(value, field) {
+    if (value && typeof value === "object") {
+        const entry = value[field];
+        if (typeof entry === "string")
+            return entry;
+    }
+    throw new Error(`Pair response missing ${field}.`);
+}
+function requiredString(record, field) {
+    const value = record[field];
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`Pair response missing ${field}.`);
+    }
+    return value;
+}
+function requiredNumber(record, field) {
+    const value = record[field];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Pair response missing ${field}.`);
+    }
+    return value;
+}

package/dist/local-state-paths.js

@@ -0,0 +1,61 @@
+import { getUserLocalCockpitPaths } from "@bli-cockpit/telemetry-core";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { describeError } from "./health-detail.js";
+/**
+ * The one place a collector file's address is computed, so no caller joins a
+ * state path by hand and drifts from the durable on-disk layout.
+ */
+export function getCollectorRuntimePaths(homeDir = os.homedir()) {
+    const paths = getUserLocalCockpitPaths(homeDir);
+    return {
+        ...paths,
+        active_work_context_file: path.join(paths.state_dir, "active-work-context.json"),
+        work_contexts_dir: path.join(paths.state_dir, "work-contexts"),
+    };
+}
+/**
+ * Every write below assumes its directory exists and is owner-only, so this
+ * runs before the first one on a fresh machine and after every upgrade.
+ */
+export async function ensureRuntimeDirectories(paths) {
+    await fs.mkdir(paths.config_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.state_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.spool_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.cursors_dir, { recursive: true, mode: 0o700 });
+    await fs.mkdir(paths.work_contexts_dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        // The `mode` above only applies to directories this call CREATES, so these
+        // chmods are what actually tightens a directory that already existed with
+        // looser bits. Failing means the operator's device token and cursors stay
+        // world-readable — non-fatal, deliberately, but not something to find out
+        // about never (BLI-3238). Reported by directory name only, never a path.
+        const tightened = [
+            ["config_dir", fs.chmod(paths.config_dir, 0o700)],
+            ["state_dir", fs.chmod(paths.state_dir, 0o700)],
+            ["spool_dir", fs.chmod(paths.spool_dir, 0o700)],
+            ["cursors_dir", fs.chmod(paths.cursors_dir, 0o700)],
+            ["work_contexts_dir", fs.chmod(paths.work_contexts_dir, 0o700)],
+        ];
+        await Promise.all(tightened.map(async ([name, work]) => {
+            try {
+                await work;
+            }
+            catch (error) {
+                console.error("[local-state] could not restrict a runtime directory to owner-only", JSON.stringify({
+                    reason: "runtime_dir_chmod_failed",
+                    directory: name,
+                    ...describeError(error),
+                }));
+            }
+        }));
+    }
+}
+/**
+ * One file per worktree fingerprint, so two checkouts of the same repo keep
+ * separate contexts instead of overwriting each other.
+ */
+export function workContextFile(paths, worktreeFingerprint) {
+    return path.join(paths.work_contexts_dir, `${worktreeFingerprint}.json`);
+}

package/dist/local-state-session.js

@@ -0,0 +1,68 @@
+import { LocalCollectorSessionFileSchema, LocalUserSessionReferenceSchema, } from "@bli-cockpit/telemetry-core";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+import { readJsonFile } from "./local-state-files.js";
+/**
+ * Who this machine is signed in as, in the shape every caller wants: a
+ * reference that always exists, so nothing downstream has to handle "there is
+ * no session file yet" as an error.
+ */
+export async function readLocalSessionReference(paths, fallback = {}) {
+    try {
+        const rawSession = await readJsonFile(paths.session_file);
+        const collectorSession = LocalCollectorSessionFileSchema.safeParse(rawSession);
+        if (collectorSession.success) {
+            return toSessionReference(collectorSession.data);
+        }
+        return LocalUserSessionReferenceSchema.parse(rawSession);
+    }
+    catch (error) {
+        // `session_state: "missing"` is correct before login and says so loudly
+        // enough on its own. It is also what a session file that EXISTS but is
+        // corrupt, truncated or unreadable collapses to — a paired machine that
+        // silently reads as never-signed-in, which is indistinguishable in every
+        // downstream receipt (BLI-3238).
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] session file present but unusable, reading as missing", JSON.stringify({
+                reason: "session_file_unusable",
+                ...describeError(error),
+            }));
+        }
+        return LocalUserSessionReferenceSchema.parse({
+            operator_id: fallback.operatorId ?? "unknown",
+            auth_subject_id: "unknown",
+            session_id: fallback.sessionId ?? "missing",
+            session_file_path: paths.session_file,
+            session_state: "missing",
+        });
+    }
+}
+/**
+ * The strict read, for the callers that need the device token itself and
+ * cannot proceed on a "missing" reference.
+ */
+export async function readLocalCollectorSessionFile(paths) {
+    return LocalCollectorSessionFileSchema.parse(await readJsonFile(paths.session_file));
+}
+/**
+ * Drops the device token and re-states expiry as a session state, so an
+ * expired session cannot travel as `valid` just because the file says so.
+ */
+export function toSessionReference(session) {
+    const now = Date.now();
+    const expiresAt = Date.parse(session.expires_at ?? "");
+    const sessionState = Number.isFinite(expiresAt) && expiresAt <= now ? "expired" : session.session_state;
+    return LocalUserSessionReferenceSchema.parse({
+        operator_id: session.operator_id,
+        auth_subject_id: session.auth_subject_id,
+        email: session.email,
+        team_id: session.team_id,
+        device_id: session.device_id,
+        device_name: session.device_name,
+        session_id: session.session_id,
+        session_file_path: session.session_file_path,
+        session_state: sessionState,
+        auth_method: session.auth_method,
+        issued_at: session.issued_at,
+        expires_at: session.expires_at,
+    });
+}

package/dist/local-state-status.js

@@ -0,0 +1,163 @@
+import os from "node:os";
+import path from "node:path";
+import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
+import { summarizeInstallEventOutbox } from "./spool/install-event-outbox.js";
+import { readRawEvidenceStagingState, summarizeStuckEvidence, } from "./raw-evidence-staging.js";
+import { getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
+import { readLocalSessionReference } from "./local-state-session.js";
+import { resolveIdentityOrFallback } from "./local-state-identity.js";
+import { readLocalWorkContextForRepo, workDisplayLabel, } from "./local-state-work-context.js";
+/**
+ * `cockpit status` — the one answer to "is this machine collecting, and is
+ * anything landing?". A green status must never be able to hide a session that
+ * never arrived, so every queue and every stuck object is reported here.
+ */
+export async function inspectLocalCollectorStatus(options = {}) {
+    const now = options.now ?? new Date();
+    const reading = await readCollectorStatus(options, now);
+    const { paths, config, session, identity, context, branch } = reading;
+    const { uploadSpool, healthOutbox, stuckEvidence } = reading;
+    const freshness = classifyCollectorFreshness(context, uploadSpool.last_upload_success_at, now);
+    const uploadState = classifyUploadState(config, uploadSpool, session);
+    return {
+        installed: Boolean(config),
+        config_file: paths.config_file,
+        session_file: paths.session_file,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        config_collector_version: config?.collector_version ?? null,
+        session_state: session.session_state,
+        repo: context?.repo ?? identity.repo_root,
+        branch,
+        active_ticket_id: context?.active_ticket_id ?? null,
+        work_label: context ? workDisplayLabel(context) : null,
+        work_id: context?.work_context_id ?? null,
+        work_context_id: context?.work_context_id ?? null,
+        repo_label: context?.repo_label ?? identity.repo_label,
+        repo_fingerprint: context?.repo_fingerprint ?? identity.repo_fingerprint,
+        worktree_label: context?.worktree_label ?? identity.worktree_label,
+        worktree_fingerprint: context?.worktree_fingerprint ?? identity.worktree_fingerprint,
+        worktree_is_primary: context?.worktree_is_primary ?? identity.worktree_is_primary,
+        collector_freshness: freshness,
+        upload_state: uploadState,
+        last_upload_attempt_at: uploadSpool.last_upload_attempt_at,
+        last_upload_success_at: uploadSpool.last_upload_success_at,
+        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,
+        stuck_evidence_object_count: stuckEvidence.stuck_object_count,
+        stuck_evidence_held_count: stuckEvidence.held_object_count,
+        stuck_evidence_max_attempts: stuckEvidence.max_attempts,
+        stuck_evidence_oldest_failure_at: stuckEvidence.oldest_first_failed_at,
+        stuck_evidence_reasons: stuckEvidence.reasons,
+        details: describeCollectorStatus(reading),
+    };
+}
+async function readCollectorStatus(options, now) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
+    const paths = getCollectorRuntimePaths(homeDir);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const session = await readLocalSessionReference(paths, {
+        operatorId: options.operatorId,
+        sessionId: options.sessionId,
+    });
+    const identity = await resolveIdentityOrFallback(repoRoot, options.branch);
+    const context = await readLocalWorkContextForRepo(paths, repoRoot).catch(() => null);
+    const branch = options.branch ?? identity.branch;
+    const [uploadSpool, healthOutbox, stagingState] = await Promise.all([
+        summarizeLocalUploadSpool(paths),
+        summarizeInstallEventOutbox(paths),
+        readRawEvidenceStagingState(paths.state_dir),
+    ]);
+    const stuckEvidence = summarizeStuckEvidence(stagingState, now);
+    return {
+        paths,
+        config,
+        session,
+        identity,
+        context,
+        branch,
+        uploadSpool,
+        healthOutbox,
+        stuckEvidence,
+    };
+}
+// Not installed outranks everything, and a pending retry outranks a valid
+// session. The return type is inferred: the four labels are already written
+// once in `LocalCollectorStatus` and once here, and a third copy would be a
+// third place to forget one.
+function classifyUploadState(config, uploadSpool, session) {
+    return !config
+        ? "not_installed"
+        : uploadSpool.pending_upload_count > 0
+            ? "retry_pending"
+            : session.session_state === "valid"
+                ? "ready"
+                : "local_only_missing_auth";
+}
+/**
+ * The sentences an operator actually reads. Each of the first five is stated
+ * either way round, because a line that only appears on failure cannot answer
+ * "did anything land at all today?"; the last four appear only when there is a
+ * queue, and each names its own reason and count.
+ */
+function describeCollectorStatus(reading) {
+    const { paths, config, session, context, uploadSpool, healthOutbox, stuckEvidence } = reading;
+    const details = [];
+    details.push(config
+        ? `Config exists at ${paths.config_file}.`
+        : "Local config missing. Run `cockpit install`.");
+    details.push(session.session_state === "valid"
+        ? "Local user session is valid."
+        : "Local user session missing or not paired; upload remains local-only.");
+    details.push(context
+        ? `Active work ${workDisplayLabel(context)} (${context.work_context_id}) last updated ${context.updated_at ?? context.started_at}.`
+        : "Active work context missing. Run `cockpit start`.");
+    details.push(uploadSpool.last_upload_attempt_at
+        ? `Last upload attempt: ${uploadSpool.last_upload_attempt_at}.`
+        : "No upload has been attempted yet.");
+    details.push(uploadSpool.last_upload_success_at
+        ? `Last upload success: ${uploadSpool.last_upload_success_at}.`
+        : "No successful upload recorded yet.");
+    if (uploadSpool.last_upload_failure_reason) {
+        details.push(`Last upload failure: ${uploadSpool.last_upload_failure_reason}.`);
+    }
+    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"}.`);
+    }
+    if (stuckEvidence.stuck_object_count > 0) {
+        details.push(`Raw evidence stuck: ${stuckEvidence.stuck_object_count} object(s) have never been accepted (${stuckEvidence.held_object_count} waiting on backoff, worst ${stuckEvidence.max_attempts} attempt(s) since ${stuckEvidence.oldest_first_failed_at ?? "unknown"}) — reasons: ${stuckEvidence.reasons.join(", ") || "unknown"}.`);
+    }
+    return details;
+}
+/**
+ * Whether this machine looks alive right now. A successful upload counts as
+ * activity as much as a context update does, so a long session that is still
+ * shipping data does not read as stale.
+ */
+export function classifyCollectorFreshness(context, lastUploadSuccessAt, now) {
+    if (!context)
+        return "missing";
+    const latestActivityAt = latestTimestamp([
+        context.updated_at ?? context.started_at,
+        lastUploadSuccessAt,
+    ]);
+    if (latestActivityAt === null)
+        return "stale";
+    return now.getTime() - latestActivityAt <= 5 * 60 * 1000 ? "fresh" : "stale";
+}
+function latestTimestamp(values) {
+    const timestamps = values
+        .map((value) => Date.parse(value ?? ""))
+        .filter((value) => Number.isFinite(value));
+    if (timestamps.length === 0)
+        return null;
+    return Math.max(...timestamps);
+}