@bli-cockpit/cli 0.2.51 → 0.2.53

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.51");
+    writeLine(io?.stdout ?? process.stdout, "0.2.53");
     return 0;
   }
 

package/dist/commands/session-sync-attribution.js

@@ -0,0 +1,55 @@
+/**
+ * Which sessions live sync may collect, and which worktrees it collects them
+ * through.
+ *
+ * One place answers all four questions the rest of the pass asks about an
+ * attribution result: is this state collectable at all, does this result belong
+ * to the worktree currently syncing, which worktrees are targets this tick, and
+ * does a cursor entry still owe a retry. Live sync is reason-ALLOWLISTED where
+ * historical backfill is not, so these answers are deliberately narrower than
+ * the shared policy in `raw-evidence-attribution-policy.ts` and must not be
+ * re-derived anywhere else.
+ */
+import { isLiveRawEvidenceSyncAttribution } from "../raw-evidence-attribution-policy.js";
+/**
+ * Live sync remains reason-allowlisted even though historical backfill accepts
+ * every deterministic fallback state.
+ */
+export function isLiveSyncCollectableAttributionState(state, reason, hasApprovedWorkspace = false) {
+    return isLiveRawEvidenceSyncAttribution(state, reason, hasApprovedWorkspace);
+}
+export function liveSyncCursorEntryRequiresRetry(entry) {
+    return (!entry.uploaded_object_key &&
+        (isLiveSyncCollectableAttributionState(entry.state, entry.reason, Boolean(entry.worktree_fingerprint)) || entry.reason === "repo_not_on_disk"));
+}
+export function matchesLiveSyncWorktree(result, target) {
+    return (isLiveRawEvidenceSyncAttribution(result.state, result.reason, result.worktree !== null) &&
+        result.worktree !== null &&
+        liveSyncTargetKey(result.worktree) === liveSyncTargetKey(target));
+}
+export function liveSyncTargetKey(worktree) {
+    return `${worktree.repo_fingerprint}:${worktree.worktree_fingerprint}`;
+}
+/**
+ * Folder and deleted-repo fallbacks can intentionally synthesize a worktree
+ * identity that is not present in git discovery. Include those identities as
+ * sync targets so a wrapper-root session is not observed and then stranded.
+ */
+export function liveSyncTargetWorktrees(discovered, results) {
+    const targets = [...discovered];
+    const seen = new Set(discovered.map(liveSyncTargetKey));
+    for (const result of results) {
+        const targetKey = result.worktree
+            ? liveSyncTargetKey(result.worktree)
+            : null;
+        if (!isLiveSyncCollectableAttributionState(result.state, result.reason, result.worktree !== null) ||
+            !result.worktree ||
+            !targetKey ||
+            seen.has(targetKey)) {
+            continue;
+        }
+        seen.add(targetKey);
+        targets.push(result.worktree);
+    }
+    return targets;
+}

package/dist/commands/session-sync-failures.js

@@ -0,0 +1,140 @@
+/**
+ * The ONE place a sync writes down that something failed, and what it is called.
+ *
+ * Every reason label this pass can produce is written here and nowhere else, so
+ * the closed registry in `sync-health-class.ts` can be checked against a single
+ * file: `sync-health-class.test.ts` reads this source and refuses a label with
+ * no declared class (BLI-3551). Two consequences bind anyone editing this file:
+ * the ledger's methods keep the names `add` and `fail`, because that test reads
+ * those exact call shapes, and a new label goes in the registry first.
+ *
+ * The recorders below are the decision table itself — worktree delivery, source
+ * scan, the unposted session report, and the sentinel for a gate that fired
+ * without saying why.
+ */
+import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
+import { sourceScanFailureReason } from "./session-sync-scan.js";
+/**
+ * The label used when a sync fails and nothing on the way there said why.
+ *
+ * A deliberate sentinel rather than a fallback to `sync_failed`: it means the
+ * gate is real but its reason is unrecorded, which is a bug in this file, and
+ * it should be visible as one instead of blending into the generic bucket.
+ */
+export const SYNC_FAILED_WITHOUT_REASON = "sync_failed_reason_not_recorded";
+export function createSyncFailureLedger() {
+    const recordsByRenderedReason = new Map();
+    const add = (record) => {
+        if (!recordsByRenderedReason.has(record.rendered)) {
+            recordsByRenderedReason.set(record.rendered, record);
+        }
+    };
+    return {
+        add,
+        fail(condition, label, rendered = label) {
+            if (condition)
+                add({ label, rendered });
+        },
+        isEmpty: () => recordsByRenderedReason.size === 0,
+        sortedRecords: () => [...recordsByRenderedReason.values()].sort((a, b) => a.rendered.localeCompare(b.rendered)),
+    };
+}
+/**
+ * Every worktree that did not finish, and every raw-evidence gap it reported.
+ *
+ * The spooled reason is the most specific thing anyone has, so it leads, and it
+ * names the worktree it belongs to — a fleet failure is usually one repo, and
+ * "which one" is the first question asked.
+ */
+export function recordWorktreeDeliveryFailures(ledger, outcomes) {
+    for (const { worktree, sync } of outcomes) {
+        if (sync.status !== "uploaded") {
+            ledger.add(sync.status === "spooled" && sync.failure_reason
+                ? {
+                    label: sync.failure_class,
+                    rendered: `${worktree.worktree_label}:${sync.failure_reason}`,
+                    http_status: sync.failure_http_status,
+                }
+                : {
+                    label: "upload_not_completed",
+                    rendered: `${worktree.worktree_label}:upload_${sync.status}`,
+                });
+        }
+        for (const reason of sync.raw_evidence_failure_reasons ?? []) {
+            ledger.add({
+                label: "raw_evidence_upload_failed",
+                rendered: `raw_evidence:${reason}`,
+            });
+        }
+        for (const reason of sync.raw_evidence_retry_reasons ?? []) {
+            ledger.add({
+                label: "raw_evidence_retry_required",
+                rendered: `raw_evidence_retry:${reason}`,
+            });
+        }
+        ledger.fail(sync.raw_evidence_deferred_byte_budget > 0, "deferred_byte_budget");
+        ledger.fail(sync.raw_evidence_deferred_object_budget > 0, "deferred_object_budget");
+    }
+}
+/**
+ * What the scan itself got wrong: a window that hit its cap, sessions that
+ * could not be read, or a session store that could not be read at all.
+ *
+ * BLI-3551: the scan's RETRY reason and the scan's FAILURE reason are two
+ * different questions, and answering both with one function is what put
+ * `claude_scan:repo_not_on_disk` on every tick of three machines. A repo that
+ * is not on disk is a label on the session (the attribution umbrella finding:
+ * nothing was deleted, the transcript simply names a path git no longer
+ * knows). It still widens the next scan window; it is not a failed sync.
+ */
+export function recordSourceScanFailures(ledger, scan) {
+    const { codexAttribution, claudeAttribution } = scan;
+    ledger.fail(codexAttribution.session_limit_applied, "codex_session_limit_applied");
+    ledger.fail(claudeAttribution.session_limit_applied, "claude_session_limit_applied");
+    ledger.fail(codexAttributionReadFailureCount(codexAttribution) > 0, "codex_session_read_failed");
+    ledger.fail(claudeAttributionReadFailureCount(claudeAttribution) > 0, "claude_session_read_failed");
+    const codexScanFailure = sourceScanFailureReason("codex", codexAttribution);
+    if (codexScanFailure) {
+        ledger.add({
+            label: "codex_scan_read_failed",
+            rendered: `codex_scan:${codexScanFailure}`,
+        });
+    }
+    const claudeScanFailure = sourceScanFailureReason("claude_code", claudeAttribution);
+    if (claudeScanFailure) {
+        ledger.add({
+            label: "claude_scan_read_failed",
+            rendered: `claude_scan:${claudeScanFailure}`,
+        });
+    }
+}
+/**
+ * A report that was owed and did not go out — unless the reason it did not go
+ * out is that there was nothing inside the approved roots to report.
+ *
+ * BLI-3551: a tick that observed only sessions from outside the operator's
+ * approved roots has nothing to post, and that is the consent boundary
+ * working — not a failure. It used to fail as
+ * `session_report_unposted:no_successful_sync`, whose word "session" then
+ * classified as `auth_failed`; one machine reported a broken credential 377
+ * times in 38 hours while its token had eleven weeks left. The withhold
+ * decision itself is untouched (adapters/attribution-core.ts) — only what it
+ * is CALLED.
+ */
+export function recordUnpostedSessionReportFailure(ledger, options) {
+    const report = options.delivery.report;
+    ledger.fail(options.delivery.reportRequired &&
+        !report.posted &&
+        !options.explainedByNothingInRoot, "session_report_unposted", `session_report_unposted:${report.reason ?? "unknown"}`);
+}
+/**
+ * A gate that fired without recording a reason still has to say so. Reached
+ * only when `ok` is false and the ledger is empty, which is a bug in this
+ * family rather than a condition of the machine.
+ */
+export function recordUnexplainedFailure(ledger) {
+    ledger.add({
+        label: SYNC_FAILED_WITHOUT_REASON,
+        rendered: SYNC_FAILED_WITHOUT_REASON,
+    });
+}

package/dist/commands/session-sync-health.js

@@ -0,0 +1,102 @@
+/**
+ * The verdict on one tick — and the one true thing said about a tick that did
+ * not fail.
+ *
+ * This used to be a single boolean chain: correct, and completely mute. A
+ * failed sync exited 1 saying only `sync_failed`, which named no cause and
+ * supported no repair (BLI-2526). The conditions are unchanged; they are now
+ * asked in order, each answered by a recorder in `session-sync-failures.ts`
+ * that writes the closed-registry LABEL the health receipt is classified by.
+ * Nothing here parses a rendered sentence back apart.
+ */
+import { createSyncFailureLedger, recordSourceScanFailures, recordUnexplainedFailure, recordUnpostedSessionReportFailure, recordWorktreeDeliveryFailures, } from "./session-sync-failures.js";
+/**
+ * Decide whether this tick failed, and record every condition that decided it.
+ *
+ * The order below is the decision table: what delivery got wrong, what the scan
+ * got wrong, whether the report was owed, and only then whether the run is ok.
+ */
+export function decideSyncHealth(options) {
+    const { outcomes } = options.worktreePass;
+    const ledger = createSyncFailureLedger();
+    recordWorktreeDeliveryFailures(ledger, outcomes);
+    recordSourceScanFailures(ledger, options.scan);
+    const sessionsOutsideRoot = options.sessions.filter((session) => OUTSIDE_APPROVED_ROOT_REASONS.has(session.attribution_reason)).length;
+    const nothingInRoot = nothingInRootCount({
+        sessionCount: options.sessions.length,
+        outsideRootCount: sessionsOutsideRoot,
+        outcomes,
+        reportPosted: options.delivery.report.posted,
+        reportReason: options.delivery.report.reason,
+    });
+    recordUnpostedSessionReportFailure(ledger, {
+        delivery: options.delivery,
+        explainedByNothingInRoot: nothingInRoot !== null,
+    });
+    // `everyWorktreeUploaded` may already be false; the delivery recorder above
+    // re-derives that from the same outcomes, so the two agree by construction.
+    const ok = options.worktreePass.everyWorktreeUploaded && ledger.isEmpty();
+    if (!ok && ledger.isEmpty()) {
+        recordUnexplainedFailure(ledger);
+    }
+    const notice = ok && nothingInRoot !== null ? `nothing_in_root:${nothingInRoot}` : null;
+    if (nothingInRoot !== null && notice) {
+        announceNothingInRoot(nothingInRoot, options.collectionRootCount);
+    }
+    const records = ledger.sortedRecords();
+    return {
+        ok,
+        failure_reasons: records.map((record) => record.rendered),
+        failure_records: records,
+        notice,
+        sessions_outside_root: sessionsOutsideRoot,
+    };
+}
+/**
+ * Reasons attribution gives when a session's working directory is not inside
+ * any approved collection root.
+ *
+ * Exact labels, not a pattern — the same discipline the classifier now follows.
+ * `attribution-core.ts` writes both of these and nothing else means
+ * "outside the boundary".
+ */
+const OUTSIDE_APPROVED_ROOT_REASONS = new Set([
+    "cwd_outside_scanned_worktrees",
+    "no_matching_worktree_signals",
+]);
+/**
+ * How many observed sessions were outside the approved roots, when that
+ * accounts for ALL of them and nothing else went wrong — otherwise `null`.
+ *
+ * Deliberately narrow. It requires that no worktree was synced at all (so no
+ * upload could have succeeded or failed), that every session observed this tick
+ * names an outside-the-root reason, and that the unposted report is the
+ * `no_successful_sync` shape rather than a spooled report that failed to flush.
+ * Anything else keeps its failure.
+ */
+export function nothingInRootCount(options) {
+    if (options.reportPosted)
+        return null;
+    if (options.reportReason !== "no_successful_sync")
+        return null;
+    if (options.outcomes.length > 0)
+        return null;
+    if (options.sessionCount === 0)
+        return null;
+    return options.outsideRootCount === options.sessionCount
+        ? options.outsideRootCount
+        : null;
+}
+/**
+ * The success branch says something too: this is the receipt that proves a
+ * quiet machine is a working machine, and the count is what tells a coach that
+ * someone is working entirely outside the approved boundary.
+ */
+function announceNothingInRoot(sessionsOutsideRoot, collectionRootCount) {
+    console.error("[session-sync] nothing to collect inside the approved roots", JSON.stringify({
+        reason: "nothing_in_root",
+        sessions_outside_root: sessionsOutsideRoot,
+        collection_root_count: collectionRootCount,
+        next_action: "widen the approved roots (an operator decision) if this machine should be collecting here",
+    }));
+}

package/dist/commands/session-sync-plan.js

@@ -0,0 +1,81 @@
+/**
+ * What this tick is bound by before it reads a single session file.
+ *
+ * Every read here degrades on purpose: a missing or corrupt local file becomes
+ * an empty cursor or a null spool, because a collector that cannot read its own
+ * bookkeeping must still collect. The one decision this step makes that changes
+ * what gets collected is the retry width — whether a source reopens all local
+ * history instead of its normal live window.
+ */
+import { readLocalCollectorConfig, } from "../local-state.js";
+import { CLAUDE_CURSOR_FILENAME, emptyRawEvidenceCursorState, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { readLocalUploadSpoolState, } from "../spool/local-spool.js";
+import { liveSyncCursorEntryRequiresRetry } from "./session-sync-attribution.js";
+/**
+ * Read the local state this sync is bound by — config, both cursors, the upload
+ * spool — and turn it into the decisions the rest of the pass reads.
+ *
+ * Every read here degrades on purpose: a missing or corrupt local file becomes
+ * an empty cursor or a null spool, because a collector that cannot read its own
+ * bookkeeping must still collect.
+ */
+export async function planSyncFromLocalState(options) {
+    const config = await readLocalCollectorConfig(options.paths).catch(() => null);
+    const claudeEnabled = config?.collect_claude_jsonl !== false;
+    const collectionRoots = normalizeCollectionRoots(options.approvedCollectionRoots ?? config?.default_repo_paths ?? []);
+    const [codexCursorBefore, claudeCursorBefore, uploadSpool] = await Promise.all([
+        readRawEvidenceCursor(options.paths).catch(() => emptyRawEvidenceCursorState()),
+        claudeEnabled
+            ? readRawEvidenceCursor(options.paths, {
+                filename: CLAUDE_CURSOR_FILENAME,
+            }).catch(() => emptyRawEvidenceCursorState())
+            : Promise.resolve(emptyRawEvidenceCursorState()),
+        readLocalUploadSpoolState(options.paths).catch(() => null),
+    ]);
+    // A spooled upload from a CLI old enough not to have recorded its source
+    // could have come from either one, so both sources own it until it clears.
+    const legacyRetryPending = Boolean(uploadSpool?.pending_uploads.some((entry) => entry.raw_evidence_file_count > 0 && entry.retry_sources.length === 0));
+    const codexSourceRetryPending = sourceScanRetryIsPending(uploadSpool, "codex");
+    const claudeSourceRetryPending = sourceScanRetryIsPending(uploadSpool, "claude_code");
+    return {
+        claudeEnabled,
+        collectionRoots,
+        codexCursorBefore,
+        claudeCursorBefore,
+        uploadSpool,
+        codexSourceRetryPending,
+        claudeSourceRetryPending,
+        codexRetryPending: sourceHasPendingRetries("codex", uploadSpool, legacyRetryPending, codexSourceRetryPending, codexCursorBefore),
+        claudeRetryPending: claudeEnabled &&
+            sourceHasPendingRetries("claude_code", uploadSpool, legacyRetryPending, claudeSourceRetryPending, claudeCursorBefore),
+        allHistorySinceMinutes: allLocalHistorySinceMinutes(options.now),
+    };
+}
+function allLocalHistorySinceMinutes(now) {
+    // A cutoff just before the Unix epoch is effectively unbounded for Codex and
+    // Claude session files while keeping date arithmetic finite and portable.
+    return Math.ceil(now.getTime() / 60_000) + 24 * 60;
+}
+/** Whether the spool already recorded a source-scan retry for this source. */
+function sourceScanRetryIsPending(uploadSpool, source) {
+    return Boolean(uploadSpool?.pending_source_retries.some((entry) => entry.source === source));
+}
+/**
+ * Does this source have a reason to widen its scan window to all local
+ * history instead of the normal live-sync window? Used to be two separately
+ * written boolean chains, one per source, that happened to agree on shape by
+ * hand — asymmetric to read even though the rule is identical for both
+ * (BLI-3394): a legacy spooled upload with no recorded source, a scan-retry
+ * the spool already remembers, a spooled upload that names this source, or an
+ * undurable session this source's own cursor is still carrying.
+ */
+function sourceHasPendingRetries(source, uploadSpool, legacyRetryPending, sourceScanRetryPending, cursor) {
+    return (legacyRetryPending ||
+        sourceScanRetryPending ||
+        Boolean(uploadSpool?.pending_uploads.some((entry) => entry.retry_sources.includes(source))) ||
+        cursorHasUndurableCollectableSession(cursor));
+}
+function cursorHasUndurableCollectableSession(cursor) {
+    return Object.values(cursor.sessions).some((entry) => liveSyncCursorEntryRequiresRetry(entry));
+}

package/dist/commands/session-sync-record.js

@@ -0,0 +1,279 @@
+/**
+ * Writing down what this tick saw: the session report first, then both cursors.
+ *
+ * The order is the whole reason these live together. The report is queued to
+ * the spool BEFORE either cursor moves, so a process that dies in between
+ * leaves an exact retry copy behind rather than a cursor that has aged an
+ * unreported session out of the live window.
+ */
+import { describeError } from "../health-detail.js";
+import { flushPendingCodexSessionReports, queueCodexSessionReport, } from "../upload.js";
+import { CLAUDE_CURSOR_FILENAME, countStaleSessions, readRawEvidenceCursor, recordSessionObservation, writeRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
+import { liveSyncCursorEntryRequiresRetry } from "./session-sync-attribution.js";
+/**
+ * Report this tick's sessions and advance both cursors — in that order, which
+ * is the load-bearing part.
+ *
+ * The report is queued to the spool BEFORE either cursor moves. If the process
+ * exits in between, the spool keeps an exact retry copy; if queueing itself
+ * fails, the cursors stay at their prior retryable positions instead of aging
+ * an unreported session out of the live window.
+ */
+export async function reportSessionsAndAdvanceCursors(options) {
+    const hadPendingSessionReports = (options.plan.uploadSpool?.pending_session_reports.length ?? 0) > 0;
+    const queuedCurrentSessionReport = await queueSessionReportForDelivery({
+        homeDir: options.run.homeDir,
+        outcomes: options.outcomes,
+        sessions: options.sessions,
+        now: options.now,
+    });
+    const staleCounts = await recordBothSourceCursorObservations({
+        paths: options.paths,
+        plan: options.plan,
+        scan: options.scan,
+        sessions: options.sessions,
+        now: options.now,
+    });
+    const report = await deliverOrExplainSessionReport({
+        hadPendingSessionReports,
+        queuedCurrentSessionReport,
+        sessionCount: options.sessions.length,
+        homeDir: options.run.homeDir,
+        fetchImpl: options.run.fetchImpl,
+        now: options.now,
+    });
+    return {
+        report,
+        reportRequired: options.sessions.length > 0 ||
+            hadPendingSessionReports ||
+            queuedCurrentSessionReport,
+        ...staleCounts,
+    };
+}
+/**
+ * Persist the metadata-only session report to the spool, before either source
+ * cursor advances.
+ *
+ * If the process exits after this point, the spool keeps an exact retry copy.
+ * If queueing itself fails, the cursors remain at their prior retryable
+ * positions instead of aging an unreported session out of the live window.
+ * Returns whether a report for THIS tick was queued.
+ */
+async function queueSessionReportForDelivery(options) {
+    const firstUploaded = options.outcomes.find((outcome) => outcome.sync.status === "uploaded");
+    if (!firstUploaded || options.sessions.length === 0)
+        return false;
+    const queued = await queueCodexSessionReport({
+        homeDir: options.homeDir,
+        dashboardUrl: firstUploaded.sync.dashboard_url,
+        generatedAt: options.now.toISOString(),
+        workContextId: firstUploaded.sync.work_context_id,
+        repoLabel: firstUploaded.worktree.repo_label,
+        branch: firstUploaded.worktree.branch,
+        repoFingerprint: firstUploaded.worktree.repo_fingerprint,
+        repoOriginUrl: firstUploaded.worktree.repo_origin_url,
+        worktreeLabel: firstUploaded.worktree.worktree_label,
+        worktreeFingerprint: firstUploaded.worktree.worktree_fingerprint,
+        worktreeIsPrimary: firstUploaded.worktree.worktree_is_primary,
+        sessions: options.sessions,
+    });
+    return Boolean(queued);
+}
+/**
+ * Advance both source cursors to what this tick observed.
+ *
+ * The sessions cursor is an optimization; a broken local state dir must not
+ * turn an already-completed sync into a CLI crash, so each side is best-effort
+ * and names its own failure.
+ */
+async function recordBothSourceCursorObservations(options) {
+    const codexStaleCount = await recordCodexSessionObservationsForSync({
+        paths: options.paths,
+        codexAttribution: options.scan.codexAttribution,
+        sessions: options.sessions,
+        now: options.now,
+        priorCursor: options.plan.codexCursorBefore,
+        codexRetryPending: options.plan.codexRetryPending,
+    });
+    const claudeStaleCount = await recordClaudeSessionObservationsForSync({
+        claudeEnabled: options.plan.claudeEnabled,
+        paths: options.paths,
+        claudeAttribution: options.scan.claudeAttribution,
+        sessions: options.sessions,
+        now: options.now,
+        claudeCursorBefore: options.plan.claudeCursorBefore,
+        claudeRetryPending: options.plan.claudeRetryPending,
+    });
+    return { codexStaleCount, claudeStaleCount };
+}
+/**
+ * Flush the queued session reports — or, when there is nothing queued, say why
+ * nothing was posted instead of returning a bare false.
+ */
+async function deliverOrExplainSessionReport(options) {
+    if (!options.hadPendingSessionReports && !options.queuedCurrentSessionReport) {
+        return {
+            posted: false,
+            reason: options.sessionCount === 0
+                ? "no_sessions_observed"
+                : "no_successful_sync",
+        };
+    }
+    return flushPendingCodexSessionReports({
+        homeDir: options.homeDir,
+        fetch: options.fetchImpl,
+        now: options.now,
+    });
+}
+/**
+ * Record this sync's Codex session observations into the Codex cursor and
+ * return the stale count. Best-effort by design: a broken local state dir
+ * must not turn an already-completed sync into a CLI crash, so a failure here
+ * only logs — the stale count simply keeps whatever value it had when the
+ * failure happened (0 if the read itself failed).
+ *
+ * Reads the cursor fresh from disk right before recording rather than reusing
+ * `priorCursor`, so a concurrent writer's update is not clobbered. Claude's
+ * counterpart does not do this extra read (see
+ * `recordClaudeSessionObservationsForSync`) — a real, intentional asymmetry
+ * kept as-is rather than forced to match.
+ */
+async function recordCodexSessionObservationsForSync(options) {
+    let staleCount = 0;
+    try {
+        const codexCursor = await readRawEvidenceCursor(options.paths);
+        staleCount = recordSourceObservations({
+            cursor: codexCursor,
+            results: options.codexAttribution.results,
+            sessions: options.sessions,
+            source: "codex",
+            sessionIdOf: (result) => result.codex_session_id,
+            now: options.now,
+            priorCursor: options.priorCursor,
+            terminalizeMissingUndurable: options.codexRetryPending &&
+                codexAttributionReadFailureCount(options.codexAttribution) === 0,
+        });
+        codexCursor.updated_at = options.now.toISOString();
+        await writeRawEvidenceCursor(options.paths, codexCursor);
+    }
+    catch (error) {
+        // Best-effort: stale counts read 0 and observations re-record next sync —
+        // which is fine ONCE. A cursor write that keeps failing means the sessions
+        // cursor never advances, every sync re-does the same work, and the only
+        // symptom is a stale count that is permanently zero (BLI-3238).
+        console.error("[session-sync] Codex session observations were not recorded", JSON.stringify({
+            reason: "session_cursor_update_failed",
+            source: "codex",
+            session_count: options.sessions.length,
+            ...describeError(error),
+        }));
+    }
+    return staleCount;
+}
+/**
+ * Record this sync's Claude session observations into the Claude cursor and
+ * return the stale count — the Claude counterpart to
+ * `recordCodexSessionObservationsForSync`. A no-op returning 0 when Claude
+ * collection is disabled, matching the source-scan side's own disabled state.
+ */
+async function recordClaudeSessionObservationsForSync(options) {
+    if (!options.claudeEnabled)
+        return 0;
+    let staleCount = 0;
+    try {
+        staleCount = recordSourceObservations({
+            cursor: options.claudeCursorBefore,
+            results: options.claudeAttribution.results,
+            sessions: options.sessions,
+            source: "claude_code",
+            sessionIdOf: (result) => result.claude_session_id,
+            now: options.now,
+            priorCursor: options.claudeCursorBefore,
+            terminalizeMissingUndurable: options.claudeRetryPending &&
+                claudeAttributionReadFailureCount(options.claudeAttribution) === 0,
+        });
+        options.claudeCursorBefore.updated_at = options.now.toISOString();
+        await writeRawEvidenceCursor(options.paths, options.claudeCursorBefore, {
+            filename: CLAUDE_CURSOR_FILENAME,
+            sessionsOnly: true,
+        });
+    }
+    catch (error) {
+        // Best-effort: a broken Claude cursor must not fail the sync. It must
+        // still say it is broken — otherwise the Claude half of collection
+        // quietly repeats itself forever.
+        console.error("[session-sync] Claude session observations were not recorded", JSON.stringify({
+            reason: "session_cursor_update_failed",
+            source: "claude_code",
+            session_count: options.sessions.length,
+            ...describeError(error),
+        }));
+    }
+    return staleCount;
+}
+/**
+ * Records per-source session observations into its cursor and returns the stale
+ * count. Damped/reused Claude sessions carry forward their prior upload
+ * timestamp + byte size so the 6h damping window keeps counting from the real
+ * last upload (otherwise a slowly-growing file would never re-upload — D21).
+ */
+function recordSourceObservations(options) {
+    const seen = new Set(options.results.map((result) => options.sessionIdOf(result)));
+    if (options.terminalizeMissingUndurable) {
+        for (const [sessionId, entry] of Object.entries(options.cursor.sessions)) {
+            if (seen.has(sessionId) ||
+                !liveSyncCursorEntryRequiresRetry(entry)) {
+                continue;
+            }
+            options.cursor.sessions[sessionId] = {
+                ...entry,
+                state: "skipped",
+                reason: "retry_source_missing",
+                last_seen_at: options.now.toISOString(),
+            };
+        }
+    }
+    const stale = countStaleSessions(options.cursor, seen);
+    for (const result of options.results) {
+        const sessionId = options.sessionIdOf(result);
+        const reported = options.sessions.find((session) => session.source === options.source &&
+            session.codex_session_id === sessionId);
+        const uploadedThisSync = reported?.upload_state === "uploaded";
+        const durableThisSync = reported?.upload_state === "uploaded" ||
+            reported?.upload_state === "reused_existing";
+        const prior = options.priorCursor?.sessions[sessionId];
+        // D21 / no-flip-flop: a sync that is spooled (offline), budget-deferred, or
+        // upload-failed for a session that was ALREADY durable must NOT wipe the
+        // prior durable state — otherwise damping is forfeited forever and the
+        // store row oscillates uploaded -> not_uploaded hourly. Carry the prior
+        // durable pointer/timestamp/size forward unless we durably uploaded anew.
+        const uploadedObjectKey = durableThisSync
+            ? (reported?.raw_evidence_pointer_id ?? prior?.uploaded_object_key ?? null)
+            : (prior?.uploaded_object_key ?? null);
+        const uploadedAt = uploadedThisSync
+            ? options.now.toISOString()
+            : (prior?.uploaded_at ?? (durableThisSync ? options.now.toISOString() : null));
+        const uploadedByteSize = uploadedThisSync
+            ? result.byte_size
+            : (prior?.uploaded_byte_size ??
+                (durableThisSync ? result.byte_size : null));
+        const entry = {
+            file_hash_sha256: result.content_hash_sha256,
+            file_mtime_ms: result.session_file_mtime_ms,
+            byte_size: result.byte_size,
+            // Durable byte offset reflects how many bytes are durable remotely (the
+            // last uploaded size), not the current file size.
+            byte_offset: uploadedByteSize ?? 0,
+            state: result.state,
+            reason: result.reason,
+            worktree_fingerprint: result.worktree?.worktree_fingerprint ?? null,
+            uploaded_object_key: uploadedObjectKey,
+            uploaded_at: uploadedAt,
+            uploaded_byte_size: uploadedByteSize,
+            last_seen_at: options.now.toISOString(),
+        };
+        recordSessionObservation(options.cursor, sessionId, entry);
+    }
+    return stale;
+}