@bli-cockpit/cli 0.2.52 → 0.2.53

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;
+}

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

@@ -0,0 +1,209 @@
+/**
+ * Reading both session stores, and settling what the reading owes.
+ *
+ * Codex and Claude are scanned once per tick each, under a window this step
+ * chooses: the normal live window, the 14-day first-run backfill, or all local
+ * history when a retry is pending. It also holds the BLI-3551 split that a
+ * scan's RETRY reason and a scan's FAILURE reason are two different claims —
+ * `repo_not_on_disk` widens the next window and never fails a sync.
+ */
+import path from "node:path";
+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 { CLAUDE_CURSOR_FILENAME } from "../cursors/raw-evidence-cursor.js";
+import { clearSourceRetryFailure, recordSourceRetryFailure, } from "../spool/local-spool.js";
+import { claudeAttributionReadFailureCount, codexAttributionReadFailureCount, } from "./agent-session-report.js";
+const CLAUDE_FIRST_RUN_BACKFILL_MINUTES = 14 * 24 * 60;
+/**
+ * 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.
+ */
+export 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 };
+}
+/**
+ * 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);
+    }
+}
+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,
+        },
+    };
+}
+async function fileExists(filePath) {
+    const { stat } = await import("node:fs/promises");
+    return stat(filePath).then(() => true, () => false);
+}

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

@@ -0,0 +1,12 @@
+/**
+ * The shapes one attributed sync pass hands from step to step.
+ *
+ * They live together, away from any step, because each one is a contract
+ * BETWEEN two steps: the plan the scan reads, the scan the upload reads, the
+ * upload the recorder reads. A step that owned its own output type would make
+ * the reader open the producer to learn what the consumer receives.
+ *
+ * Every name here is re-exported from `./session-sync.js`, which is the address
+ * callers already know.
+ */
+export {};