@bli-cockpit/cli 0.2.48 → 0.2.50

package/dist/commands/sync.js

@@ -0,0 +1,387 @@
+import { writeLine } from "./cli-io.js";
+import { attributedSyncRunStatus, cursorStatusLine, displayTicketId, rawEvidenceSyncLine, shortSha, worktreeSyncRow, writeAgentSessionSummary, } from "./collection-report.js";
+import { collectionRootConsentAliases } from "./collection-roots.js";
+import { discoverCommandWorktrees } from "./local-discovery.js";
+import { sendCollectorHeartbeatBestEffort, } from "./heartbeat.js";
+import { classifySyncFailureRecords, classifySyncHealthError, redactedSyncErrorDetail, reportInstallEventsBestEffort, } from "./install-receipts.js";
+import { runAttributedWorktreeSync, } from "./session-sync.js";
+import { runAutostartSelfHealAfterSync, runMemoryInstallAfterSync, runScheduledSelfUpdateAfterSync, } from "./sync-followups.js";
+import { describeError } from "../health-detail.js";
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { rotateCollectorLogsBestEffort } from "../log-rotation.js";
+import { DEFAULT_DASHBOARD_URL, getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { CollectionRootRequiredError, } from "../onboarding-roots.js";
+import { rawEvidenceDedupSummary, rawEvidenceGcSummary, runRawEvidenceLocalGc, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { acquireSyncLock } from "../sync-lock.js";
+export async function runSync(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    // BLI-3553, first thing in the tick: cap the scheduler's own logs. Nothing
+    // rotated them before, and two months of a 15-minute tick left 211 MB of
+    // sync.log on the reference Mac. Best-effort by construction — a rotation
+    // problem is its own log line, never a reason collection does not run.
+    await rotateCollectorLogsBestEffort(paths);
+    const config = await readLocalCollectorConfig(paths).catch(() => null);
+    const dashboardUrl = command.dashboardUrl ?? config?.dashboard_url ?? DEFAULT_DASHBOARD_URL;
+    const minCliVersionAtStart = await reportInstallEventsBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        command: "sync",
+        events: [{ step: "sync_started", status: "ok" }],
+        json: command.json,
+        io,
+    });
+    try {
+        const result = await runSyncWithHealthReceipt(command, io);
+        // BLI-3551: every tick checks in, including one that collected nothing.
+        // This is the only writer of `last_seen_at` that does not need an envelope,
+        // so it is what separates a quiet machine from a dead one.
+        await sendSyncHeartbeat(command, io, dashboardUrl, result.heartbeat);
+        const minCliVersion = await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl,
+            command: "sync",
+            events: [result.completion],
+            json: command.json,
+            io,
+        });
+        // BLI-2601: self-update runs only after collection's own outcome above is
+        // already decided and reported, win or lose. See the function doc.
+        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
+        await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
+        // BLI-3580: BLI Memory's registration converges the same way — after
+        // collection, at most once a day, its own receipt either way.
+        await runMemoryInstallAfterSync(command, io, dashboardUrl);
+        return result.exitCode;
+    }
+    catch (error) {
+        const errorCode = classifySyncHealthError(error);
+        // A machine whose sync THREW is still alive, and that is worth knowing —
+        // a device that stops checking in entirely is a different problem from one
+        // checking in with a failure every fifteen minutes.
+        await sendSyncHeartbeat(command, io, dashboardUrl, {
+            status: "fail",
+            reason: errorCode,
+        });
+        const minCliVersion = await reportInstallEventsBestEffort({
+            homeDir: command.homeDir,
+            dashboardUrl,
+            command: "sync",
+            events: [
+                {
+                    step: "sync_complete",
+                    status: "fail",
+                    error_code: errorCode,
+                    error_detail: redactedSyncErrorDetail(error),
+                },
+            ],
+            json: command.json,
+            io,
+        });
+        await runScheduledSelfUpdateAfterSync(command, io, dashboardUrl, minCliVersion ?? minCliVersionAtStart);
+        await runAutostartSelfHealAfterSync(command, io, dashboardUrl);
+        // BLI-3580: BLI Memory's registration converges the same way — after
+        // collection, at most once a day, its own receipt either way.
+        await runMemoryInstallAfterSync(command, io, dashboardUrl);
+        throw error;
+    }
+}
+/**
+ * The tick's check-in (BLI-3551).
+ *
+ * Resolving the roots is best-effort on purpose: a machine with NO approved
+ * root is exactly the machine whose silence needs explaining, so it still
+ * checks in — with an empty root list, which is itself the finding.
+ */
+async function sendSyncHeartbeat(command, io, dashboardUrl, facts) {
+    const roots = await resolveSyncCollectionRoots(command).catch(() => []);
+    await sendCollectorHeartbeatBestEffort({
+        homeDir: command.homeDir,
+        dashboardUrl,
+        roots,
+        facts,
+        io,
+    }).catch((error) => {
+        // The sender already swallows everything it knows about; this is the net
+        // for anything it does not, because a heartbeat must never fail a sync.
+        console.error("[heartbeat] the check-in threw and was dropped", JSON.stringify({ reason: "heartbeat_threw", ...describeError(error) }));
+        return false;
+    });
+}
+async function runSyncWithHealthReceipt(command, io) {
+    const backfillLock = await inspectBackfillLock(getCollectorRuntimePaths(command.homeDir));
+    if (backfillLock.held) {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: "live_sync_paused_during_backfill",
+                reason: "live sync paused during backfill",
+                held_since: backfillLock.held_since,
+                collection_complete: false,
+                upload_state: "not_uploaded",
+                retryable: true,
+            }, null, 2));
+        }
+        else {
+            writeLine(io.stdout, "Pausing normal sync while it catches up on old sessions.");
+        }
+        return {
+            exitCode: 0,
+            completion: {
+                step: "sync_complete",
+                status: "skipped",
+                error_code: "live_sync_paused_during_backfill",
+            },
+            heartbeat: {
+                status: "skipped",
+                reason: "live_sync_paused_during_backfill",
+            },
+        };
+    }
+    // Single-flight: a launchd timer and a manual sync must not interleave the
+    // cursor read-modify-write. A blocked invocation exits cleanly (B.4 §7).
+    const lock = await acquireSyncLock(getCollectorRuntimePaths(command.homeDir));
+    if (!lock.acquired) {
+        if (command.json) {
+            writeLine(io.stdout, JSON.stringify({
+                status: "sync_already_running",
+                reason: "another sync owns the collection lock",
+                held_since: lock.held_since,
+                collection_complete: false,
+                upload_state: "not_uploaded",
+                retryable: true,
+            }, null, 2));
+        }
+        else {
+            writeLine(io.stdout, "Tower sync already running; skipping this run.");
+        }
+        return {
+            exitCode: 0,
+            completion: {
+                step: "sync_complete",
+                status: "skipped",
+                error_code: "sync_already_running",
+            },
+            heartbeat: { status: "skipped", reason: "sync_already_running" },
+        };
+    }
+    try {
+        const { exitCode, failureReasons, failureRecords, notice, sessionsObserved, sessionsOutsideRoot, } = await runSyncLocked(command, io);
+        const counts = {
+            sessionsObserved,
+            sessionsOutsideRoot,
+        };
+        if (exitCode === 0) {
+            // BLI-3551: an `ok` tick can still have something to say. `nothing_in_root`
+            // is the receipt that separates "this machine is alive and its operator
+            // works outside the approved roots" from "this machine is dead", which
+            // until now looked identical from the dashboard.
+            return {
+                exitCode,
+                completion: {
+                    step: "sync_complete",
+                    status: "ok",
+                    ...(notice ? { error_detail: notice } : {}),
+                },
+                heartbeat: { status: "ok", reason: notice, ...counts },
+            };
+        }
+        // A sync that fails by exit code says exactly as much as one that throws.
+        // It used to say `sync_failed` and nothing else, so 100% of recorded
+        // failure rows carried a null detail and the real reason was reachable only
+        // by running `cockpit status` on the machine itself (BLI-2526).
+        const reasonText = failureReasons.join("; ");
+        // The bucket comes from the records the deciding branches wrote, not from
+        // this sentence (BLI-3551). The sentence is still the detail.
+        const errorCode = classifySyncFailureRecords(failureRecords);
+        return {
+            exitCode,
+            completion: {
+                step: "sync_complete",
+                status: "fail",
+                error_code: errorCode,
+                error_detail: redactedSyncErrorDetail(reasonText),
+            },
+            heartbeat: { status: "fail", reason: errorCode, ...counts },
+        };
+    }
+    finally {
+        await lock.handle.release();
+    }
+}
+/**
+ * Turn a finished run into an exit code and the reasons behind it.
+ *
+ * One place, so a future return path cannot reintroduce a code with no reason.
+ * The reasons come from the run itself — the code that decided `ok` is false is
+ * the only code that knows why.
+ */
+function syncResult(run) {
+    return {
+        exitCode: run.ok ? 0 : 1,
+        failureReasons: run.ok ? [] : run.failure_reasons,
+        failureRecords: run.ok ? [] : run.failure_records,
+        notice: run.notice,
+        sessionsObserved: run.sessions_observed,
+        sessionsOutsideRoot: run.sessions_outside_root,
+    };
+}
+/**
+ * The sync runbook: resolve which roots to collect, dedup staged packs before
+ * touching anything else, discover worktrees, sync them, then report — one of
+ * three shapes depending on how many worktrees came back. The three shapes
+ * share nothing but `dedup`, so each gets its own step function below rather
+ * than one branchy body.
+ */
+async function runSyncLocked(command, io) {
+    const collectionRoots = await resolveSyncCollectionRoots(command);
+    // Before anything is collected: collapse byte-identical staged packs. It runs
+    // first, unconditionally and unthrottled, because a machine that already
+    // holds 559 copies of one rollout needs the disk back before it stages
+    // anything else (BLI-3066). Safe by construction — a duplicate is identical
+    // by content hash to the survivor.
+    const dedup = await sweepDuplicateStagedRawEvidence(getCollectorRuntimePaths(command.homeDir), io.env);
+    if (!dedup.skipped && dedup.removed_dirs > 0) {
+        writeLine(io.stdout, rawEvidenceDedupSummary(dedup));
+    }
+    const worktrees = await discoverCommandWorktrees(collectionRoots, {
+        maxDepth: command.maxDepth,
+        maxRepos: command.maxRepos,
+        homeDir: command.homeDir,
+        allowEmpty: true,
+    }, io);
+    const run = await runAttributedWorktreeSync({
+        homeDir: command.homeDir,
+        dashboardUrl: command.dashboardUrl,
+        collectionRoots,
+        startContexts: false,
+        worktrees,
+        fetchImpl: io.fetch,
+    });
+    if (run.outcomes.length > 1) {
+        return reportMultiRepoSync(command, io, run, dedup);
+    }
+    // Zero worktrees is a legitimate steady state, not a failure: an approved
+    // root can hold no git repos, and sessions upload independently of
+    // worktrees (session-first, BLI-2581). This used to throw "Sync produced no
+    // result", which painted ~90 false-red sync_failed receipts per day on one
+    // fleet machine with a single empty root and taught people to ignore
+    // sync_failed (BLI-2722). A genuinely broken run still fails via run.ok.
+    if (run.outcomes.length === 0) {
+        return reportNoWorktreeSync(command, io, run, dedup);
+    }
+    return reportSingleRepoSync(command, io, run, dedup);
+}
+async function reportMultiRepoSync(command, io, run, dedup) {
+    const rows = run.outcomes.map((outcome) => worktreeSyncRow(outcome, run));
+    const collectionRunStatus = attributedSyncRunStatus(run);
+    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            mode: "multi_repo",
+            status: collectionRunStatus,
+            collection_complete: run.ok,
+            results: run.outcomes.map((outcome) => outcome.sync),
+            repos: rows,
+            codex_sessions: run.summary,
+            raw_evidence_gc: gc,
+            raw_evidence_dedup: dedup,
+        }, null, 2));
+        return syncResult(run);
+    }
+    writeLine(run.ok ? io.stdout : io.stderr, `Tower parent sync ${collectionRunStatus} ${run.outcomes.filter((outcome) => outcome.sync.status === "uploaded").length}/${run.outcomes.length} worktree(s).`);
+    for (const outcome of run.outcomes) {
+        const { worktree, sync } = outcome;
+        const uploaded = sync.status === "uploaded";
+        const failureSuffix = sync.status === "spooled" ? ` reason:${sync.failure_reason}` : "";
+        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 syncResult(run);
+}
+async function reportNoWorktreeSync(command, io, run, dedup) {
+    const collectionRunStatus = attributedSyncRunStatus(run);
+    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            mode: "no_worktrees",
+            status: collectionRunStatus,
+            collection_complete: run.ok,
+            ...(run.notice ? { notice: run.notice } : {}),
+            codex_sessions: run.summary,
+            raw_evidence_gc: gc,
+            raw_evidence_dedup: dedup,
+        }, null, 2));
+        return syncResult(run);
+    }
+    writeLine(run.ok ? io.stdout : io.stderr, `Tower sync ${collectionRunStatus}: no git worktrees under this root; session scan ran.`);
+    if (run.notice) {
+        // Says out loud what the receipt now says to the dashboard: the sessions
+        // this machine ran were all outside the folders it is allowed to look at.
+        writeLine(io.stdout, `Every session seen this run was outside your approved folders (${run.notice}). Nothing was collected, and nothing is broken.`);
+    }
+    writeAgentSessionSummary(io, run.summary);
+    if (gc && !gc.skipped)
+        writeLine(io.stdout, rawEvidenceGcSummary(gc));
+    return syncResult(run);
+}
+async function reportSingleRepoSync(command, io, run, dedup) {
+    const result = run.outcomes[0]?.sync;
+    if (!result) {
+        throw new Error("Sync produced no result for the repo worktree.");
+    }
+    const collectionRunStatus = attributedSyncRunStatus(run);
+    const gc = run.ok ? await runSyncRawEvidenceGc(command, io) : null;
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            ...result,
+            status: collectionRunStatus,
+            collection_complete: run.ok,
+            codex_sessions: run.summary,
+            raw_evidence_gc: gc,
+            raw_evidence_dedup: dedup,
+        }, null, 2));
+        return syncResult(run);
+    }
+    if (run.ok) {
+        writeLine(io.stdout, "Tower uploaded this session.");
+        writeLine(io.stdout, `Ticket: ${displayTicketId(result.ticket_id)}`);
+        writeLine(io.stdout, `Context: ${result.work_context_id}`);
+        writeLine(io.stdout, `Head: ${shortSha(result.head_sha)}`);
+        writeLine(io.stdout, `Things recorded: ${result.event_count}`);
+        writeLine(io.stdout, `Risk flags: ${result.risk_flag_count}`);
+        writeLine(io.stdout, `Raw evidence files: ${result.raw_evidence_file_count}`);
+        writeLine(io.stdout, rawEvidenceSyncLine(result));
+        writeAgentSessionSummary(io, run.summary);
+        writeLine(io.stdout, cursorStatusLine(result));
+        if (gc && !gc.skipped)
+            writeLine(io.stdout, rawEvidenceGcSummary(gc));
+        return syncResult(run);
+    }
+    if (result.status === "uploaded") {
+        writeLine(io.stderr, "Tower uploaded, but some sessions did not make it. Run `cockpit sync` again.");
+        writeAgentSessionSummary(io, run.summary);
+        return syncResult(run);
+    }
+    writeLine(io.stderr, "Tower could not upload. It saved a note to retry and will try again on the next sync.");
+    writeLine(io.stderr, `Ticket: ${displayTicketId(result.ticket_id)}`);
+    writeLine(io.stderr, `Failure: ${result.failure_reason}`);
+    writeLine(io.stderr, `Retry: ${result.retry_command}`);
+    return syncResult(run);
+}
+async function resolveSyncCollectionRoots(command) {
+    const explicitRoots = normalizeCollectionRoots(command.repoRoot ? [command.repoRoot] : []);
+    if (explicitRoots.length > 0) {
+        return collectionRootConsentAliases(explicitRoots);
+    }
+    const config = await readLocalCollectorConfig(getCollectorRuntimePaths(command.homeDir)).catch(() => null);
+    const savedRoots = normalizeCollectionRoots(config?.default_repo_paths ?? []);
+    if (savedRoots.length > 0) {
+        return collectionRootConsentAliases(savedRoots);
+    }
+    throw new CollectionRootRequiredError(`no explicit or saved collection root is available.`);
+}
+async function runSyncRawEvidenceGc(command, io) {
+    return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
+}

package/dist/local-state-attributed-target.js

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { normalizeGitOrigin, repoFingerprintFromLocalRoot, repoFingerprintFromOrigin, repoLabelFromOrigin, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
+import { isSamePath } from "./root-normalization.js";
+/**
+ * A transcript-attributed target is an identity a CALLER built — for a wrapper
+ * folder or a repo that no longer exists on disk — so every field of it is
+ * re-derived here before a single byte of context state is written. Nothing
+ * downstream can tell an invented fingerprint from a real one.
+ *
+ * The checks run in a fixed order and each throws its own sentence, so the
+ * first thing wrong is the thing the operator is told about.
+ */
+export async function validateAttributedTargetIdentity(requestedRepoRoot, identity) {
+    const canonicalRoot = await stableWorktreeRoot(requestedRepoRoot);
+    const identityRoot = await stableWorktreeRoot(identity.repo_root);
+    const identityRequestedPath = await stableWorktreeRoot(identity.requested_path);
+    if (!isSamePath(canonicalRoot, identityRoot) ||
+        !isSamePath(canonicalRoot, identityRequestedPath)) {
+        throw new Error("Attributed target identity paths do not match the requested repo root.");
+    }
+    const expectedWorktreeFingerprint = stableWorktreeFingerprint(canonicalRoot);
+    if (identity.worktree_fingerprint !== expectedWorktreeFingerprint) {
+        throw new Error("Attributed target worktree fingerprint does not match its repo root.");
+    }
+    const expectedWorktreeLabel = path.basename(canonicalRoot) || "workspace";
+    if (identity.worktree_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target worktree label does not match its repo root.");
+    }
+    if (identity.repo_origin_url) {
+        assertRepoFieldsMatchOrigin(identity, identity.repo_origin_url);
+    }
+    else {
+        assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel);
+    }
+    return {
+        ...identity,
+        requested_path: canonicalRoot,
+        repo_root: canonicalRoot,
+    };
+}
+/**
+ * An origin-derived target is a repo reconstructed from transcript
+ * provenance, so it may not claim to be the live primary worktree of anything.
+ */
+function assertRepoFieldsMatchOrigin(identity, repoOriginUrl) {
+    const normalizedOrigin = normalizeGitOrigin(repoOriginUrl);
+    if (normalizedOrigin !== repoOriginUrl) {
+        throw new Error("Attributed target repo origin is not normalized.");
+    }
+    if (identity.repo_fingerprint !== repoFingerprintFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo fingerprint does not match its origin.");
+    }
+    if (identity.repo_label !== repoLabelFromOrigin(normalizedOrigin)) {
+        throw new Error("Attributed target repo label does not match its origin.");
+    }
+    if (identity.worktree_is_primary) {
+        throw new Error("Origin-derived attributed targets cannot claim a primary live worktree.");
+    }
+}
+/**
+ * Without an origin the only thing an identity can honestly be derived from is
+ * the local root, so the fingerprint, the label and primacy all follow from it.
+ */
+function assertRepoFieldsMatchLocalRoot(identity, canonicalRoot, expectedWorktreeLabel) {
+    if (identity.repo_fingerprint !==
+        repoFingerprintFromLocalRoot(canonicalRoot)) {
+        throw new Error("Attributed target repo fingerprint does not match its local root.");
+    }
+    if (identity.repo_label !== expectedWorktreeLabel) {
+        throw new Error("Attributed target repo label does not match its local root.");
+    }
+    if (!identity.worktree_is_primary) {
+        throw new Error("Local attributed targets must use their primary local identity.");
+    }
+}

package/dist/local-state-config.js

@@ -0,0 +1,147 @@
+import { LocalCollectorConfigSchema, } from "@bli-cockpit/telemetry-core";
+import crypto from "node:crypto";
+import { readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { normalizeCollectionRoots } from "./root-normalization.js";
+import { ensureRuntimeDirectories, getCollectorRuntimePaths, } from "./local-state-paths.js";
+import { isMissingFileError, readJsonFile, writeJsonFile, } from "./local-state-files.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
+    : "0.0.0";
+export const DEFAULT_DASHBOARD_URL = "https://bli-cockpit-dashboard.vercel.app";
+/**
+ * `cockpit install` — the one write that registers collection roots, because
+ * widening an operator's boundary is a consent decision and nothing else may
+ * make it.
+ */
+export async function installLocalCollector(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const repoRoots = normalizeRepoRoots(options.repoRoots);
+    const repoRoot = path.resolve(options.repoRoot ?? repoRoots[0] ?? process.cwd());
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    const existingConfig = await readLocalCollectorConfig(paths).catch(() => null);
+    const defaultRepoPaths = normalizeRepoRoots([
+        ...(options.replaceRepoRoots ? [] : (existingConfig?.default_repo_paths ?? [])),
+        ...(repoRoots.length > 0 ? repoRoots : [repoRoot]),
+    ]);
+    const rawEvidenceUpload = migrateRawEvidenceUploadChoice(existingConfig);
+    const config = LocalCollectorConfigSchema.parse({
+        schema_version: "telemetry-core.v1",
+        dashboard_url: options.dashboardUrl ?? existingConfig?.dashboard_url ?? DEFAULT_DASHBOARD_URL,
+        supabase_url: options.supabaseUrl ?? existingConfig?.supabase_url,
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        device_id: existingConfig?.device_id ?? `device-${crypto.randomUUID()}`,
+        device_name: normalizeDeviceName(options.deviceName) ??
+            existingConfig?.device_name ??
+            defaultDeviceName(),
+        claimed_owner_email: existingConfig?.claimed_owner_email,
+        operator_id: existingConfig?.operator_id,
+        default_repo_paths: defaultRepoPaths,
+        raw_evidence_upload: rawEvidenceUpload,
+        session_file_path: paths.session_file,
+        state_dir_path: paths.state_dir,
+    });
+    await writeJsonFile(paths.config_file, config);
+    return {
+        config,
+        paths,
+        auth_pairing_state: "missing",
+        message: "Local collector installed. Pair/login is still required before remote upload.",
+    };
+}
+/**
+ * The one on-disk migration this file performs: both retired raw-evidence
+ * choices become the durable one, so a machine installed before durable
+ * evidence existed stops holding the old answer forever.
+ */
+function migrateRawEvidenceUploadChoice(existingConfig) {
+    return existingConfig?.raw_evidence_upload === "disabled" ||
+        existingConfig?.raw_evidence_upload === "remote_short_retention_opt_in"
+        ? "remote_durable_opt_in"
+        : (existingConfig?.raw_evidence_upload ?? "remote_durable_opt_in");
+}
+function normalizeRepoRoots(repoRoots) {
+    if (!repoRoots)
+        return [];
+    const seen = new Set();
+    const candidates = [];
+    for (const root of repoRoots) {
+        const resolved = path.resolve(root);
+        if (seen.has(resolved))
+            continue;
+        seen.add(resolved);
+        candidates.push(resolved);
+    }
+    return normalizeCollectionRoots(candidates);
+}
+/**
+ * Reads the collector config, creating a minimal rootless one when the file
+ * does not exist yet (fresh machine where `cockpit onboard`/`install` has not
+ * run). Never registers collection roots: root consent stays with
+ * onboard/install. A corrupt existing config is never overwritten.
+ */
+export async function ensureLocalCollectorConfig(options = {}) {
+    const homeDir = options.homeDir ?? os.homedir();
+    const paths = getCollectorRuntimePaths(homeDir);
+    await ensureRuntimeDirectories(paths);
+    let existing = null;
+    try {
+        existing = await readLocalCollectorConfig(paths);
+    }
+    catch (error) {
+        if (!isMissingFileError(error)) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new Error(`Local collector config at ${paths.config_file} is unreadable (${reason}). ` +
+                "Run `cockpit onboard` to repair it.");
+        }
+    }
+    if (existing)
+        return { config: existing, paths, created: false };
+    const config = LocalCollectorConfigSchema.parse({
+        schema_version: "telemetry-core.v1",
+        dashboard_url: normalizeDashboardUrl(options.dashboardUrl ?? DEFAULT_DASHBOARD_URL),
+        collector_version: LOCAL_COLLECTOR_VERSION,
+        device_id: `device-${crypto.randomUUID()}`,
+        device_name: defaultDeviceName(),
+        default_repo_paths: [],
+        session_file_path: paths.session_file,
+        state_dir_path: paths.state_dir,
+    });
+    await writeJsonFile(paths.config_file, config);
+    return { config, paths, created: true };
+}
+/**
+ * Every caller that needs to know how this machine is configured comes through
+ * here, so a config that exists and will not parse fails the same way for all
+ * of them instead of each inventing a default.
+ */
+export async function readLocalCollectorConfig(paths) {
+    return LocalCollectorConfigSchema.parse(await readJsonFile(paths.config_file));
+}
+/**
+ * A trailing slash in a dashboard URL produces `//api/...` request paths that
+ * some proxies answer differently, so the stored value is normalized once.
+ */
+export function normalizeDashboardUrl(value) {
+    const normalized = value.trim().replace(/\/+$/, "");
+    if (!normalized)
+        throw new Error("Dashboard URL cannot be empty.");
+    return normalized;
+}
+/** The device name an operator sees in the dashboard before they pick one. */
+export function defaultDeviceName() {
+    return normalizeDeviceName(os.hostname()) ?? "Local machine";
+}
+/** Keeps a hand-typed or hostname-derived device name inside what the schema accepts. */
+export function normalizeDeviceName(value) {
+    const trimmed = value?.trim().replace(/\s+/g, " ");
+    return trimmed ? trimmed.slice(0, 120) : undefined;
+}
+/** A claimed owner email is a label a person types, so an unusable one is dropped rather than stored. */
+export function normalizeOptionalEmail(value) {
+    const trimmed = value?.trim().toLowerCase();
+    return trimmed && trimmed.includes("@") ? trimmed : undefined;
+}

package/dist/local-state-files.js

@@ -0,0 +1,59 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { describeError, isMissingFileFailure } from "./health-detail.js";
+/**
+ * The one reader behind the config file, the session file and every work
+ * context — and therefore the one place worth reporting from.
+ *
+ * Roughly twenty call sites swallow this to `null` or a default with
+ * `.catch(() => null)`, each of them asking a reasonable question ("is this
+ * machine set up?") to which "no" is a legitimate answer. What none of them
+ * could distinguish is "no, nothing is there" from "yes, and it is corrupt or
+ * unreadable" — so the distinction is drawn HERE, once, rather than in twenty
+ * places where it would be twenty chances to forget (BLI-3238).
+ *
+ * The error still propagates unchanged; callers keep whatever they decided.
+ */
+export async function readJsonFile(filePath) {
+    try {
+        return JSON.parse(await fs.readFile(filePath, "utf8"));
+    }
+    catch (error) {
+        // Absent is the ordinary pre-onboarding state on every one of these files
+        // and stays quiet; anything else means state exists and cannot be used.
+        if (!isMissingFileFailure(error)) {
+            console.error("[local-state] a collector state file exists but could not be read", JSON.stringify({
+                reason: "state_file_unreadable",
+                // Which file, without the path: the basename of these is a fixed
+                // vocabulary (`config.json`, `session.json`, a work-context
+                // fingerprint) and carries no repo or operator name.
+                state_file: path.basename(filePath),
+                ...describeError(error),
+            }));
+        }
+        throw error;
+    }
+}
+/**
+ * The one writer behind every collector state file, because each of them holds
+ * a device token or an operator's work and must land owner-only on any host.
+ */
+export async function writeJsonFile(filePath, value) {
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, {
+        mode: 0o600,
+    });
+    if (process.platform !== "win32") {
+        await fs.chmod(filePath, 0o600).catch(() => undefined);
+    }
+}
+/**
+ * Separate from `isMissingFileFailure`: the two callers here hold a raw `fs`
+ * rejection rather than a wrapped failure, and "the file was never there" is
+ * the one outcome they treat as success rather than an error to report.
+ */
+export function isMissingFileError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}