@bli-cockpit/cli 0.2.53 → 0.2.55

package/dist/adapters/claude-attribution-discovery.js

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { SESSION_FILE_UUID_PATTERN } from "./attribution-core.js";
+import { describeError } from "../health-detail.js";
+import { CLAUDE_SESSION_MAX_SIDECAR_FILES, } from "./claude-attribution-types.js";
+/**
+ * Walks `~/.claude/projects/<path-slug>/` for session mains and their
+ * `subagents/agent-*.jsonl` sidecars, within the D10 recency window. Purely a
+ * filesystem walk — nothing here reads a transcript's content.
+ */
+export async function discoverClaudeSessions(projectsDir, cutoffMs) {
+    const sessions = [];
+    const projectDirsSkipped = 0;
+    let projectDirReadFailedCount = 0;
+    let sessionStatFailedCount = 0;
+    let sidecarDirReadFailedCount = 0;
+    let sidecarStatFailedCount = 0;
+    // Same shape as the Codex walk: first reason plus counts, once. Per-file
+    // lines across a store of thousands would be their own silence (BLI-3238).
+    let firstDirectoryFailure = null;
+    let firstStatFailure = null;
+    let projectEntries;
+    try {
+        projectEntries = await fs.readdir(projectsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        // The whole projects root. Absent means Claude Code has never run here;
+        // anything else means every Claude session on this machine is invisible
+        // and the scan still reports a clean zero.
+        if (!isMissingPathError(error)) {
+            console.error("[claude-attribution] Claude projects root unreadable; no sessions can be seen", JSON.stringify({
+                reason: "projects_root_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return {
+            sessions,
+            projectDirsSkipped,
+            projectDirReadFailedCount: isMissingPathError(error) ? 0 : 1,
+            sessionStatFailedCount,
+            sidecarDirReadFailedCount,
+            sidecarStatFailedCount,
+        };
+    }
+    for (const projectEntry of projectEntries) {
+        if (!projectEntry.isDirectory())
+            continue;
+        const projectDir = path.join(projectsDir, projectEntry.name);
+        let sessionEntries;
+        try {
+            sessionEntries = await fs.readdir(projectDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (!isMissingPathError(error)) {
+                projectDirReadFailedCount += 1;
+                firstDirectoryFailure ??= describeError(error);
+            }
+            continue;
+        }
+        for (const sessionEntry of sessionEntries) {
+            if (!sessionEntry.isFile())
+                continue;
+            if (!SESSION_FILE_UUID_PATTERN.test(sessionEntry.name))
+                continue;
+            const mainFile = path.join(projectDir, sessionEntry.name);
+            let mainStat;
+            try {
+                mainStat = await fs.stat(mainFile);
+            }
+            catch (error) {
+                sessionStatFailedCount += 1;
+                firstStatFailure ??= describeError(error);
+                continue;
+            }
+            const sessionUuid = sessionEntry.name.replace(/\.jsonl$/i, "");
+            const sidecarDiscovery = await discoverSidecars(path.join(projectDir, sessionUuid, "subagents"));
+            const { sidecars, sidecarsCapped } = sidecarDiscovery;
+            sidecarDirReadFailedCount += sidecarDiscovery.dirReadFailedCount;
+            sidecarStatFailedCount += sidecarDiscovery.statFailedCount;
+            const recencyMs = Math.max(mainStat.mtimeMs, ...sidecars.map((sidecar) => sidecar.mtimeMs));
+            // D10: a session is recent if its main file OR any sidecar is in window.
+            if (recencyMs < cutoffMs)
+                continue;
+            sessions.push({
+                mainFile,
+                mainMtimeMs: mainStat.mtimeMs,
+                mainByteSize: mainStat.size,
+                recencyMs,
+                sidecars,
+                sidecarsCapped,
+            });
+        }
+    }
+    if (projectDirReadFailedCount > 0 || sessionStatFailedCount > 0) {
+        console.error("[claude-attribution] Claude sessions were invisible to the walk", JSON.stringify({
+            reason: "session_discovery_incomplete",
+            project_dir_read_failed_count: projectDirReadFailedCount,
+            session_stat_failed_count: sessionStatFailedCount,
+            found_session_count: sessions.length,
+            ...(firstDirectoryFailure
+                ? { first_directory_failure: firstDirectoryFailure }
+                : {}),
+            ...(firstStatFailure ? { first_stat_failure: firstStatFailure } : {}),
+        }));
+    }
+    return {
+        sessions,
+        projectDirsSkipped,
+        projectDirReadFailedCount,
+        sessionStatFailedCount,
+        sidecarDirReadFailedCount,
+        sidecarStatFailedCount,
+    };
+}
+async function discoverSidecars(subagentsDir) {
+    let entries;
+    try {
+        entries = await fs.readdir(subagentsDir, { withFileTypes: true });
+    }
+    catch (error) {
+        // Most sessions have no subagents at all, so absent is quiet. Anything
+        // else means the session is collected WITHOUT its subagent transcripts and
+        // nothing downstream can tell that from a session that had none.
+        if (!isMissingPathError(error)) {
+            console.error("[claude-attribution] subagent folder unreadable; sidecars omitted from this session", JSON.stringify({
+                reason: "sidecar_dir_unreadable",
+                ...describeError(error),
+            }));
+        }
+        return {
+            sidecars: [],
+            sidecarsCapped: 0,
+            dirReadFailedCount: isMissingPathError(error) ? 0 : 1,
+            statFailedCount: 0,
+        };
+    }
+    const discovered = [];
+    let statFailedCount = 0;
+    let firstSidecarStatFailure = null;
+    for (const entry of entries) {
+        // Only agent transcripts. `*.meta.json` carry operator-authored
+        // descriptions and are never harvested (D3).
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.startsWith("agent-") || !entry.name.endsWith(".jsonl")) {
+            continue;
+        }
+        const local_path = path.join(subagentsDir, entry.name);
+        let stat;
+        try {
+            stat = await fs.stat(local_path);
+        }
+        catch (error) {
+            statFailedCount += 1;
+            firstSidecarStatFailure ??= describeError(error);
+            continue;
+        }
+        discovered.push({
+            local_path,
+            file_name: entry.name,
+            mtimeMs: stat.mtimeMs,
+            byteSize: stat.size,
+        });
+    }
+    if (statFailedCount > 0) {
+        console.error("[claude-attribution] subagent transcripts skipped", JSON.stringify({
+            reason: "sidecar_stat_failed",
+            stat_failed_count: statFailedCount,
+            found_sidecar_count: discovered.length,
+            ...firstSidecarStatFailure,
+        }));
+    }
+    discovered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const capped = Math.max(0, discovered.length - CLAUDE_SESSION_MAX_SIDECAR_FILES);
+    return {
+        sidecars: discovered.slice(0, CLAUDE_SESSION_MAX_SIDECAR_FILES),
+        sidecarsCapped: capped,
+        dirReadFailedCount: 0,
+        statFailedCount,
+    };
+}
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/adapters/claude-attribution-score.js

@@ -0,0 +1,204 @@
+import crypto from "node:crypto";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { isRawEvidenceUploadableAttributionState } from "../raw-evidence-attribution-policy.js";
+import { describeError } from "../health-detail.js";
+import { isPathWithin, sanitizeSessionId, scoreSignalsAgainstWorktrees, sessionIdFromFileName, shortHash, } from "./attribution-core.js";
+import { extractClaudeSessionSignals, isSchemaDriftSuspected, streamMainSignals, } from "./claude-attribution-signals.js";
+import { CLAUDE_SESSION_MAX_FILE_BYTES, } from "./claude-attribution-types.js";
+/**
+ * Turns one discovered session into an attribution verdict: read (or, for an
+ * oversized main, stream) its signals, score them against the known
+ * worktrees, and validate its sidecars against the winning worktree.
+ */
+export async function attributeOneSession(session, worktrees, collectionRoots) {
+    const fileName = path.basename(session.mainFile);
+    const base = {
+        file_path: session.mainFile,
+        file_name: fileName,
+        claude_session_id: sessionIdFromFileName(fileName) ?? shortHash(session.mainFile),
+        cwd_basename: null,
+        cwd_hash: null,
+        session_file_mtime: new Date(session.mainMtimeMs).toISOString(),
+        session_file_mtime_ms: session.mainMtimeMs,
+        session_recency_ms: session.recencyMs,
+        byte_size: session.mainByteSize,
+        content_hash_sha256: null,
+        main_file_oversized: false,
+        oversized_lines_skipped: 0,
+        sidecars_capped: session.sidecarsCapped,
+        sidecar_files: [],
+    };
+    if (session.mainByteSize === 0) {
+        return skippedResult(base, "empty_file");
+    }
+    let signals;
+    const oversized = session.mainByteSize > CLAUDE_SESSION_MAX_FILE_BYTES;
+    if (oversized) {
+        // D7: stream the oversized main so metadata signals remain available. The
+        // bytes themselves are not uploaded until the collection ceiling changes.
+        let streamed;
+        try {
+            streamed = await streamMainSignals(session.mainFile);
+        }
+        catch (error) {
+            // A read race on one oversized main must not abort the whole scan; honor
+            // the per-file skip contract. Per session, so worth a line each time:
+            // this is a whole session nobody will ever coach on (BLI-3238).
+            console.error("[claude-attribution] oversized session could not be streamed, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "stream_oversized_main",
+                byte_size: session.mainByteSize,
+                ...describeError(error),
+            }));
+            return skippedResult(base, "file_read_failed");
+        }
+        signals = streamed.signals;
+        base.content_hash_sha256 = streamed.contentHash;
+        base.byte_size = streamed.byteSize;
+        base.main_file_oversized = true;
+        base.oversized_lines_skipped = streamed.oversizedLinesSkipped;
+    }
+    else {
+        let raw;
+        try {
+            raw = await fs.readFile(session.mainFile);
+        }
+        catch (error) {
+            console.error("[claude-attribution] session file unreadable, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "read_main",
+                byte_size: session.mainByteSize,
+                ...describeError(error),
+            }));
+            return skippedResult(base, "file_read_failed");
+        }
+        const content = raw.toString("utf8");
+        base.content_hash_sha256 = sha256(raw);
+        base.byte_size = raw.byteLength;
+        if (content.trim() === "") {
+            return skippedResult(base, "empty_file");
+        }
+        signals = extractClaudeSessionSignals(content);
+    }
+    const metaSessionId = sanitizeSessionId(signals.session_ids[0]);
+    if (metaSessionId) {
+        base.claude_session_id = metaSessionId;
+    }
+    const primaryCwd = signals.cwds[0] ?? null;
+    if (primaryCwd) {
+        base.cwd_basename = path.basename(primaryCwd) || null;
+        base.cwd_hash = shortHash(primaryCwd);
+    }
+    if (signals.line_count === 0 || signals.parse_error_count === signals.line_count) {
+        return {
+            ...base,
+            state: "unattributed",
+            reason: "jsonl_parse_failed",
+            signals: [],
+            attribution_score: 0,
+            path_score: 0,
+            worktree: null,
+        };
+    }
+    const outcome = scoreSignalsAgainstWorktrees({
+        cwds: signals.cwds,
+        workspaceRoots: [],
+        originUrls: signals.repository_urls,
+        branches: signals.branches,
+        headShas: [],
+    }, worktrees, { collectionRoots, originLabel: "pr_repo_match", pathExists: existsSync });
+    const extraSignals = [];
+    if (base.main_file_oversized)
+        extraSignals.push("main_file_oversized");
+    if (isSchemaDriftSuspected(signals))
+        extraSignals.push("schema_drift_suspected");
+    const sidecarFiles = isRawEvidenceUploadableAttributionState(outcome.state, outcome.worktree !== null) && outcome.worktree
+        ? await collectSidecarDiagnostics(session.sidecars, outcome.worktree)
+        : session.sidecars.map((sidecar) => ({
+            local_path: sidecar.local_path,
+            file_name: sidecar.file_name,
+            byte_size: sidecar.byteSize,
+            content_hash_sha256: null,
+            skipped_reason: null,
+        }));
+    return {
+        ...base,
+        state: outcome.state,
+        reason: outcome.reason,
+        signals: [...outcome.signals, ...extraSignals],
+        attribution_score: outcome.attribution_score,
+        path_score: outcome.path_score,
+        worktree: outcome.worktree,
+        sidecar_files: sidecarFiles,
+    };
+}
+/**
+ * Validates and content-addresses an attributed session's sidecars. Each
+ * sidecar's envelope cwd must resolve within the attributed worktree root, or
+ * it is skipped `sidecar_cwd_mismatch` rather than uploaded under the wrong
+ * work context. The secret guard and size cap run here too; a guarded or
+ * oversized sidecar is recorded with a reason and the session stays
+ * harvestable.
+ */
+async function collectSidecarDiagnostics(sidecars, worktree) {
+    const out = [];
+    for (const sidecar of sidecars) {
+        const entry = {
+            local_path: sidecar.local_path,
+            file_name: sidecar.file_name,
+            byte_size: sidecar.byteSize,
+            content_hash_sha256: null,
+            skipped_reason: null,
+        };
+        if (sidecar.byteSize > CLAUDE_SESSION_MAX_FILE_BYTES) {
+            out.push({ ...entry, skipped_reason: "file_too_large" });
+            continue;
+        }
+        let raw;
+        try {
+            raw = await fs.readFile(sidecar.local_path);
+        }
+        catch (error) {
+            // `file_read_failed` stays on the sidecar row. Beside it: a subagent
+            // transcript that was stat'd successfully seconds ago and now will not
+            // read is a race worth being able to recognise (BLI-3238).
+            console.error("[claude-attribution] subagent transcript unreadable, skipping it", JSON.stringify({
+                reason: "file_read_failed",
+                stage: "read_sidecar",
+                byte_size: sidecar.byteSize,
+                ...describeError(error),
+            }));
+            out.push({ ...entry, skipped_reason: "file_read_failed" });
+            continue;
+        }
+        const content = raw.toString("utf8");
+        const sidecarCwds = extractClaudeSessionSignals(content).cwds;
+        if (sidecarCwds.length > 0 &&
+            !sidecarCwds.some((cwd) => isPathWithin(cwd, worktree.repo_root))) {
+            out.push({ ...entry, skipped_reason: "sidecar_cwd_mismatch" });
+            continue;
+        }
+        out.push({
+            ...entry,
+            byte_size: raw.byteLength,
+            content_hash_sha256: sha256(raw),
+        });
+    }
+    return out;
+}
+function skippedResult(base, reason) {
+    return {
+        ...base,
+        state: "skipped",
+        reason,
+        signals: [],
+        attribution_score: 0,
+        path_score: 0,
+        worktree: null,
+    };
+}
+function sha256(value) {
+    return crypto.createHash("sha256").update(value).digest("hex");
+}

package/dist/adapters/claude-attribution-signals.js

@@ -0,0 +1,180 @@
+import crypto from "node:crypto";
+import { createReadStream } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { CONTENT_RECORD_TYPES, MAX_LINE_BUFFER_BYTES, SCHEMA_DRIFT_MIN_HIT_RATE, SCHEMA_DRIFT_MIN_RECORDS, } from "./claude-attribution-types.js";
+/**
+ * Allowlisted signal extraction, in-memory and streamed. Reads only `type`,
+ * `cwd`, `gitBranch`, `sessionId`, and `prRepository` (pr-link records).
+ * Structurally identical to the Codex extractor, with the allowlist enforced
+ * by construction — no generic record walk that could surface message bodies.
+ */
+export function extractClaudeSessionSignals(content) {
+    const accumulator = createSignalAccumulator();
+    for (const line of content.split("\n")) {
+        accumulator.processLine(line);
+    }
+    return accumulator.finalize();
+}
+function createSignalAccumulator() {
+    const sessionIds = new Set();
+    const cwds = new Set();
+    const branches = new Set();
+    const repositoryUrls = new Set();
+    let lineCount = 0;
+    let parseErrorCount = 0;
+    let contentRecordCount = 0;
+    let contentRecordsWithEnvelope = 0;
+    return {
+        processLine(line) {
+            if (!line.trim())
+                return;
+            lineCount += 1;
+            let record;
+            try {
+                record = JSON.parse(line);
+            }
+            catch {
+                // Deliberately silent (BLI-3238), same as the Codex line parser: per
+                // LINE across hundreds of thousands, the last line of a live session
+                // is routinely half-written, the count travels in `parseErrorCount` at
+                // the right grain, and the error would carry transcript text.
+                parseErrorCount += 1;
+                return;
+            }
+            if (!record || typeof record !== "object")
+                return;
+            const entry = record;
+            const type = typeof entry["type"] === "string" ? entry["type"] : "";
+            const cwd = stringOrNull(entry["cwd"]);
+            const sessionId = stringOrNull(entry["sessionId"]);
+            if (cwd)
+                cwds.add(cwd);
+            if (sessionId)
+                sessionIds.add(sessionId);
+            const branch = stringOrNull(entry["gitBranch"]);
+            if (branch)
+                branches.add(branch);
+            if (type === "pr-link") {
+                const repository = stringOrNull(entry["prRepository"]);
+                if (repository)
+                    repositoryUrls.add(normalizePrRepository(repository));
+            }
+            // D11 canary input: among content records, how many carry both cwd and
+            // sessionId. gitBranch is intentionally excluded — it is legitimately
+            // absent in non-git directories and would false-positive desktop sessions.
+            if (CONTENT_RECORD_TYPES.has(type)) {
+                contentRecordCount += 1;
+                if (cwd && sessionId)
+                    contentRecordsWithEnvelope += 1;
+            }
+        },
+        finalize() {
+            return {
+                session_ids: [...sessionIds],
+                cwds: [...cwds],
+                branches: [...branches],
+                repository_urls: [...repositoryUrls],
+                line_count: lineCount,
+                parse_error_count: parseErrorCount,
+                content_record_count: contentRecordCount,
+                envelope_field_hit_rate: contentRecordCount === 0
+                    ? 1
+                    : contentRecordsWithEnvelope / contentRecordCount,
+            };
+        },
+    };
+}
+export function isSchemaDriftSuspected(signals) {
+    // Only meaningful with enough records to be a signal, not noise.
+    if (signals.line_count < SCHEMA_DRIFT_MIN_RECORDS)
+        return false;
+    // A `type`-field rename yields zero recognized content records, which would
+    // otherwise leave the hit-rate defaulted to 1 and hide the most structural
+    // drift the canary exists to catch — flag a record-heavy file with no
+    // recognizable content records too.
+    if (signals.content_record_count === 0)
+        return true;
+    return signals.envelope_field_hit_rate < SCHEMA_DRIFT_MIN_HIT_RATE;
+}
+export async function streamMainSignals(filePath) {
+    const accumulator = createSignalAccumulator();
+    const hash = crypto.createHash("sha256");
+    let oversizedLinesSkipped = 0;
+    let byteSize = 0;
+    let pending = "";
+    let pendingTruncated = false;
+    const flushCompletedLine = (lineText) => {
+        if (pendingTruncated) {
+            // The line exceeded the metadata buffer; count it and continue. The raw
+            // evidence collector performs full-file sanitization before upload.
+            oversizedLinesSkipped += 1;
+            pending = "";
+            pendingTruncated = false;
+            return;
+        }
+        const full = pending + lineText;
+        pending = "";
+        accumulator.processLine(full);
+    };
+    // StringDecoder buffers an incomplete multibyte char across chunk boundaries
+    // so a UTF-8 character split by the read boundary never decodes to a fragment
+    // that could weaken the secret guard or corrupt a cwd signal. The content
+    // hash is over raw bytes (below) and is unaffected either way.
+    const decoder = new StringDecoder("utf8");
+    const consumeText = (text) => {
+        let remaining = text;
+        let newlineIndex = remaining.indexOf("\n");
+        while (newlineIndex !== -1) {
+            flushCompletedLine(remaining.slice(0, newlineIndex));
+            remaining = remaining.slice(newlineIndex + 1);
+            newlineIndex = remaining.indexOf("\n");
+        }
+        if (pendingTruncated)
+            return; // already over buffer; ignore until newline
+        if (pending.length + remaining.length > MAX_LINE_BUFFER_BYTES) {
+            pending = (pending + remaining).slice(0, MAX_LINE_BUFFER_BYTES);
+            pendingTruncated = true;
+        }
+        else {
+            pending += remaining;
+        }
+    };
+    await new Promise((resolve, reject) => {
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            hash.update(buffer);
+            byteSize += buffer.byteLength;
+            consumeText(decoder.write(buffer));
+        });
+        stream.on("end", () => {
+            const tail = decoder.end();
+            if (tail)
+                consumeText(tail);
+            if (pending.length > 0 || pendingTruncated)
+                flushCompletedLine("");
+            resolve();
+        });
+        stream.on("error", reject);
+    });
+    return {
+        signals: accumulator.finalize(),
+        oversizedLinesSkipped,
+        contentHash: hash.digest("hex"),
+        byteSize,
+    };
+}
+function normalizePrRepository(repository) {
+    const trimmed = repository
+        .trim()
+        .replace(/\.git$/i, "")
+        .replace(/^https?:\/\//i, "")
+        .replace(/^github\.com\//i, "")
+        .replace(/^\/+|\/+$/g, "")
+        .toLowerCase();
+    // GitHub-only by construction (D5); a non-GitHub origin simply never matches.
+    return `github.com/${trimmed}`;
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/adapters/claude-attribution-types.js

@@ -0,0 +1,25 @@
+import { RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES } from "@bli-cockpit/telemetry-core";
+/**
+ * The shapes and tuning constants `claude-attribution.ts` and its siblings
+ * (discovery, score, signals) all agree on. Kept in one module so none of
+ * them needs to import another to know what a session, a signal, or a
+ * discovered sidecar looks like.
+ */
+export const CLAUDE_ATTRIBUTION_DEFAULT_SINCE_MINUTES = 24 * 60;
+export const CLAUDE_ATTRIBUTION_DEFAULT_SESSION_LIMIT = 50;
+// Upload cap, NOT an attribution cap (D7): an oversized main file is still
+// scored and attributed via a streamed read; only the file's bytes stay local.
+export const CLAUDE_SESSION_MAX_FILE_BYTES = RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES;
+export const CLAUDE_SESSION_MAX_SIDECAR_FILES = 40;
+// JSONL lines holding a large tool result can be multi-MiB; a streamed read of
+// an oversized main caps the per-line buffer so one giant line cannot blow
+// memory. Lines over the cap are skipped + counted; the head is still guarded.
+export const MAX_LINE_BUFFER_BYTES = 2 * 1024 * 1024;
+export const SCHEMA_DRIFT_MIN_RECORDS = 20;
+export const SCHEMA_DRIFT_MIN_HIT_RATE = 0.5;
+export const CONTENT_RECORD_TYPES = new Set([
+    "user",
+    "assistant",
+    "system",
+    "attachment",
+]);