@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/commands/backfill-result.js

@@ -0,0 +1,150 @@
+import { BACKFILL_UPLOAD_BATCH_SESSIONS, uploadableCandidates, } from "./backfill-batches.js";
+import { backfillRetryCommand } from "./backfill-command-line.js";
+import { selectedSources } from "./backfill-scope.js";
+/**
+ * Someone else is already holding a lock this run needs. Reported as blocked
+ * with nothing done rather than as a failure — the scan is still valid, and
+ * the retry command in it works as soon as the other run finishes.
+ */
+export function lockHeldResult(command, scanned, blocker) {
+    return {
+        ...baseBackfillResult(command, backfillResultBaseArgs(scanned)),
+        status: "blocked",
+        retry_command: scanned.retryCommand,
+        failure_reason: blocker.failureReason,
+        blocked_at: {
+            what: blocker.what,
+            batch_index: 0,
+            batch_total: 0,
+            done: 0,
+            total: scanned.scan.candidates.length,
+        },
+    };
+}
+/** The `{now, dashboardUrl, sources, window, cursor, scan, reasonCounts}` bag every `baseBackfillResult` call needs. */
+export function backfillResultBaseArgs(ctx) {
+    return {
+        now: ctx.now,
+        dashboardUrl: ctx.dashboardUrl,
+        sources: ctx.sources,
+        window: ctx.window,
+        cursor: ctx.cursor,
+        scan: ctx.scan,
+        reasonCounts: ctx.reasonCounts,
+    };
+}
+export function baseBackfillResult(command, options) {
+    const states = countBy(options.scan.candidates, (candidate) => candidate.state);
+    const uploadable = uploadableCandidates(options.scan.candidates);
+    const perSource = {
+        codex: sourceCounts("codex", options.scan),
+        claude_code: sourceCounts("claude_code", options.scan),
+    };
+    return {
+        status: "complete",
+        dry_run: command.dryRun,
+        dashboard_url: options.dashboardUrl,
+        verify_url: `${options.dashboardUrl}/my-work`,
+        sources: options.sources,
+        window: options.window,
+        counts: {
+            total: options.scan.candidates.length,
+            uploadable: uploadable.length,
+            backfilled: 0,
+            skipped: options.scan.candidates.length - uploadable.length,
+            failed: 0,
+            deferred: 0,
+            remaining: 0,
+            states,
+            reasons: options.reasonCounts,
+            per_source: perSource,
+        },
+        batches: {
+            total: Math.ceil(uploadable.length / BACKFILL_UPLOAD_BATCH_SESSIONS),
+            completed: 0,
+            failed: 0,
+        },
+        resume_cursor: options.cursor,
+        retry_command: backfillRetryCommand(command),
+        report: emptyReport("not_posted"),
+        server_acknowledged: {
+            codex_session_report_recorded_count: 0,
+            raw_evidence_uploaded_object_count: 0,
+            raw_evidence_uploaded_chunk_count: 0,
+        },
+    };
+}
+export function blockedBackfillResult(command, options) {
+    return {
+        status: "blocked",
+        dry_run: command.dryRun,
+        dashboard_url: options.dashboardUrl,
+        verify_url: `${options.dashboardUrl}/my-work`,
+        sources: selectedSources(command.source),
+        window: {
+            mode: command.all ? "all" : "since_days",
+            since_days: command.sinceDays ?? null,
+            started_at: options.now.toISOString(),
+            paired_at: options.now.toISOString(),
+            since_minutes: 0,
+        },
+        counts: {
+            total: 0,
+            uploadable: 0,
+            backfilled: 0,
+            skipped: 0,
+            failed: 0,
+            deferred: 0,
+            remaining: 0,
+            states: {},
+            reasons: [],
+            per_source: {
+                codex: emptySourceCounts(),
+                claude_code: emptySourceCounts(),
+            },
+        },
+        batches: { total: 0, completed: 0, failed: 0 },
+        resume_cursor: options.cursor,
+        retry_command: backfillRetryCommand(command),
+        report: emptyReport("not_posted"),
+        server_acknowledged: {
+            codex_session_report_recorded_count: 0,
+            raw_evidence_uploaded_object_count: 0,
+            raw_evidence_uploaded_chunk_count: 0,
+        },
+        failure_reason: options.reason,
+    };
+}
+function sourceCounts(source, scan) {
+    const candidates = scan.candidates.filter((candidate) => candidate.source === source);
+    const scanned = source === "codex"
+        ? (scan.codexAttribution?.scanned_file_count ?? 0)
+        : (scan.claudeAttribution?.scanned_session_count ?? 0);
+    return {
+        scanned,
+        selected: candidates.length,
+        uploadable: uploadableCandidates(candidates).length,
+        states: countBy(candidates, (candidate) => candidate.state),
+    };
+}
+function emptySourceCounts() {
+    return { scanned: 0, selected: 0, uploadable: 0, states: {} };
+}
+export function emptyReport(reason) {
+    return {
+        posted: false,
+        reason,
+        chunk_count: 0,
+        recorded_count: 0,
+        failed_count: 0,
+        chunks: [],
+    };
+}
+function countBy(items, keyOf) {
+    const counts = {};
+    for (const item of items) {
+        const key = keyOf(item);
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    return counts;
+}

package/dist/commands/backfill-scan.js

@@ -0,0 +1,274 @@
+/**
+ * SCAN: read both archived session stores and turn them into the candidates
+ * this run will consider, then census what could not be accounted for.
+ *
+ * Two rules shape everything here. A store's own scan limit is a memory guard,
+ * not permission to leave history undiscovered, so a capped pass is rescanned
+ * in full. And a terminal session that never earned a durable pointer is
+ * reopened ahead of newer history, because a `--max-files` cap should be spent
+ * on what was missed before what merely arrived.
+ */
+import os from "node:os";
+import path from "node:path";
+import { scanAndAttributeClaudeSessions, } from "../adapters/claude-attribution.js";
+import { defaultCodexSessionDirs, scanAndAttributeCodexSessions, } from "../adapters/codex-attribution.js";
+import { emptyBackfillCursorState, prepareBackfillCursorForScope, readBackfillCursor, } from "../cursors/backfill-cursor.js";
+import { CLAUDE_CURSOR_FILENAME, readRawEvidenceCursor, } from "../cursors/raw-evidence-cursor.js";
+import { getCollectorRuntimePaths } from "../local-state.js";
+import { candidateCursorKey, compareBackfillCandidates, isAfterCursor, } from "./backfill-candidates.js";
+import { addReadOnlyGuardIssues, addRepoDiscoveryIssues, backfillScanIssues, countReadOnlyGuards, oversizedBackfillCandidateKeys, retryableCandidateKeys, sortScanIssuesByPriority, } from "./backfill-issues.js";
+import { reasonCountsFor } from "./backfill-reasons.js";
+import { blockedBackfillResult } from "./backfill-result.js";
+import { resolveBackfillScope } from "./backfill-scope.js";
+/**
+ * SCAN: is this machine paired, what roots/sources/window apply, and what did
+ * the archived Codex + Claude session stores actually contain. Returns either
+ * a terminal "not paired" result or everything PLAN/UPLOAD/REPORT need next.
+ */
+export async function scanBackfillRun(command, io, now) {
+    const paths = getCollectorRuntimePaths(command.homeDir);
+    const scope = await resolveBackfillScope(command, io, now, paths);
+    if (scope.kind === "not_paired") {
+        return {
+            kind: "blocked",
+            result: blockedBackfillResult(command, {
+                now,
+                dashboardUrl: scope.dashboardUrl,
+                reason: "collector_not_paired",
+                cursor: await readBackfillCursor(paths),
+            }),
+        };
+    }
+    const { collectionRoots, sources, worktreeDiscovery } = scope;
+    const storedCursor = command.dryRun
+        ? emptyBackfillCursorState()
+        : await readBackfillCursor(paths);
+    const scopedCursor = prepareBackfillCursorForScope(storedCursor, collectionRoots, sources);
+    const cursor = scopedCursor.cursor;
+    const pointerlessTerminalSessions = await loadPointerlessTerminalSessions(paths, sources);
+    const scan = await scanBackfillSessions({
+        command,
+        homeDir: command.homeDir ?? os.homedir(),
+        worktrees: worktreeDiscovery.worktrees,
+        collectionRoots,
+        sources,
+        window: scope.window,
+        cursor,
+        pointerlessTerminalSessions,
+        now,
+    });
+    const reasonCounts = await auditScannedCandidates(scan, worktreeDiscovery.incomplete_reasons);
+    return {
+        kind: "scanned",
+        now,
+        paths,
+        dashboardUrl: scope.dashboardUrl,
+        sources,
+        window: scope.window,
+        collectionRoots,
+        worktrees: worktreeDiscovery.worktrees,
+        retryCommand: scope.retryCommand,
+        scopedCursor,
+        cursor,
+        scan,
+        reasonCounts,
+        oversizedCandidateKeys: oversizedBackfillCandidateKeys(scan.candidates),
+    };
+}
+/**
+ * Finishes the scan's ledger before anything acts on it: adds what repo
+ * discovery could not enumerate, reads every candidate file once to find the
+ * ones this machine cannot actually deliver, and folds all of it into the
+ * reason table the operator sees. Mutates `scan` in place — it is the one
+ * owner of `issues` and `retryable_candidate_keys` — and returns the table.
+ */
+async function auditScannedCandidates(scan, discoveryIncompleteReasons) {
+    addRepoDiscoveryIssues(scan.issues, discoveryIncompleteReasons);
+    sortScanIssuesByPriority(scan.issues);
+    const guards = await countReadOnlyGuards(scan.candidates);
+    scan.retryable_candidate_keys = new Set([
+        ...scan.retryable_candidate_keys,
+        ...guards.retryable_candidate_keys,
+    ]);
+    addReadOnlyGuardIssues(scan.issues, guards.counts);
+    return reasonCountsFor(scan.candidates, guards.counts, scan.issues);
+}
+/**
+ * Reads both archived session stores and turns them into the candidates this
+ * run will consider: scan each selected store, keep what the cursor has not
+ * already resolved, order it, apply the operator's `--max-files` cap, then
+ * census what could not be accounted for.
+ */
+async function scanBackfillSessions(options) {
+    const scanLimit = options.command.maxFiles ?? 10_000;
+    const codexSessionDirs = defaultCodexSessionDirs(options.homeDir);
+    const claudeProjectsDir = path.join(options.homeDir, ".claude", "projects");
+    const codexAttribution = options.sources.includes("codex")
+        ? await scanCodexHistory(options, codexSessionDirs, scanLimit)
+        : null;
+    const claudeAttribution = options.sources.includes("claude_code")
+        ? await scanClaudeHistory(options, claudeProjectsDir, scanLimit)
+        : null;
+    const selection = selectBackfillCandidates({
+        codexAttribution,
+        claudeAttribution,
+        cursor: options.cursor,
+        pointerlessTerminalSessions: options.pointerlessTerminalSessions,
+        maxFiles: options.command.maxFiles,
+    });
+    const issues = await backfillScanIssues({
+        codexAttribution,
+        claudeAttribution,
+        codexSessionDirs,
+        claudeProjectsDir,
+        candidates: selection.candidates,
+        omittedCandidateCount: selection.omittedCandidateCount,
+    });
+    return {
+        candidates: selection.candidates,
+        codexAttribution,
+        claudeAttribution,
+        issues,
+        retryable_candidate_keys: retryableCandidateKeys(selection.candidates),
+        omitted_candidate_count: selection.omittedCandidateCount,
+    };
+}
+/**
+ * The adapter's own limit is a memory guard, not permission to silently leave
+ * history undiscovered. When it fires, re-scan the exact discovered population
+ * so a user-facing `--max-files` cap can resume from a truthful ordering.
+ */
+async function scanCodexHistory(request, sessionsDirs, scanLimit) {
+    const scan = (limit) => scanAndAttributeCodexSessions({
+        sessionsDirs,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_file_count));
+}
+/** Same rule for the Claude store: a capped first pass is rescanned in full. */
+async function scanClaudeHistory(request, projectsDir, scanLimit) {
+    const scan = (limit) => scanAndAttributeClaudeSessions({
+        projectsDir,
+        worktrees: request.worktrees,
+        now: request.now,
+        sinceMinutes: request.window.since_minutes,
+        limit,
+        collectionRoots: request.collectionRoots,
+    });
+    const firstPass = await scan(scanLimit);
+    if (!firstPass.session_limit_applied)
+        return firstPass;
+    return scan(Math.max(scanLimit + 1, firstPass.discovered_session_count));
+}
+/**
+ * Which scanned sessions this run will actually work on. A session is in play
+ * if the cursor has not passed it, or if it is a terminal session that never
+ * earned a pointer and so deserves another attempt; those retries sort first
+ * so a `--max-files` cap spends its budget on them before newer history.
+ */
+function selectBackfillCandidates(options) {
+    const allCandidates = [
+        ...(options.codexAttribution?.results.map(normalizeCodexCandidate) ?? []),
+        ...(options.claudeAttribution?.results.map(normalizeClaudeCandidate) ?? []),
+    ]
+        .filter((candidate) => isAfterCursor(candidate, options.cursor) ||
+        isPointerlessTerminalRetry(candidate, options.pointerlessTerminalSessions))
+        .sort((a, b) => compareBackfillCandidatesForRetry(a, b, options.pointerlessTerminalSessions));
+    const candidates = allCandidates.slice(0, options.maxFiles ?? Number.MAX_SAFE_INTEGER);
+    return {
+        candidates,
+        omittedCandidateCount: allCandidates.length - candidates.length,
+    };
+}
+async function loadPointerlessTerminalSessions(paths, sources) {
+    const [codexCursor, claudeCursor] = await Promise.all([
+        sources.includes("codex")
+            ? readRawEvidenceCursor(paths)
+            : Promise.resolve(null),
+        sources.includes("claude_code")
+            ? readRawEvidenceCursor(paths, { filename: CLAUDE_CURSOR_FILENAME })
+            : Promise.resolve(null),
+    ]);
+    const terminalIds = (sessions) => new Set(Object.entries(sessions ?? {})
+        .filter(([, entry]) => isPointerlessTerminalCursorEntry(entry))
+        .map(([sessionId]) => sessionId));
+    const result = {
+        codex: terminalIds(codexCursor?.sessions),
+        claude_code: terminalIds(claudeCursor?.sessions),
+    };
+    const count = result.codex.size + result.claude_code.size;
+    if (count > 0) {
+        console.error("[backfill] pointer-less terminal sessions reopened", JSON.stringify({
+            count,
+            codex_count: result.codex.size,
+            claude_count: result.claude_code.size,
+        }));
+    }
+    return result;
+}
+function isPointerlessTerminalCursorEntry(entry) {
+    return (!entry.uploaded_object_key &&
+        (entry.state === "ambiguous" ||
+            entry.state === "unattributed" ||
+            entry.state === "skipped"));
+}
+function isPointerlessTerminalRetry(candidate, sessions) {
+    return sessions[candidate.source].has(candidate.session_id);
+}
+function compareBackfillCandidatesForRetry(a, b, sessions) {
+    const aRetry = isPointerlessTerminalRetry(a, sessions);
+    const bRetry = isPointerlessTerminalRetry(b, sessions);
+    if (aRetry !== bRetry)
+        return aRetry ? -1 : 1;
+    if (aRetry && bRetry) {
+        return (a.session_file_mtime_ms - b.session_file_mtime_ms ||
+            candidateCursorKey(a).localeCompare(candidateCursorKey(b)));
+    }
+    return compareBackfillCandidates(a, b);
+}
+function normalizeCodexCandidate(result) {
+    return {
+        source: "codex",
+        session_id: result.codex_session_id,
+        file_path: result.file_path,
+        state: result.state,
+        reason: result.reason,
+        signals: result.signals,
+        attribution_score: result.attribution_score,
+        path_score: result.path_score,
+        content_hash_sha256: result.content_hash_sha256,
+        byte_size: result.byte_size,
+        session_file_mtime: result.session_file_mtime,
+        session_file_mtime_ms: result.session_file_mtime_ms,
+        worktree: result.worktree,
+        cwd_basename: result.cwd_basename,
+        cwd_hash: result.cwd_hash,
+    };
+}
+function normalizeClaudeCandidate(result) {
+    return {
+        source: "claude_code",
+        session_id: result.claude_session_id,
+        file_path: result.file_path,
+        state: result.state,
+        reason: result.reason,
+        signals: result.signals,
+        attribution_score: result.attribution_score,
+        path_score: result.path_score,
+        content_hash_sha256: result.content_hash_sha256,
+        byte_size: result.byte_size,
+        session_file_mtime: result.session_file_mtime,
+        session_file_mtime_ms: result.session_file_mtime_ms,
+        worktree: result.worktree,
+        cwd_basename: result.cwd_basename,
+        cwd_hash: result.cwd_hash,
+        claude: result,
+    };
+}

package/dist/commands/backfill-scope.js

@@ -0,0 +1,114 @@
+/**
+ * What this machine is allowed and able to back fill, before any session is
+ * read: is the collector paired, which approved roots and repos does it cover,
+ * which stores and how far back was it asked for, and can it reach the
+ * dashboard at all. Nothing here opens a transcript.
+ */
+import path from "node:path";
+import { readLocalCollectorConfig, readLocalCollectorSessionFile, readLocalSessionReference, } from "../local-state.js";
+import { DEFAULT_DISCOVERY_MAX_DEPTH, DEFAULT_DISCOVERY_MAX_REPOS, collectionRootPathAliases, discoverGitWorktreesInRootsWithStatus, } from "../repo-identity.js";
+import { normalizeCollectionRoots } from "../root-normalization.js";
+import { backfillDiscoveryRetryCommand } from "./backfill-command-line.js";
+const ALL_BACKFILL_SINCE_MINUTES = 20 * 365 * 24 * 60;
+/**
+ * Answers the four questions every later stage assumes: is this collector
+ * paired, which approved roots and repos does it cover, which stores and how
+ * far back was it asked for, and — on a dry run — can it even reach the
+ * dashboard. Nothing here reads a session; a machine that is not paired stops
+ * before any history is touched.
+ */
+export async function resolveBackfillScope(command, io, now, paths) {
+    const config = await readLocalCollectorConfig(paths);
+    const sessionFile = await readLocalCollectorSessionFile(paths);
+    const session = await readLocalSessionReference(paths);
+    if (session.session_state !== "valid") {
+        return {
+            kind: "not_paired",
+            dashboardUrl: sessionFile.dashboard_url ?? config.dashboard_url,
+        };
+    }
+    const pairedAt = parseRequiredDate(sessionFile.paired_at, "paired_at");
+    const dashboardUrl = normalizeDashboardUrl(sessionFile.dashboard_url ?? config.dashboard_url);
+    const roots = backfillCollectionRoots(command, config.default_repo_paths);
+    const collectionRoots = normalizeCollectionRoots(await collectionRootPathAliases(roots));
+    const worktreeDiscovery = await discoverBackfillWorktrees(collectionRoots, command);
+    const window = backfillWindow(command, now, pairedAt);
+    await validateBackfillReachability({
+        fetchImpl: io.fetch,
+        dashboardUrl,
+        dryRun: command.dryRun,
+    });
+    return {
+        kind: "ready",
+        dashboardUrl,
+        collectionRoots,
+        worktreeDiscovery,
+        retryCommand: backfillDiscoveryRetryCommand(command, worktreeDiscovery),
+        sources: selectedSources(command.source),
+        window,
+    };
+}
+function backfillCollectionRoots(command, savedRoots) {
+    if (command.repoRoot)
+        return [path.resolve(command.repoRoot)];
+    const roots = normalizeCollectionRoots(savedRoots);
+    if (roots.length === 0) {
+        throw new Error("No saved collection roots. Run `cockpit onboard --workspace <path>` or pass `cockpit backfill --workspace <path>`.");
+    }
+    return roots;
+}
+async function discoverBackfillWorktrees(roots, command) {
+    return discoverGitWorktreesInRootsWithStatus(roots, {
+        maxDepth: command.maxDepth ?? DEFAULT_DISCOVERY_MAX_DEPTH,
+        maxWorktrees: command.maxRepos ?? DEFAULT_DISCOVERY_MAX_REPOS,
+    });
+}
+export function selectedSources(source) {
+    if (source === "codex")
+        return ["codex"];
+    if (source === "claude")
+        return ["claude_code"];
+    return ["codex", "claude_code"];
+}
+function backfillWindow(command, now, pairedAt) {
+    if (command.all) {
+        return {
+            mode: "all",
+            since_days: null,
+            started_at: new Date(now.getTime() - ALL_BACKFILL_SINCE_MINUTES * 60_000)
+                .toISOString(),
+            paired_at: pairedAt.toISOString(),
+            since_minutes: ALL_BACKFILL_SINCE_MINUTES,
+        };
+    }
+    const requestedMs = now.getTime() - (command.sinceDays ?? 1) * 24 * 60 * 60_000;
+    const startedAtMs = Math.max(requestedMs, pairedAt.getTime());
+    const sinceMinutes = Math.max(1, Math.ceil((now.getTime() - startedAtMs) / 60_000));
+    return {
+        mode: "since_days",
+        since_days: command.sinceDays ?? null,
+        started_at: new Date(startedAtMs).toISOString(),
+        paired_at: pairedAt.toISOString(),
+        since_minutes: sinceMinutes,
+    };
+}
+async function validateBackfillReachability(options) {
+    if (!options.dryRun)
+        return;
+    const response = await options.fetchImpl(options.dashboardUrl, {
+        method: "HEAD",
+    });
+    if (response.status >= 500) {
+        throw new Error(`Dashboard reachability failed with HTTP ${response.status}.`);
+    }
+}
+function parseRequiredDate(value, label) {
+    const date = new Date(value);
+    if (!Number.isFinite(date.getTime())) {
+        throw new Error(`Collector session ${label} is invalid.`);
+    }
+    return date;
+}
+function normalizeDashboardUrl(value) {
+    return value.trim().replace(/\/+$/, "");
+}

package/dist/commands/backfill-session-report.js

@@ -0,0 +1,145 @@
+/**
+ * One attribution row per session this run saw, uploaded or not — the only
+ * record the server ever gets of a session the collector could not upload.
+ *
+ * Every branch names an outcome: a pointer when one exists, and otherwise WHY
+ * there is none (BLI-2107 for an attributed session, BLI-3272 for a refused
+ * one). Backfill is the path that revisits old sessions, so a silent branch
+ * here would keep rewriting the very NULL/NULL rows those tickets found.
+ */
+import { NO_UPLOAD_ATTEMPT_RECORDED, notUploadableAttributionStateReason, } from "@bli-cockpit/telemetry-core";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+/**
+ * One attribution row per session this run saw, uploaded or not — the only
+ * record the server ever gets of a session the collector could not upload.
+ * Exported for the BLI-3272 regression test; not part of the CLI surface.
+ */
+export function buildBackfillSessionReport(options) {
+    const uploads = indexMainTranscriptUploads(options.syncResults);
+    const bestBySession = bestCandidatePerSession(options.candidates);
+    return [...bestBySession.values()].map((candidate) => sessionAttributionRow(candidate, uploads, options.now));
+}
+function indexMainTranscriptUploads(syncResults) {
+    const bySourceAndSession = new Map();
+    const noUploadReasonBySessionId = new Map();
+    for (const sync of syncResults) {
+        if (sync.status !== "uploaded")
+            continue;
+        for (const outcome of sync.raw_evidence_outcomes) {
+            if (!outcome.codex_session_id)
+                continue;
+            const source = outcome.kind === "claude_jsonl"
+                ? "claude_code"
+                : outcome.kind === "codex_jsonl"
+                    ? "codex"
+                    : null;
+            if (!source)
+                continue;
+            if (!outcome.raw_evidence_pointer_id) {
+                if (outcome.reason) {
+                    noUploadReasonBySessionId.set(outcome.codex_session_id, outcome.reason);
+                }
+                continue;
+            }
+            bySourceAndSession.set(`${source}:${outcome.codex_session_id}`, {
+                upload_state: outcome.upload_state,
+                raw_evidence_pointer_id: outcome.raw_evidence_pointer_id,
+                reason: outcome.reason,
+            });
+        }
+    }
+    return { bySourceAndSession, noUploadReasonBySessionId };
+}
+/**
+ * One row per session, not per file: the same session can be scanned from
+ * several paths, so the best-attributed sighting wins and the most recent one
+ * breaks a tie.
+ */
+function bestCandidatePerSession(candidates) {
+    const bestByKey = new Map();
+    for (const candidate of candidates) {
+        const key = `${candidate.source}:${candidate.session_id}`;
+        const existing = bestByKey.get(key);
+        if (!existing || rank(candidate.state) > rank(existing.state)) {
+            bestByKey.set(key, candidate);
+        }
+        else if (existing &&
+            rank(candidate.state) === rank(existing.state) &&
+            candidate.session_file_mtime_ms > existing.session_file_mtime_ms) {
+            bestByKey.set(key, candidate);
+        }
+    }
+    return bestByKey;
+}
+function sessionAttributionRow(candidate, uploads, now) {
+    return {
+        codex_session_id: candidate.session_id,
+        source: candidate.source,
+        observed_at: now.toISOString(),
+        attribution_state: candidate.state,
+        attribution_reason: candidate.reason,
+        attribution_score: candidate.attribution_score,
+        path_score: candidate.path_score,
+        signals: candidate.signals,
+        ...(candidate.content_hash_sha256
+            ? { session_file_hash_sha256: candidate.content_hash_sha256 }
+            : {}),
+        session_file_byte_size: candidate.byte_size,
+        session_file_mtime: candidate.session_file_mtime,
+        ...(candidate.worktree
+            ? {
+                repo_fingerprint: candidate.worktree.repo_fingerprint,
+                worktree_fingerprint: candidate.worktree.worktree_fingerprint,
+                repo_label: candidate.worktree.repo_label,
+                branch: candidate.worktree.branch,
+            }
+            : {}),
+        ...(candidate.cwd_basename ? { cwd_basename: candidate.cwd_basename } : {}),
+        ...(candidate.cwd_hash ? { cwd_hash: candidate.cwd_hash } : {}),
+        ...sessionUploadFields(candidate, uploads),
+    };
+}
+/**
+ * The upload half of a report row. Every branch names an outcome: a pointer
+ * when one exists, and otherwise WHY there is none — BLI-2107 for an
+ * attributed session and BLI-3272 for a refused one. Backfill is the path that
+ * revisits old sessions, so a silent branch here would keep rewriting the very
+ * NULL/NULL rows those tickets found.
+ */
+function sessionUploadFields(candidate, uploads) {
+    const upload = uploads.bySourceAndSession.get(`${candidate.source}:${candidate.session_id}`);
+    if (upload) {
+        return {
+            raw_evidence_pointer_id: upload.raw_evidence_pointer_id,
+            upload_state: upload.upload_state,
+            ...(upload.upload_state === "upload_failed"
+                ? { upload_reason: upload.reason ?? NO_UPLOAD_ATTEMPT_RECORDED }
+                : {}),
+        };
+    }
+    const observedReason = uploads.noUploadReasonBySessionId.get(candidate.session_id);
+    const wasUploadable = isRawEvidenceUploadableAttributionState(candidate.state, candidate.worktree !== null);
+    return {
+        upload_state: "not_uploaded",
+        upload_reason: observedReason ??
+            (wasUploadable
+                ? NO_UPLOAD_ATTEMPT_RECORDED
+                : notUploadableAttributionStateReason(candidate.reason)),
+    };
+}
+function rank(state) {
+    switch (state) {
+        case "attributed":
+            return 5;
+        case "attributed_fallback":
+            return 4;
+        case "ambiguous":
+            return 3;
+        case "unattributed":
+            return 2;
+        case "skipped":
+            return 1;
+        default:
+            return 0;
+    }
+}

package/dist/commands/backfill-types.js

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