@bli-cockpit/cli 0.2.52 → 0.2.54

package/dist/commands/session-sync.js

@@ -1,217 +1,51 @@
-// Session attribution + ambient sync engine for the local collector. Split out
-// of commands/local.ts so the command runners read as a table of contents; this
-// is the core dual-source (Codex + Claude) scan/attribute/upload/report pass.
-//
-// `runAttributedWorktreeSync` is the whole story in nine steps, in the order the
-// pass runs them; everything below it is one of those steps. What a run REPORTS
-// — the per-session rows and the CLI funnel counts — lives next door in
-// `agent-session-report.ts` and is re-exported from here (BLI-3572).
+/**
+ * One attributed sync pass: scan both session stores, attribute what they hold,
+ * upload it through every target worktree, write down what happened, and judge
+ * the tick.
+ *
+ * This file is the sequence and nothing else. Each step lives in a named
+ * sibling, and every public name below is still importable from
+ * `./session-sync.js`, which is the address `sync.ts`, `onboard.ts`,
+ * `collection-report.ts` and the suites already use:
+ *
+ * - `session-sync-types.ts` — the shapes each step hands to the next.
+ * - `session-sync-plan.ts` — what this tick is bound by before it reads a
+ *   file: Claude on or off, the approved roots, both cursors, and how wide a
+ *   retry has to reopen the window.
+ * - `session-sync-attribution.ts` — which sessions live sync may collect and
+ *   which worktrees it collects them through, including the synthesized
+ *   fallback targets git discovery never produced.
+ * - `session-sync-scan.ts` — reading both session stores under the window the
+ *   plan chose, and settling each source's scan-retry bookkeeping.
+ * - `session-sync-upload.ts` — sending each worktree's transcripts under one
+ *   shared raw-evidence budget, with the Claude growth damper.
+ * - `session-sync-record.ts` — the session report, then both cursors, in that
+ *   order.
+ * - `session-sync-failures.ts` — the ONE place a label is written; the
+ *   class-lock test reads that file (BLI-3551).
+ * - `session-sync-health.ts` — the verdict, and the notice a quiet-but-working
+ *   machine still emits.
+ *
+ * What a run REPORTS — the per-session rows and the CLI funnel counts — lives
+ * next door in `agent-session-report.ts` and is re-exported from here
+ * (BLI-3572). A new sibling must also join `scripts/build-public-cli.mjs`
+ * `runtimeFiles`, or the repo tests stay green while the packed CLI breaks.
+ */
 import os from "node:os";
-import path from "node:path";
-import { getCollectorRuntimePaths, readLocalCollectorConfig, startLocalWorkContext, startLocalWorkContextForAttributedTarget, } from "../local-state.js";
-import { describeError } from "../health-detail.js";
-import { buildAgentSessionReport, buildAgentSessionSummary, claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
-import { flushPendingCodexSessionReports, LocalUploadBlockedError, queueCodexSessionReport, syncLocalAmbientEnvelope, } from "../upload.js";
-import { CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT, CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES, defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
-import { scanAndAttributeClaudeSessions } from "../adapters/claude-attribution.js";
-import { RAW_EVIDENCE_DEFAULT_BYTE_BUDGET, RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET } from "../adapters/raw-evidence.js";
-import { CLAUDE_CURSOR_FILENAME, countStaleSessions, emptyRawEvidenceCursorState, readRawEvidenceCursor, recordSessionObservation, writeRawEvidenceCursor } from "../cursors/raw-evidence-cursor.js";
-import { normalizeCollectionRoots } from "../root-normalization.js";
-import { clearSourceRetryFailure, readLocalUploadSpoolState, recordSourceRetryFailure, } from "../spool/local-spool.js";
-import { isLiveRawEvidenceSyncAttribution } from "../raw-evidence-attribution-policy.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { buildAgentSessionReport, buildAgentSessionSummary, } from "./agent-session-report.js";
+import { planSyncFromLocalState } from "./session-sync-plan.js";
+import { scanAndAttributeBothSources } from "./session-sync-scan.js";
+import { syncEveryTargetWorktree } from "./session-sync-upload.js";
+import { reportSessionsAndAdvanceCursors } from "./session-sync-record.js";
+import { decideSyncHealth } from "./session-sync-health.js";
 // What a run reports lives in `agent-session-report.ts`; it is re-exported here
 // because `./session-sync.js` is the address every caller already knows.
 export { ATTRIBUTION_STATE_RANK, buildAgentSessionReport, } from "./agent-session-report.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";
-const CLAUDE_FIRST_RUN_BACKFILL_MINUTES = 14 * 24 * 60;
-const CLAUDE_DAMP_GROWTH_BYTES = 256 * 1024;
-const CLAUDE_DAMP_MAX_AGE_MS = 6 * 60 * 60 * 1000;
-/**
- * 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);
-}
-function cursorHasUndurableCollectableSession(cursor) {
-    return Object.values(cursor.sessions).some((entry) => liveSyncCursorEntryRequiresRetry(entry));
-}
-export function liveSyncCursorEntryRequiresRetry(entry) {
-    return (!entry.uploaded_object_key &&
-        (isLiveSyncCollectableAttributionState(entry.state, entry.reason, Boolean(entry.worktree_fingerprint)) || entry.reason === "repo_not_on_disk"));
-}
-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));
-}
-/**
- * Scan and attribute Codex sessions for this sync, widening the window to all
- * local history when a retry is pending. Codex has no first-run backfill
- * concept (that is a Claude-only window, see `scanClaudeSessionsForSync`) and
- * is always scanned, unlike Claude which can be disabled entirely.
- */
-async function scanCodexSessionsForSync(options) {
-    const sinceMinutes = options.retryPending
-        ? options.allHistorySinceMinutes
-        : CODEX_ATTRIBUTION_SCAN_WINDOW_MINUTES;
-    let scan = await scanAndAttributeCodexSessions({
-        sessionsDirs: defaultCodexSessionDirs(options.homeDir),
-        worktrees: options.worktrees,
-        now: options.now,
-        sinceMinutes,
-        limit: CODEX_ATTRIBUTION_SCAN_WINDOW_SESSION_LIMIT,
-        collectionRoots: options.collectionRoots,
-    });
-    if (scan.session_limit_applied) {
-        // Re-run once, bounded by exactly what the first pass discovered, so a
-        // capped scan still returns every session it found instead of silently
-        // truncating at the window's default limit.
-        scan = await scanAndAttributeCodexSessions({
-            sessionsDirs: defaultCodexSessionDirs(options.homeDir),
-            worktrees: options.worktrees,
-            now: options.now,
-            sinceMinutes,
-            limit: scan.discovered_file_count,
-            collectionRoots: options.collectionRoots,
-        });
-    }
-    return scan;
-}
-/**
- * Scan and attribute Claude sessions for this sync — the Claude counterpart to
- * `scanCodexSessionsForSync`. Disabled collection returns an empty scan
- * up front; a first sync (no cursor yet) widens the window to 14 days instead
- * of the normal 24h so it captures retroactive history.
- */
-async function scanClaudeSessionsForSync(options) {
-    if (!options.claudeEnabled)
-        return emptyClaudeScan();
-    const sinceMinutes = options.retryPending
-        ? options.allHistorySinceMinutes
-        : options.firstRunBackfill
-            ? CLAUDE_FIRST_RUN_BACKFILL_MINUTES
-            : undefined;
-    const projectsDir = path.join(options.homeDir, ".claude", "projects");
-    let scan = await scanAndAttributeClaudeSessions({
-        projectsDir,
-        worktrees: options.worktrees,
-        now: options.now,
-        collectionRoots: options.collectionRoots,
-        sinceMinutes,
-    });
-    if (scan.session_limit_applied) {
-        scan = await scanAndAttributeClaudeSessions({
-            projectsDir,
-            worktrees: options.worktrees,
-            now: options.now,
-            collectionRoots: options.collectionRoots,
-            sinceMinutes,
-            limit: scan.discovered_session_count,
-        });
-    }
-    return scan;
-}
-export function sourceScanRetryReason(source, scan) {
-    const reasons = new Set();
-    const failure = sourceScanFailureReason(source, scan);
-    if (failure)
-        reasons.add(failure);
-    // Kept HERE and nowhere else (BLI-3551): a repo that is not on disk is a
-    // reason to widen the next scan window, because the transcript fallback can
-    // still attribute it. It is not a reason to call this sync failed — see
-    // `sourceScanFailureReason`.
-    if (scan.results.some((result) => result.reason === "repo_not_on_disk")) {
-        reasons.add("repo_not_on_disk");
-    }
-    return reasons.size > 0 ? [...reasons].sort().join(",") : null;
-}
-/**
- * The part of the scan outcome that is a genuine FAILURE: the session store
- * itself could not be read, so sessions that exist were not seen.
- *
- * Split from {@link sourceScanRetryReason} in BLI-3551. The two used to be one
- * function, so `repo_not_on_disk` — a label the attribution umbrella finding
- * already established is not a defect (nothing was deleted; the transcript
- * names a path git no longer tracks) — failed the sync on every tick for three
- * operators. A retry hint and a failure are different claims.
- */
-export function sourceScanFailureReason(source, scan) {
-    const readFailureCount = source === "codex"
-        ? codexAttributionReadFailureCount(scan)
-        : claudeAttributionReadFailureCount(scan);
-    return readFailureCount > 0 ? `${source}_session_store_read_failed` : null;
-}
-async function reconcileSourceScanRetry(options) {
-    if (options.reason) {
-        await recordSourceRetryFailure(options.paths, {
-            source: options.source,
-            reason: options.reason,
-            attemptedAt: options.attemptedAt,
-        });
-        return;
-    }
-    if (options.pendingBefore) {
-        await clearSourceRetryFailure(options.paths, options.source, options.attemptedAt);
-    }
-}
-export function matchesLiveSyncWorktree(result, target) {
-    return (isLiveRawEvidenceSyncAttribution(result.state, result.reason, result.worktree !== null) &&
-        result.worktree !== null &&
-        liveSyncTargetKey(result.worktree) === liveSyncTargetKey(target));
-}
-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;
-}
+export { isLiveSyncCollectableAttributionState, liveSyncCursorEntryRequiresRetry, liveSyncTargetWorktrees, matchesLiveSyncWorktree, } from "./session-sync-attribution.js";
+export { sourceScanFailureReason, sourceScanRetryReason, } from "./session-sync-scan.js";
+export { SYNC_FAILED_WITHOUT_REASON } from "./session-sync-failures.js";
+export { nothingInRootCount } from "./session-sync-health.js";
 /**
  * Shared dual-source sync orchestration for single-repo and parent-folder
  * modes. Codex AND Claude Code sessions are scanned and attributed once across
@@ -295,781 +129,4 @@ export async function runAttributedWorktreeSync(options) {
         claudeAttribution: scan.claudeAttribution,
         summary,
     };
-}
-/**
- * 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.
- */
-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),
-    };
-}
-/**
- * Scan and attribute both session sources, then settle each source's scan-retry
- * bookkeeping against what the scan actually found.
- *
- * Codex first, Claude second, and Claude's first-run window is decided between
- * them because it depends on whether the Claude cursor file exists yet.
- */
-async function scanAndAttributeBothSources(options) {
-    const { plan } = options;
-    const codexAttribution = await scanCodexSessionsForSync({
-        homeDir: options.homeDir,
-        worktrees: options.worktrees,
-        now: options.now,
-        collectionRoots: plan.collectionRoots,
-        retryPending: plan.codexRetryPending,
-        allHistorySinceMinutes: plan.allHistorySinceMinutes,
-    });
-    // First run (D B.4 §8): without a Claude cursor yet, widen the window to 14
-    // days so the first sync captures retroactive history instead of only 24h.
-    const claudeCursorExists = await fileExists(path.join(options.paths.cursors_dir, CLAUDE_CURSOR_FILENAME));
-    const firstRunBackfill = plan.claudeEnabled && !claudeCursorExists;
-    const claudeAttribution = await scanClaudeSessionsForSync({
-        claudeEnabled: plan.claudeEnabled,
-        homeDir: options.homeDir,
-        worktrees: options.worktrees,
-        now: options.now,
-        collectionRoots: plan.collectionRoots,
-        retryPending: plan.claudeRetryPending,
-        allHistorySinceMinutes: plan.allHistorySinceMinutes,
-        firstRunBackfill,
-    });
-    await reconcileSourceScanRetry({
-        paths: options.paths,
-        source: "codex",
-        attemptedAt: options.now.toISOString(),
-        pendingBefore: plan.codexSourceRetryPending,
-        reason: sourceScanRetryReason("codex", codexAttribution),
-    });
-    if (plan.claudeEnabled) {
-        await reconcileSourceScanRetry({
-            paths: options.paths,
-            source: "claude_code",
-            attemptedAt: options.now.toISOString(),
-            pendingBefore: plan.claudeSourceRetryPending,
-            reason: sourceScanRetryReason("claude_code", claudeAttribution),
-        });
-    }
-    return { codexAttribution, claudeAttribution, firstRunBackfill };
-}
-/**
- * Sync every worktree this tick is responsible for, in order, under one shared
- * raw-evidence budget.
- *
- * The budget is per-sync (D7b), not per-worktree: a parent-folder sync over
- * many worktrees honors a single byte/object cap rather than N times it.
- */
-async function syncEveryTargetWorktree(options) {
-    const { run, scan } = options;
-    const syncWorktrees = liveSyncTargetWorktrees(run.worktrees, [
-        ...scan.codexAttribution.results,
-        ...scan.claudeAttribution.results,
-    ]);
-    const discoveredWorktreeKeys = new Set(run.worktrees.map(liveSyncTargetKey));
-    // sessionId -> prior durable pointer for damped sessions (drives the
-    // growth_damped count + the skip_main decision).
-    const dampedClaudePointers = new Map();
-    const rawEvidenceBudget = {
-        remainingBytes: RAW_EVIDENCE_DEFAULT_BYTE_BUDGET,
-        remainingObjects: RAW_EVIDENCE_DEFAULT_OBJECT_BUDGET,
-    };
-    const outcomes = [];
-    let everyWorktreeUploaded = true;
-    for (const worktree of syncWorktrees) {
-        const outcome = await syncOneWorktree({
-            run,
-            now: options.now,
-            plan: options.plan,
-            scan,
-            worktree,
-            syncWorktrees,
-            rawEvidenceBudget,
-            // A target git discovery never produced is one the fallback attribution
-            // synthesized, and it syncs through its own attributed work context.
-            isDiscoveredWorktree: discoveredWorktreeKeys.has(liveSyncTargetKey(worktree)),
-            recordDampedClaudeSession: (sessionId, priorPointer) => {
-                dampedClaudePointers.set(sessionId, priorPointer);
-            },
-        });
-        everyWorktreeUploaded =
-            everyWorktreeUploaded && outcome.sync.status === "uploaded";
-        outcomes.push(outcome);
-    }
-    return {
-        outcomes,
-        everyWorktreeUploaded,
-        claudePriorDurablePointers: claudeDurablePointersFromCursor(options.plan.claudeCursorBefore),
-        growthDampedSessionCount: dampedClaudePointers.size,
-    };
-}
-/** Every Claude session the cursor already holds a durable pointer for. */
-function claudeDurablePointersFromCursor(claudeCursorBefore) {
-    const pointersBySessionId = new Map();
-    for (const [sessionId, entry] of Object.entries(claudeCursorBefore.sessions)) {
-        if (entry.uploaded_object_key) {
-            pointersBySessionId.set(sessionId, entry.uploaded_object_key);
-        }
-    }
-    return pointersBySessionId;
-}
-/**
- * Sync one worktree's attributed transcripts, starting a work context first
- * when this target needs one.
- *
- * A newly cloned repo has no work context yet. Capture is permissive and ticket
- * binding comes later, so a `missing_context` refusal starts general ambient
- * capture for that repo and retries, instead of blocking every other repo's
- * sync until someone runs `cockpit start` by hand.
- */
-async function syncOneWorktree(options) {
-    const { run, worktree } = options;
-    const attributedSyntheticTarget = options.isDiscoveredWorktree
-        ? null
-        : worktree;
-    const contextOptions = {
-        homeDir: run.homeDir,
-        repoRoot: worktree.repo_root,
-        activeTicketId: run.activeTicketId,
-        operatorId: run.operatorId,
-        sessionId: run.sessionId,
-        ...(attributedSyntheticTarget ? {} : { branch: run.branch }),
-    };
-    const ensureContext = () => attributedSyntheticTarget
-        ? startLocalWorkContextForAttributedTarget(contextOptions, attributedSyntheticTarget)
-        : startLocalWorkContext(contextOptions);
-    let context = null;
-    if (run.startContexts || attributedSyntheticTarget) {
-        context = await ensureContext();
-    }
-    const syncOptions = ambientEnvelopeForWorktree(options);
-    let sync;
-    try {
-        sync = await syncLocalAmbientEnvelope(syncOptions);
-    }
-    catch (error) {
-        if (error instanceof LocalUploadBlockedError &&
-            error.blocker === "missing_context") {
-            context = await ensureContext();
-            sync = await syncLocalAmbientEnvelope(syncOptions);
-        }
-        else {
-            throw error;
-        }
-    }
-    return { worktree, context, sync };
-}
-/**
- * Assemble what one worktree is about to upload: its sibling worktree
- * inventory, its Codex mains, its Claude mains and sidecars, and its share of
- * the sync-wide raw-evidence budget.
- */
-function ambientEnvelopeForWorktree(options) {
-    const { run, worktree, scan } = options;
-    const claudeSessionFiles = claudeSessionFilesForWorktree({
-        worktree,
-        claudeResults: scan.claudeAttribution.results,
-        claudeCursorBefore: options.plan.claudeCursorBefore,
-        now: options.now,
-        recordDampedClaudeSession: options.recordDampedClaudeSession,
-    });
-    return {
-        homeDir: run.homeDir,
-        repoRoot: worktree.repo_root,
-        dashboardUrl: run.dashboardUrl,
-        worktreeInventory: worktreeInventoryForRepo(worktree, options.syncWorktrees),
-        codexSessionFiles: scan.codexAttribution.results
-            .filter((result) => matchesLiveSyncWorktree(result, worktree))
-            .map((result) => ({
-            local_path: result.file_path,
-            codex_session_id: result.codex_session_id,
-        })),
-        codexAttributionScan: scan.codexAttribution,
-        claudeSessionFiles,
-        claudeAttributionScan: scan.claudeAttribution,
-        rawEvidenceBudget: options.rawEvidenceBudget,
-        fetch: run.fetchImpl,
-    };
-}
-/**
- * This worktree's Claude mains and sidecars, with the growth damper applied.
- *
- * A damped main is still reported — `skip_main` means "do not re-upload the
- * body this tick", not "forget this session" — and its prior durable pointer is
- * recorded so the session report can say `reused_existing` instead of flipping
- * the row to not_uploaded.
- */
-function claudeSessionFilesForWorktree(options) {
-    return options.claudeResults
-        .filter((result) => matchesLiveSyncWorktree(result, options.worktree))
-        .map((result) => {
-        const damped = !result.main_file_oversized &&
-            shouldDampClaudeMain(result, options.claudeCursorBefore, options.now);
-        if (damped) {
-            options.recordDampedClaudeSession(result.claude_session_id, options.claudeCursorBefore.sessions[result.claude_session_id]
-                ?.uploaded_object_key ?? null);
-        }
-        return {
-            local_path: result.file_path,
-            claude_session_id: result.claude_session_id,
-            main_file_oversized: result.main_file_oversized,
-            skip_main: damped,
-            sidecar_files: result.sidecar_files
-                .filter((sidecar) => !sidecar.skipped_reason)
-                .map((sidecar) => ({ local_path: sidecar.local_path })),
-        };
-    });
-}
-/**
- * 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.
- */
-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,
-    });
-}
-/**
- * Decide whether this tick failed, and record every condition that decided it.
- *
- * This used to be one boolean chain: correct, and completely mute — a failed
- * sync exited 1 saying only `sync_failed` (BLI-2526). The conditions are the
- * same; they now write down what they decided, each beside the closed-registry
- * LABEL the health receipt is classified by (BLI-3551). Nothing parses the
- * rendered sentence back apart.
- */
-function decideSyncHealth(options) {
-    const { outcomes } = options.worktreePass;
-    const report = options.delivery.report;
-    const ledger = createSyncFailureLedger();
-    recordWorktreeDeliveryFailures(ledger, outcomes);
-    recordSourceScanFailures(ledger, options.scan.codexAttribution, options.scan.claudeAttribution);
-    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: report.posted,
-        reportReason: report.reason,
-    });
-    // 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.
-    ledger.fail(options.delivery.reportRequired && !report.posted && nothingInRoot === null, "session_report_unposted", `session_report_unposted:${report.reason ?? "unknown"}`);
-    // `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()) {
-        ledger.add({
-            label: SYNC_FAILED_WITHOUT_REASON,
-            rendered: SYNC_FAILED_WITHOUT_REASON,
-        });
-    }
-    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,
-    };
-}
-/**
- * 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.
- */
-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.
- */
-function recordSourceScanFailures(ledger, codexAttribution, claudeAttribution) {
-    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}`,
-        });
-    }
-}
-/**
- * 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",
-    }));
-}
-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)),
-    };
-}
-/**
- * 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;
-}
-/**
- * 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;
-}
-function shouldDampClaudeMain(result, cursor, now) {
-    const entry = cursor.sessions[result.claude_session_id];
-    if (!entry ||
-        !entry.uploaded_object_key ||
-        !entry.uploaded_at ||
-        entry.uploaded_byte_size == null) {
-        return false;
-    }
-    const grew = result.byte_size > entry.uploaded_byte_size;
-    if (!grew)
-        return false; // unchanged content reuses via the object cursor
-    const growth = result.byte_size - entry.uploaded_byte_size;
-    const ageMs = now.getTime() - Date.parse(entry.uploaded_at);
-    return (growth <= CLAUDE_DAMP_GROWTH_BYTES &&
-        Number.isFinite(ageMs) &&
-        ageMs <= CLAUDE_DAMP_MAX_AGE_MS);
-}
-function emptyClaudeScan() {
-    return {
-        results: [],
-        discovered_session_count: 0,
-        scanned_session_count: 0,
-        since_minutes: 0,
-        session_limit: 0,
-        session_limit_applied: false,
-        max_file_bytes: 0,
-        max_sidecar_files: 0,
-        max_line_buffer_bytes: 0,
-        project_dirs_skipped: 0,
-        project_dir_read_failed_count: 0,
-        session_stat_failed_count: 0,
-        sidecar_dir_read_failed_count: 0,
-        sidecar_stat_failed_count: 0,
-        disabled_reason: "claude_collection_disabled_by_config",
-        counts: {
-            attributed: 0,
-            attributed_fallback: 0,
-            ambiguous: 0,
-            unattributed: 0,
-            skipped: 0,
-            mains_oversized: 0,
-            oversized_lines_skipped: 0,
-            sessions_schema_drift: 0,
-            sidecars_capped: 0,
-        },
-    };
-}
-function worktreeInventoryForRepo(current, worktrees) {
-    return worktrees
-        .filter((worktree) => worktree.repo_fingerprint
-        ? worktree.repo_fingerprint === current.repo_fingerprint
-        : worktree.repo_label === current.repo_label)
-        .map((worktree) => ({
-        repo: worktree.repo_root,
-        repo_label: worktree.repo_label,
-        repo_fingerprint: worktree.repo_fingerprint,
-        repo_origin_url: worktree.repo_origin_url ?? undefined,
-        head_sha: worktree.head_sha ?? undefined,
-        worktree_label: worktree.worktree_label,
-        worktree_fingerprint: worktree.worktree_fingerprint,
-        worktree_is_primary: worktree.worktree_is_primary,
-        branch: worktree.branch,
-    }));
-}
-async function fileExists(filePath) {
-    const { stat } = await import("node:fs/promises");
-    return stat(filePath).then(() => true, () => false);
 }