@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/local-state.js

@@ -1,853 +1,39 @@
-import { getUserLocalCockpitPaths, LocalCollectorSessionFileSchema, LocalCollectorConfigSchema, LocalUserSessionReferenceSchema, LocalWorkContextSchema, } from "@bli-cockpit/telemetry-core";
-import crypto from "node:crypto";
-import { readFileSync } from "node:fs";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { normalizeGitOrigin, repoFingerprintFromLocalRoot, repoFingerprintFromOrigin, repoLabelFromOrigin, resolveRepoWorktreeIdentity, stableWorktreeFingerprint, stableWorktreeRoot, } from "./repo-identity.js";
-import { isSamePath, normalizeCollectionRoots, } from "./root-normalization.js";
-import { summarizeLocalUploadSpool } from "./spool/local-spool.js";
-import { summarizeInstallEventOutbox } from "./spool/install-event-outbox.js";
-import { readRawEvidenceStagingState, summarizeStuckEvidence, } from "./raw-evidence-staging.js";
-import { describeError, isMissingFileFailure } from "./health-detail.js";
-import { serverFailureDetail } from "./upload-http.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";
-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"),
-    };
-}
-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 = 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");
-    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.",
-    };
-}
-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 };
-}
-export async function pairLocalCollector(options = {}) {
-    const homeDir = options.homeDir ?? os.homedir();
-    const paths = getCollectorRuntimePaths(homeDir);
-    await ensureRuntimeDirectories(paths);
-    const config = await 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`.");
-    });
-    const dashboardUrl = normalizeDashboardUrl(options.dashboardUrl ?? config.dashboard_url);
-    const deviceId = config.device_id ?? `device-${crypto.randomUUID()}`;
-    const deviceName = normalizeDeviceName(options.deviceName) ??
-        config.device_name ??
-        defaultDeviceName();
-    const claimedOwnerEmail = normalizeOptionalEmail(options.claimedOwnerEmail) ??
-        config.claimed_owner_email;
-    if (!config.device_id ||
-        config.device_name !== deviceName ||
-        (claimedOwnerEmail && config.claimed_owner_email !== claimedOwnerEmail)) {
-        await writeJsonFile(paths.config_file, {
-            ...config,
-            device_id: deviceId,
-            device_name: deviceName,
-            claimed_owner_email: claimedOwnerEmail,
-        });
-    }
-    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: deviceId,
-        device_name: deviceName,
-        claimed_owner_email: 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,
-    };
-}
-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 };
-}
-export async function startLocalWorkContext(options = {}) {
-    return writeLocalWorkContext(options);
-}
-/**
- * Starts a context for a transcript-attributed sync target that does not exist
- * in the current git inventory, such as an approved wrapper folder or a
- * deleted repo reconstructed from transcript provenance. This internal path
- * validates the exact target identity before writing any context state.
- */
-export async function startLocalWorkContextForAttributedTarget(options, attributedIdentity) {
-    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
-    const identity = await validateAttributedTargetIdentity(repoRoot, attributedIdentity);
-    return writeLocalWorkContext(options, identity);
-}
-async function writeLocalWorkContext(options, attributedIdentity) {
-    if (options.activeTicketId && options.clearTicket) {
-        throw new Error("--ticket and --clear-ticket cannot be combined.");
-    }
-    const now = options.now ?? new Date();
-    const homeDir = options.homeDir ?? os.homedir();
-    const repoRoot = path.resolve(options.repoRoot ?? process.cwd());
-    const paths = getCollectorRuntimePaths(homeDir);
-    await ensureRuntimeDirectories(paths);
-    const config = await readLocalCollectorConfig(paths).catch(() => null);
-    const session = await readLocalSessionReference(paths, {
-        operatorId: options.operatorId,
-        sessionId: options.sessionId,
-    });
-    const identity = attributedIdentity ??
-        (await resolveIdentityOrFallback(repoRoot, options.branch));
-    const branch = attributedIdentity
-        ? attributedIdentity.branch
-        : (options.branch ?? identity.branch);
-    const sessionId = options.sessionId ??
-        (session.session_state === "missing" ? `local-${crypto.randomUUID()}` : session.session_id);
-    const operatorId = options.operatorId ?? session.operator_id;
-    const deviceId = session.device_id ?? config?.device_id ?? "device-unknown";
-    const workContextId = stableWorkContextId({
-        operatorId,
-        deviceId,
-        repoFingerprint: identity.repo_fingerprint,
-        worktreeFingerprint: identity.worktree_fingerprint,
-    });
-    const existingContext = await readLocalWorkContextByFingerprint(paths, identity.worktree_fingerprint).catch(() => null);
-    const activeTicketId = options.clearTicket
-        ? undefined
-        : (options.activeTicketId ?? existingContext?.active_ticket_id);
-    const ticketBindingCandidates = options.activeTicketId
-        ? [
-            {
-                ticket_id: options.activeTicketId,
-                binding_source: "active_work_context",
-                confidence: 1,
-                evidence_labels: ["cockpit_start_ticket"],
-            },
-        ]
-        : options.clearTicket
-            ? []
-            : (existingContext?.ticket_binding_candidates ?? []);
-    const context = LocalWorkContextSchema.parse({
-        work_context_id: workContextId,
-        repo: identity.repo_root,
-        branch,
-        repo_label: identity.repo_label,
-        repo_fingerprint: identity.repo_fingerprint,
-        repo_origin_url: identity.repo_origin_url ?? undefined,
-        head_sha: identity.head_sha ?? undefined,
-        worktree_label: identity.worktree_label,
-        worktree_fingerprint: identity.worktree_fingerprint,
-        worktree_is_primary: identity.worktree_is_primary,
-        operator_id: operatorId,
-        session_id: sessionId,
-        started_at: existingContext?.started_at ?? now.toISOString(),
-        updated_at: now.toISOString(),
-        active_ticket_id: activeTicketId,
-        ticket_binding_candidates: ticketBindingCandidates,
-        topic_label: options.topicLabel,
-        topic_summary_redacted: options.topicSummaryRedacted,
-        work_intent: options.workIntent,
-        work_phase: options.workPhase,
-        intent_source: options.intentSource,
-        intent_confidence: options.intentConfidence,
-        pull_request_url: existingContext?.pull_request_url,
-        provenance: {
-            capture_source: "collector_runtime",
-            capture_adapter_version: LOCAL_COLLECTOR_VERSION,
-            collector_version: LOCAL_COLLECTOR_VERSION,
-            repo: identity.repo_root,
-            branch,
-            repo_label: identity.repo_label,
-            repo_fingerprint: identity.repo_fingerprint,
-            repo_origin_url: identity.repo_origin_url ?? undefined,
-            worktree_label: identity.worktree_label,
-            worktree_fingerprint: identity.worktree_fingerprint,
-            worktree_is_primary: identity.worktree_is_primary,
-            operator_id: operatorId,
-            session_id: sessionId,
-            work_context_id: workContextId,
-        },
-    });
-    await writeJsonFile(workContextFile(paths, identity.worktree_fingerprint), context);
-    await writeJsonFile(paths.active_work_context_file, context);
-    return context;
-}
-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) {
-        const normalizedOrigin = normalizeGitOrigin(identity.repo_origin_url);
-        if (normalizedOrigin !== identity.repo_origin_url) {
-            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.");
-        }
-    }
-    else {
-        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.");
-        }
-    }
-    return {
-        ...identity,
-        requested_path: canonicalRoot,
-        repo_root: canonicalRoot,
-    };
-}
-export async function inspectLocalCollectorStatus(options = {}) {
-    const now = options.now ?? new Date();
-    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);
-    const freshness = classifyCollectorFreshness(context, uploadSpool.last_upload_success_at, now);
-    const uploadState = !config
-        ? "not_installed"
-        : uploadSpool.pending_upload_count > 0
-            ? "retry_pending"
-            : session.session_state === "valid"
-                ? "ready"
-                : "local_only_missing_auth";
-    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 {
-        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,
-    };
-}
-function workDisplayLabel(context) {
-    const repoLabel = (context.repo_label ?? path.basename(context.repo)) || "workspace";
-    const worktreeLabel = context.worktree_label ?? repoLabel;
-    return `${repoLabel}/${worktreeLabel}`;
-}
-export async function readLocalCollectorConfig(paths) {
-    return LocalCollectorConfigSchema.parse(await readJsonFile(paths.config_file));
-}
-export async function readLocalWorkContext(paths) {
-    return LocalWorkContextSchema.parse(await readJsonFile(paths.active_work_context_file));
-}
-export async function readLocalWorkContextForRepo(paths, repoRoot) {
-    const identity = await resolveIdentityOrFallback(repoRoot);
-    const context = await readLocalWorkContextByFingerprint(paths, identity.worktree_fingerprint).catch(() => null);
-    if (context)
-        return context;
-    const active = await readLocalWorkContext(paths);
-    if (active.worktree_fingerprint === identity.worktree_fingerprint ||
-        path.resolve(active.repo) === identity.repo_root) {
-        return active;
-    }
-    throw new Error(`Active work context missing for ${identity.worktree_label}. Run \`cockpit start --workspace "${identity.repo_root}"\`.`);
-}
-async function readLocalWorkContextByFingerprint(paths, worktreeFingerprint) {
-    return LocalWorkContextSchema.parse(await readJsonFile(workContextFile(paths, worktreeFingerprint)));
-}
-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",
-        });
-    }
-}
-export async function readLocalCollectorSessionFile(paths) {
-    return LocalCollectorSessionFileSchema.parse(await readJsonFile(paths.session_file));
-}
-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";
-    }
-}
-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);
-}
-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),
-                }));
-            }
-        }));
-    }
-}
-function workContextFile(paths, worktreeFingerprint) {
-    return path.join(paths.work_contexts_dir, `${worktreeFingerprint}.json`);
-}
-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,
-    };
-}
-function stableWorkContextId(input) {
-    return `work-${sha256([
-        input.operatorId,
-        input.deviceId,
-        input.repoFingerprint,
-        input.worktreeFingerprint,
-    ].join(":")).slice(0, 32)}`;
-}
-function sha256(value) {
-    return crypto.createHash("sha256").update(value, "utf8").digest("hex");
-}
-/**
- * The one reader behind the config file, the session file and every work
- * context — and therefore the one place worth reporting from.
+ * The collector's own state on a machine — the durable on-disk contract behind
+ * `cockpit install`, `login`, `logout`, `start` and `status`.
  *
- * 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.
- */
-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;
-    }
-}
-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);
-    }
-}
-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);
-}
-function normalizeDashboardUrl(value) {
-    const normalized = value.trim().replace(/\/+$/, "");
-    if (!normalized)
-        throw new Error("Dashboard URL cannot be empty.");
-    return normalized;
-}
-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.
+ * This file is the table of contents and holds no logic. Each state family
+ * lives in a named sibling, and every public name below is still importable
+ * from `./local-state.js`, which is what ~90 modules and suites depend on:
  *
- * "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.
+ * - `local-state-paths.ts` — where every collector file lives, the owner-only
+ *   directory setup, and the per-worktree context filename.
+ * - `local-state-files.ts` — the ONE reader and ONE writer behind every state
+ *   file, and therefore the one place a corrupt file is reported from.
+ * - `local-state-config.ts` — `config.json`: install, ensure, read, the values
+ *   they default (collector version, dashboard URL, device name), and the one
+ *   on-disk migration of a retired raw-evidence choice.
+ * - `local-state-session.ts` — `session.json` read as a reference, with expiry
+ *   collapsed into the session state.
+ * - `local-state-pairing.ts` — `cockpit login` and `cockpit logout`: the two
+ *   operations that make and unmake that session file, plus the pair
+ *   start/poll HTTP client and its refusal message.
+ * - `local-state-identity.ts` — which repo and worktree a folder is, with the
+ *   path-derived fallback that keeps a non-git folder collectable.
+ * - `local-state-attributed-target.ts` — re-derives a caller-supplied identity
+ *   for a wrapper folder or a deleted repo before any context state is written.
+ * - `local-state-work-context.ts` — the active work context and the
+ *   per-worktree ones: what `cockpit start` bound, and the stable work id.
+ * - `local-state-status.ts` — `cockpit status`: the reading, the sentences an
+ *   operator reads, and the freshness classifier.
  *
- * 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.
+ * A new sibling here must also join `scripts/build-public-cli.mjs`
+ * `runtimeFiles`, or the repo tests stay green while the packed CLI breaks.
  */
-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 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,
-    });
-}
-function defaultDeviceName() {
-    return normalizeDeviceName(os.hostname()) ?? "Local machine";
-}
-function normalizeDeviceName(value) {
-    const trimmed = value?.trim().replace(/\s+/g, " ");
-    return trimmed ? trimmed.slice(0, 120) : undefined;
-}
-function normalizeOptionalEmail(value) {
-    const trimmed = value?.trim().toLowerCase();
-    return trimmed && trimmed.includes("@") ? trimmed : undefined;
-}
-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;
-}
-function isMissingFileError(error) {
-    return (error instanceof Error &&
-        "code" in error &&
-        error.code === "ENOENT");
-}
+export { getCollectorRuntimePaths } from "./local-state-paths.js";
+export { DEFAULT_DASHBOARD_URL, ensureLocalCollectorConfig, installLocalCollector, LOCAL_COLLECTOR_VERSION, readLocalCollectorConfig, } from "./local-state-config.js";
+export { readLocalCollectorSessionFile, readLocalSessionReference, } from "./local-state-session.js";
+export { logoutLocalCollector, pairLocalCollector, } from "./local-state-pairing.js";
+export { resolveGitBranch } from "./local-state-identity.js";
+export { readLocalWorkContext, readLocalWorkContextForRepo, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "./local-state-work-context.js";
+export { classifyCollectorFreshness, inspectLocalCollectorStatus, } from "./local-state-status.js";