@bli-cockpit/cli 0.2.94 → 0.2.95

package/dist/commands/sync-receipt.js

@@ -0,0 +1,138 @@
+import { writeLine } from "./cli-io.js";
+import { classifySyncFailureRecords, redactedSyncErrorDetail, } from "./install-receipts.js";
+import { runSyncLocked } from "./sync-run.js";
+import { inspectBackfillLock } from "../backfill-lock.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { acquireSyncLock } from "../sync-lock.js";
+/**
+ * Run the tick behind both locks and come back with what to report.
+ *
+ * Standing aside is not failing: both skip arms exit 0 and say which lock they
+ * stood aside for, because a machine that runs its backfill for an hour is
+ * healthy and must not read as an hour of broken syncs.
+ */
+export async function runSyncWithHealthReceipt(command, io) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const backfillLock = await inspectBackfillLock(paths);
+    if (backfillLock.held) {
+        return standAsideForBackfill(command, io, backfillLock.held_since);
+    }
+    // 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(paths);
+    if (!lock.acquired) {
+        return standAsideForRunningSync(command, io, lock.held_since);
+    }
+    try {
+        const run = await runSyncLocked(command, io);
+        return run.exitCode === 0 ? collectedReceipt(run) : failedReceipt(run);
+    }
+    finally {
+        await lock.handle.release();
+    }
+}
+/** The backfill owns the machine right now; say so and stand down. */
+function standAsideForBackfill(command, io, heldSince) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "live_sync_paused_during_backfill",
+            reason: "live sync paused during backfill",
+            held_since: heldSince,
+            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",
+        },
+    };
+}
+/** Another sync already holds the collection lock; say so and stand down. */
+function standAsideForRunningSync(command, io, heldSince) {
+    if (command.json) {
+        writeLine(io.stdout, JSON.stringify({
+            status: "sync_already_running",
+            reason: "another sync owns the collection lock",
+            held_since: heldSince,
+            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" },
+    };
+}
+/**
+ * The receipt for a run that came back clean.
+ *
+ * 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.
+ */
+function collectedReceipt(run) {
+    return {
+        exitCode: run.exitCode,
+        completion: {
+            step: "sync_complete",
+            status: "ok",
+            ...(run.notice ? { error_detail: run.notice } : {}),
+        },
+        heartbeat: { status: "ok", reason: run.notice, ...heartbeatCounts(run) },
+    };
+}
+/**
+ * The receipt for a run that came back non-zero.
+ *
+ * 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).
+ */
+function failedReceipt(run) {
+    const reasonText = run.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(run.failureRecords);
+    return {
+        exitCode: run.exitCode,
+        completion: {
+            step: "sync_complete",
+            status: "fail",
+            error_code: errorCode,
+            error_detail: redactedSyncErrorDetail(reasonText),
+        },
+        heartbeat: { status: "fail", reason: errorCode, ...heartbeatCounts(run) },
+    };
+}
+/** The counts the heartbeat carries so a quiet machine can explain itself. */
+function heartbeatCounts(run) {
+    return {
+        sessionsObserved: run.sessionsObserved,
+        sessionsOutsideRoot: run.sessionsOutsideRoot,
+        sessionsNewThisTick: run.sessionsNewThisTick,
+        sessionsPendingUpload: run.sessionsPendingUpload,
+    };
+}

package/dist/commands/sync-report.js

@@ -0,0 +1,153 @@
+import { writeLine } from "./cli-io.js";
+import { attributedSyncRunStatus, cursorStatusLine, displayTicketId, rawEvidenceSyncLine, shortSha, worktreeSyncRow, writeAgentSessionSummary, } from "./collection-report.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { rawEvidenceGcSummary, runRawEvidenceLocalGc, } from "../raw-evidence-gc.js";
+/**
+ * Report a run that touched more than one worktree.
+ *
+ * The per-worktree rows are the point: a parent sync is only as good as its
+ * weakest repo, and each row names its own failure reason.
+ */
+export 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).`);
+    writeWorktreeSyncRows(io, run);
+    writeAgentSessionSummary(io, run.summary);
+    if (gc && !gc.skipped)
+        writeLine(io.stdout, rawEvidenceGcSummary(gc));
+    return syncResult(run);
+}
+/**
+ * Report a run that found no git worktrees at all — a steady state, not a
+ * failure (the reasoning is at the branch that chooses this shape, in
+ * `sync-run.ts`). It still says what the session scan saw, and when everything
+ * it saw was outside the approved folders it says that in words.
+ */
+export 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);
+}
+/**
+ * Report the ordinary case: one worktree, three ways it can have gone.
+ *
+ * A clean run prints what landed, a partial one says to run the tick again,
+ * and a spooled one names the failure and the retry command — the operator's
+ * next move is on the screen in every branch.
+ */
+export 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) {
+        writeUploadedSessionLines(io, 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);
+}
+/** One line per worktree, on stdout when it uploaded and stderr when it did not. */
+function writeWorktreeSyncRows(io, run) {
+    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}`);
+    }
+}
+/** What one clean single-repo tick collected, in the order a person reads it. */
+function writeUploadedSessionLines(io, result) {
+    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));
+}
+/**
+ * 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,
+        sessionsNewThisTick: run.sessions_new_this_tick,
+        sessionsPendingUpload: run.sessions_pending_upload,
+    };
+}
+/** The local raw-evidence sweep a successful run earns before it reports. */
+async function runSyncRawEvidenceGc(command, io) {
+    return runRawEvidenceLocalGc(getCollectorRuntimePaths(command.homeDir), io.env);
+}

package/dist/commands/sync-roots.js

@@ -0,0 +1,28 @@
+/**
+ * Which approved roots this tick may collect (BLI-3982).
+ *
+ * Two steps ask the question — the run, which collects them, and the
+ * heartbeat, which labels the check-in with them — so it has one answer here
+ * rather than one each.
+ */
+import { collectionRootConsentAliases } from "./collection-roots.js";
+import { getCollectorRuntimePaths, readLocalCollectorConfig, } from "../local-state.js";
+import { CollectionRootRequiredError } from "../onboarding-roots.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+/**
+ * The roots this run is allowed to look at: what the operator typed, else what
+ * they consented to when they onboarded, else nothing — and nothing is an
+ * error, because a sync with no boundary has no business reading a disk.
+ */
+export 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.`);
+}

package/dist/commands/sync-run.js

@@ -0,0 +1,52 @@
+import { writeLine } from "./cli-io.js";
+import { discoverCommandWorktrees } from "./local-discovery.js";
+import { runAttributedWorktreeSync } from "./session-sync.js";
+import { reportMultiRepoSync, reportNoWorktreeSync, reportSingleRepoSync, } from "./sync-report.js";
+import { resolveSyncCollectionRoots } from "./sync-roots.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { rawEvidenceDedupSummary, sweepDuplicateStagedRawEvidence, } from "../raw-evidence-gc.js";
+/**
+ * Collect everything this tick may collect, then report it.
+ *
+ * The caller holds the collection lock for the whole of this function; nothing
+ * here acquires or releases one.
+ */
+export 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);
+}

package/dist/commands/sync-types.js

@@ -0,0 +1 @@
+export {};