@bli-cockpit/cli 0.2.49 → 0.2.51

package/dist/adapters/raw-evidence-facts.js

@@ -0,0 +1,338 @@
+/**
+ * How a pass ends, and what it says about itself when it does.
+ *
+ * Three endings, one report shape: nothing collected, a promoted pack, or a
+ * crash. All three return the same `RawEvidenceFacts` counts and an
+ * `evidence_completeness` payload carrying every gap the pass recorded, so a
+ * sync that collected nothing is legible rather than absent, and a crashed one
+ * is reported rather than silent.
+ *
+ * Two rules are load-bearing here:
+ *
+ * - **A pack is named by its content, never by when it ran** (BLI-3066).
+ *   Identical content on the next sync resolves to the identical directory.
+ * - **The manifest is an object of the pack like any other file**, content
+ *   hash in its key and all (BLI-3552). Keying it by pack id alone made one
+ *   key name different bytes, and `begin` then answered
+ *   `hash_mismatch_committed_object` on every sync forever.
+ *
+ * The pointers this module hands back are what the uploader delivers and what
+ * the server commits; `raw-evidence-manifest.ts` owns their shape.
+ */
+import { SourceScanResultSchema } from "@bli-cockpit/telemetry-core";
+import path from "node:path";
+import { makeSourceAdapterIdentity, } from "./common.js";
+import { contentKeyedRawEvidencePackId, recordStagedObject, } from "../raw-evidence-staging.js";
+import { sha256 } from "./raw-evidence-keys.js";
+import { countEvidenceEntries, makeEvidenceCompleteness, } from "./raw-evidence-completeness.js";
+import { evidenceEntry, pointerFromEntry, RAW_EVIDENCE_BUCKET, } from "./raw-evidence-manifest.js";
+import { persistStagingState, promoteStagedPack, stageManifest, } from "./raw-evidence-pack-store.js";
+import { discardStagingDir, } from "./raw-evidence-collection-state.js";
+// ---------------------------------------------------------------------------
+// The three ways a pass ends
+// ---------------------------------------------------------------------------
+/**
+ * Nothing collected: drop the staging directory instead of leaving an empty
+ * pack behind. This used to leave one empty `work-*` dir per sync.
+ */
+export async function finishWithEmptyPack(collection, options, run) {
+    await discardStagingDir(run.stagingDir);
+    collection.packId = contentKeyedRawEvidencePackId({
+        workContextId: collection.context.workContextId,
+        contentHashes: [],
+    });
+    await persistStagingState(options.stateDir, collection.staging, collection.context.now.toISOString());
+    const facts = makeEmptyPackFacts(collection, run.window);
+    return {
+        facts,
+        scan: makeRawEvidenceScan({
+            context: collection.context,
+            startedAt: run.window.startedAt,
+            status: "partial",
+            facts,
+        }),
+    };
+}
+export async function finishWithPromotedPack(collection, options, run) {
+    const context = collection.context;
+    const entries = collection.entries;
+    // The pack is named by what is in it, never by when it was made. Identical
+    // content on the next sync resolves to the identical directory, which is
+    // the whole fix for BLI-3066.
+    const packId = contentKeyedRawEvidencePackId({
+        workContextId: context.workContextId,
+        contentHashes: entries.map((entry) => entry.content_hash_sha256),
+    });
+    collection.packId = packId;
+    const promotion = await promoteStagedPack({
+        rawEvidenceRoot: collection.rawEvidenceRoot,
+        stagingDir: run.stagingDir,
+        packId,
+        workContextId: context.workContextId,
+        entries,
+    });
+    rebaseStagedEntriesOntoPack(collection, promotion.evidenceDir);
+    const manifestPath = await addManifestToPack(collection, promotion, packId);
+    await persistStagingState(options.stateDir, collection.staging, context.now.toISOString());
+    logPackStaged(collection, promotion, packId);
+    const facts = makePromotedPackFacts(collection, {
+        packId,
+        manifestPath,
+        promotion,
+        window: run.window,
+    });
+    return {
+        facts,
+        scan: makeRawEvidenceScan({
+            context,
+            startedAt: run.window.startedAt,
+            // A pack of nothing but its own manifest carries no evidence, so it
+            // reports partial however cleanly it was written.
+            status: entries.length > 1 ? "ok" : "partial",
+            facts,
+        }),
+    };
+}
+/** A pack with files: the same shell as an empty one, plus what is in it. */
+function makePromotedPackFacts(collection, place) {
+    const entries = collection.entries;
+    return {
+        ...packFactsShell(collection, {
+            packId: place.packId,
+            manifestPath: place.manifestPath,
+            evidenceDir: place.promotion.evidenceDir,
+            window: place.window,
+        }),
+        stage_state: place.promotion.state,
+        file_count: entries.length,
+        byte_size: totalByteSize(entries),
+        content_kinds: [...new Set(entries.map((entry) => entry.kind))],
+        pointers: entries.map(pointerFromEntry),
+        upload_files: entries.map(uploadFileFromEntry),
+    };
+}
+/**
+ * Write the manifest and make it an object of the pack like any other file, so
+ * the uploader has one list to walk. Returns where it landed.
+ */
+async function addManifestToPack(collection, promotion, packId) {
+    const context = collection.context;
+    const manifestPath = path.join(promotion.evidenceDir, "manifest.json");
+    const manifestBytes = await stageManifest({
+        context,
+        packId,
+        manifestPath,
+        entries: collection.entries,
+        skipped: collection.skipped,
+        redacted: collection.redacted,
+        reused: collection.reused,
+        reusePack: promotion.state === "reused",
+    });
+    collection.entries.push(evidenceEntry({
+        context,
+        kind: "manifest",
+        packId,
+        localPath: manifestPath,
+        relativePath: "manifest.json",
+        mediaType: "application/json",
+        redactedSummary: "Local raw evidence pack manifest.",
+        bytes: manifestBytes,
+        // The manifest carries its own content hash in its key, exactly like
+        // every other object in the pack (BLI-3552). Without it the key was
+        // `…/<packId>/manifest.json`, and a pack id is a function of the OTHER
+        // files' hashes — not of the manifest's bytes, which also carry
+        // `created_at`, the ordering-dependent `files[].relative_path`, `branch`,
+        // and the skipped/redacted/reused ledgers. So the same key named
+        // different bytes whenever the pack directory was not adopted verbatim
+        // (a refill, a pruned or wiped state dir, a machine that had never seen
+        // the pack). `begin` then answered `hash_mismatch_committed_object` on
+        // every sync forever, because the new manifest is stable and the old one
+        // is durable. `stageManifest`'s byte-stability trick still stands; it is
+        // now a nice-to-have rather than the only thing between us and a loop.
+        contentAddress: `manifest/${sha256(manifestBytes).slice(0, 16)}.json`,
+    }));
+    return manifestPath;
+}
+/** The success line. A sync that staged nothing new still has to say so. */
+function logPackStaged(collection, promotion, packId) {
+    console.error("[raw-evidence] pack staged", JSON.stringify({
+        pack_id: packId,
+        stage_state: promotion.state,
+        reason: stageReasonLabel(promotion.state, promotion.priorPackCount),
+        prior_pack_count: promotion.priorPackCount,
+        refilled_file_count: promotion.refilledFileCount,
+        file_count: collection.entries.length,
+        byte_size: totalByteSize(collection.entries),
+        staged_new: collection.stagedNewCount,
+        staged_reused: collection.stagedReusedCount,
+        delivery_held: collection.deliveryHeldCount,
+    }));
+}
+/**
+ * A crashed pass. The staged-object index is deliberately NOT written: this
+ * attempt's bookkeeping describes a directory that is about to be deleted.
+ */
+export async function finishWithFailedPack(collection, run) {
+    collection.failed.push({
+        kind: "raw_evidence",
+        reason: "collection_failed",
+    });
+    // Staging is per-attempt scratch: a crashed pass must not leave a partial
+    // directory behind to be counted, re-hashed or swept later.
+    await discardStagingDir(run.stagingDir);
+    collection.packId =
+        collection.packId ||
+            contentKeyedRawEvidencePackId({
+                workContextId: collection.context.workContextId,
+                contentHashes: collection.entries.map((entry) => entry.content_hash_sha256),
+            });
+    console.error("[raw-evidence] pack collection failed", JSON.stringify({
+        pack_id: collection.packId,
+        reason: "collection_failed",
+        detail: run.error instanceof Error ? run.error.name : typeof run.error,
+        collected_file_count: collection.entries.length,
+        staged_new: collection.stagedNewCount,
+        staged_reused: collection.stagedReusedCount,
+    }));
+    const facts = makeEmptyPackFacts(collection, run.window);
+    return {
+        facts,
+        scan: makeRawEvidenceScan({
+            context: collection.context,
+            startedAt: run.window.startedAt,
+            status: "failed",
+            facts,
+        }),
+    };
+}
+// ---------------------------------------------------------------------------
+// What every ending reports
+// ---------------------------------------------------------------------------
+/**
+ * A pack with no files of its own: the empty pass and the crashed pass report
+ * the same shape, differing only in the scan status and the reason already
+ * logged. `evidence_completeness` still carries every gap this pass recorded.
+ */
+function makeEmptyPackFacts(collection, scanWindow) {
+    const evidenceDir = path.join(collection.rawEvidenceRoot, collection.packId);
+    return {
+        ...packFactsShell(collection, {
+            packId: collection.packId,
+            manifestPath: path.join(evidenceDir, "manifest.json"),
+            evidenceDir,
+            window: scanWindow,
+        }),
+        stage_state: "empty",
+        file_count: 0,
+        byte_size: 0,
+        content_kinds: [],
+        pointers: [],
+        upload_files: [],
+    };
+}
+/** The counts every ending reports identically, however the pass ended. */
+function packFactsShell(collection, place) {
+    return {
+        pack_id: place.packId,
+        manifest_path: place.manifestPath,
+        evidence_dir: place.evidenceDir,
+        storage_bucket: RAW_EVIDENCE_BUCKET,
+        skipped_count: countEvidenceEntries(collection.skipped),
+        sanitized_count: collection.redacted.length,
+        reused_count: collection.reused.length,
+        staged_reused_count: collection.stagedReusedCount,
+        staged_new_count: collection.stagedNewCount,
+        delivery_held_count: collection.deliveryHeldCount,
+        deferred_byte_budget_count: countDeferred(collection, "deferred_byte_budget"),
+        deferred_object_budget_count: countDeferred(collection, "deferred_object_budget"),
+        evidence_completeness: makeEvidenceCompleteness(collection, {
+            startedAt: place.window.startedAt,
+            finishedAt: place.window.finishedAt(),
+            sinceMinutes: place.window.sinceMinutes,
+        }),
+        reused: collection.reused,
+    };
+}
+function countDeferred(collection, reason) {
+    return countEvidenceEntries(collection.skipped, (entry) => entry.reason === reason);
+}
+function totalByteSize(entries) {
+    return entries.reduce((sum, entry) => sum + entry.byte_size, 0);
+}
+function uploadFileFromEntry(entry) {
+    return {
+        pointer: pointerFromEntry(entry),
+        local_path: entry.local_path,
+        kind: entry.kind,
+        codex_session_id: entry.codex_session_id ?? null,
+        ...(entry.artifact_metadata
+            ? { artifact_metadata: entry.artifact_metadata }
+            : {}),
+    };
+}
+function stageReasonLabel(state, priorPackCount) {
+    if (state === "reused")
+        return "staged_reused";
+    if (state === "restaged_incomplete")
+        return "restaged_incomplete";
+    return priorPackCount > 0 ? "restaged_content_changed" : "staged_new";
+}
+/**
+ * Point every entry this pass staged at its home in the promoted pack, and
+ * remember the content hash so the next sync can adopt the copy instead of
+ * writing it again. Entries adopted from another pack keep their path.
+ */
+function rebaseStagedEntriesOntoPack(collection, evidenceDir) {
+    for (const entry of collection.entries) {
+        if (!entry.staged_in_pack)
+            continue;
+        entry.local_path = path.join(evidenceDir, "files", path.basename(entry.local_path));
+        recordStagedObject(collection.staging, entry.content_hash_sha256, {
+            pack_id: collection.packId,
+            relative_path: `files/${path.basename(entry.local_path)}`,
+            byte_size: entry.byte_size,
+            source_key: entry.source_key,
+            staged_at: collection.context.now.toISOString(),
+        });
+    }
+}
+function makeRawEvidenceScan(options) {
+    return SourceScanResultSchema.parse({
+        adapter: makeSourceAdapterIdentity("collector_runtime", "raw-evidence-pack"),
+        work_context_id: options.context.workContextId,
+        status: options.status,
+        started_at: options.startedAt,
+        finished_at: options.context.now.toISOString(),
+        events: [
+            {
+                source_event_id: `raw-evidence-pack:${options.facts.pack_id}`,
+                event_type: "raw_evidence_pack_written",
+                occurred_at: options.context.now.toISOString(),
+                redaction: {
+                    privacy_classification: "remote_durable_raw_evidence",
+                    redaction_status: "raw_remote_durable",
+                    redacted_fields: ["local_path"],
+                    raw_evidence_pointer_ids: options.facts.pointers.map((pointer) => pointer.raw_evidence_pointer_id),
+                    redacted_summary: "Raw prompt/response/tool/session/diff evidence harvested to a private durable remote evidence pack.",
+                },
+                raw_evidence_pointers: options.facts.pointers,
+            },
+        ],
+        diagnostic_labels: [
+            `pack_id:${options.facts.pack_id}`,
+            `files:${options.facts.file_count}`,
+            `bytes:${options.facts.byte_size}`,
+            `skipped:${options.facts.skipped_count}`,
+            `reused:${options.facts.reused_count}`,
+            `stage_state:${options.facts.stage_state}`,
+            `staged_new:${options.facts.staged_new_count}`,
+            `staged_reused:${options.facts.staged_reused_count}`,
+            `delivery_held:${options.facts.delivery_held_count}`,
+            `completeness:${options.facts.evidence_completeness.status}`,
+            `truncated:${options.facts.evidence_completeness.totals.truncated_count}`,
+            `deferred:${options.facts.evidence_completeness.totals.deferred_count}`,
+            `failed:${options.facts.evidence_completeness.totals.failed_count}`,
+            ...options.facts.content_kinds.map((kind) => `kind:${kind}`),
+        ],
+    });
+}

package/dist/adapters/raw-evidence-git-diff-reader.js

@@ -0,0 +1,187 @@
+/**
+ * The other half of the evidence of what someone actually changed: the working
+ * tree's own two diffs, unstaged and staged.
+ *
+ * `raw-evidence-git-diff.ts` runs git and enforces the pathspec and the caps;
+ * this is the pack side — the scanned counts, the named gaps, masking, the
+ * budget, and the manifest entry. Neither target is switchable off by the
+ * caller, because a transcript without its diff describes work nobody can
+ * check.
+ *
+ * A missing repo root is a fact about the folder, not a fault in git
+ * (BLI-3551): it is asked once per pass, costs one log line, and still gives
+ * both targets their own named gap.
+ */
+import path from "node:path";
+import { describeError } from "../health-detail.js";
+import { evidenceSourceKey } from "../raw-evidence-staging.js";
+import { sha256 } from "./raw-evidence-keys.js";
+import { maskSecretsInGitDiff, } from "./raw-evidence-sanitize.js";
+import { markBudgetCapApplied, markCapApplied, recordScanned, } from "./raw-evidence-completeness.js";
+import { evidenceEntry } from "./raw-evidence-manifest.js";
+import { admitToBudget, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
+import { MAX_GIT_DIFF_BYTES, REPO_ROOT_MISSING_REASON, RepoRootMissingError, repoRootExists, runGitDiff, } from "./raw-evidence-git-diff.js";
+const GIT_DIFF_TARGETS = [
+    { label: "unstaged", args: ["diff", "--no-ext-diff", "--"] },
+    { label: "staged", args: ["diff", "--cached", "--no-ext-diff", "--"] },
+];
+export async function collectGitDiffFiles(collection, repoRoot) {
+    if (!(await repoRootExists(repoRoot))) {
+        skipEveryDiffTargetForMissingRoot(collection);
+        return;
+    }
+    for (const target of GIT_DIFF_TARGETS) {
+        recordScanned(collection, "git_diff");
+        const diff = await runOneGitDiff(collection, target, repoRoot);
+        if (!diff)
+            continue;
+        if (diff.truncated)
+            recordGitDiffTruncation(collection, diff);
+        // An empty diff is not a gap: there was simply nothing to record. The
+        // truncation marker above still stands even when zero bytes survived.
+        if (!diff.stdout.trim())
+            continue;
+        await stageOneGitDiff(collection, {
+            label: target.label,
+            diffText: diff.stdout,
+            truncated: diff.truncated,
+        });
+    }
+}
+/**
+ * BLI-3551: the root is asked about once per pass, before either target, so a
+ * pruned worktree costs ONE line instead of one per diff target per session per
+ * tick — and the line says the folder is gone rather than accusing git of
+ * failing. Both targets still get their own named gap.
+ */
+function skipEveryDiffTargetForMissingRoot(collection) {
+    console.error("[raw-evidence] git diff skipped, repository root is no longer on disk", JSON.stringify({
+        reason: REPO_ROOT_MISSING_REASON,
+        diff_targets_skipped: GIT_DIFF_TARGETS.length,
+        next_action: "nothing to do; the diff returns when the worktree is restored or the session ages out",
+    }));
+    for (const target of GIT_DIFF_TARGETS) {
+        recordScanned(collection, "git_diff");
+        collection.skipped.push({
+            kind: "git_diff",
+            label: target.label,
+            reason: REPO_ROOT_MISSING_REASON,
+        });
+    }
+}
+/**
+ * Run one diff, or record why it produced nothing. Null means the gap is
+ * already named in the ledger, so the caller only has to move on.
+ */
+async function runOneGitDiff(collection, target, repoRoot) {
+    try {
+        return await runGitDiff(target.args, repoRoot);
+    }
+    catch (error) {
+        // The root was there a moment ago and is not now (or a second collector
+        // pruned it mid-tick). Same named outcome, still not a git failure.
+        if (error instanceof RepoRootMissingError) {
+            collection.skipped.push({
+                kind: "git_diff",
+                label: target.label,
+                reason: REPO_ROOT_MISSING_REASON,
+            });
+            return null;
+        }
+        // `git_diff_failed` is the skip label and stays. It covers git not being
+        // installed, the folder not being a repo, a locked index and a diff that
+        // exceeded the child-process buffer — and the diff is half the evidence
+        // for what someone actually changed, so losing it quietly matters.
+        console.error("[raw-evidence] git diff failed", JSON.stringify({
+            reason: "git_diff_failed",
+            diff_target: target.label,
+            ...describeError(error),
+        }));
+        collection.skipped.push({
+            kind: "git_diff",
+            label: target.label,
+            reason: "git_diff_failed",
+        });
+        return null;
+    }
+}
+/** A diff that hit its size or time cap is partial evidence, and says so. */
+function recordGitDiffTruncation(collection, diff) {
+    markCapApplied(collection, "git_diff", diff.truncationCapType);
+    collection.truncated.push({
+        kind: "git_diff",
+        reason: diff.truncationReason,
+        ...(diff.truncationCapType === "max_bytes_per_diff"
+            ? { max_bytes: MAX_GIT_DIFF_BYTES }
+            : {}),
+        observed_bytes: diff.observedBytes,
+        included_bytes: Buffer.byteLength(diff.stdout, "utf8"),
+    });
+}
+async function stageOneGitDiff(collection, target) {
+    const sanitized = maskSecretsInGitDiff(collection, target);
+    const contentHash = sha256(sanitized.bytes);
+    if (collection.skipContentHashes.has(contentHash)) {
+        collection.reused.push({
+            kind: "git_diff",
+            label: target.label,
+            content_hash_sha256: contentHash,
+            codex_session_id: null,
+        });
+        return;
+    }
+    const deferReason = admitToBudget(collection.budget, sanitized.bytes.byteLength);
+    if (deferReason) {
+        markBudgetCapApplied(collection, deferReason);
+        collection.skipped.push({
+            kind: "git_diff",
+            label: target.label,
+            reason: deferReason,
+        });
+        return;
+    }
+    await writeGitDiffToPack(collection, { target, sanitized, contentHash });
+}
+/** Put an accepted diff's bytes on disk and add its manifest entry. */
+async function writeGitDiffToPack(collection, diff) {
+    const label = diff.target.label;
+    const relativePath = path.join("files", `git-${label}.diff`);
+    const diffSourceKey = evidenceSourceKey({
+        kind: "git_diff",
+        sessionId: collection.context.workContextId,
+        label,
+    });
+    const staged = await stageEvidenceBytes(collection, {
+        contentHash: diff.contentHash,
+        bytes: diff.sanitized.bytes,
+        fileName: path.basename(relativePath),
+        kind: "git_diff",
+        sourceKey: diffSourceKey,
+    });
+    collection.entries.push(evidenceEntry({
+        context: collection.context,
+        kind: "git_diff",
+        packId: collection.packId,
+        localPath: staged.local_path,
+        relativePath,
+        stagedInPack: staged.staged_in_pack,
+        sourceKey: diffSourceKey,
+        mediaType: "text/x-diff",
+        redactedSummary: gitDiffSummary(label, {
+            redacted: diff.sanitized.status === "redacted",
+            truncated: diff.target.truncated,
+        }),
+        redaction: diff.sanitized.redaction,
+        bytes: diff.sanitized.bytes,
+        contentAddress: `git-diff/${label}-${diff.contentHash.slice(0, 16)}.diff`,
+    }));
+}
+function gitDiffSummary(label, state) {
+    if (state.redacted) {
+        return `Raw git ${label} diff preserved locally with env/secret paths excluded and secret-like values deterministically redacted.`;
+    }
+    if (state.truncated) {
+        return `Raw git ${label} diff truncated to the capture cap and preserved locally with env/secret paths excluded.`;
+    }
+    return `Raw git ${label} diff preserved locally with env/secret paths excluded.`;
+}

package/dist/adapters/raw-evidence-image-reader.js

@@ -0,0 +1,107 @@
+/**
+ * Images a person explicitly attached to an agent session, and only those.
+ *
+ * `agent-image-evidence.ts` decides what counts as an attachment and hands back
+ * decoded bytes; this is the pack side of that split — scanned counts, named
+ * skips, the reuse and budget checks, and the manifest entry. An image is only
+ * ever collected after its transcript was accepted, so a session that was
+ * skipped cannot leak its screenshots.
+ */
+import path from "node:path";
+import { collectAgentImageEvidenceFromJsonlFile, } from "./agent-image-evidence.js";
+import { evidenceSourceKey } from "../raw-evidence-staging.js";
+import { sha256 } from "./raw-evidence-keys.js";
+import { markBudgetCapApplied, recordScanned, } from "./raw-evidence-completeness.js";
+import { evidenceEntry } from "./raw-evidence-manifest.js";
+import { admitToBudget, stageEvidenceBytes, } from "./raw-evidence-collection-state.js";
+export async function collectAgentImagesFromTranscript(collection, options) {
+    const result = await collectAgentImageEvidenceFromJsonlFile({
+        filePath: options.filePath,
+        source: options.source,
+        sessionId: options.sessionId,
+        sidecarId: options.sidecarId,
+    });
+    recordScanned(collection, options.kind, result.images.length + result.skipped.length);
+    for (const skipped of result.skipped) {
+        collection.skipped.push({
+            kind: options.kind,
+            label: skipped.label,
+            reason: skipped.reason,
+        });
+    }
+    for (const image of result.images) {
+        await collectOneAgentImageFile(collection, {
+            image,
+            kind: options.kind,
+            sessionId: options.sessionId,
+            contentAddress: options.contentAddress,
+        });
+    }
+}
+async function collectOneAgentImageFile(collection, options) {
+    const raw = options.image.bytes;
+    const contentHash = sha256(raw);
+    const metadata = {
+        ...options.image.metadata,
+        content_hash_sha256: contentHash,
+        byte_size: raw.byteLength,
+    };
+    if (collection.skipContentHashes.has(contentHash)) {
+        collection.reused.push({
+            kind: options.kind,
+            label: options.image.label,
+            content_hash_sha256: contentHash,
+            codex_session_id: options.sessionId,
+            artifact_metadata: metadata,
+        });
+        return;
+    }
+    const deferReason = admitToBudget(collection.budget, raw.byteLength);
+    if (deferReason) {
+        markBudgetCapApplied(collection, deferReason);
+        collection.skipped.push({
+            kind: options.kind,
+            label: options.image.label,
+            reason: deferReason,
+        });
+        return;
+    }
+    await writeAgentImageToPack(collection, {
+        ...options,
+        contentHash,
+        metadata,
+    });
+}
+/** Put an accepted image's bytes on disk and add its manifest entry. */
+async function writeAgentImageToPack(collection, image) {
+    const raw = image.image.bytes;
+    collection.index.value += 1;
+    const relativePath = path.join("files", `${String(collection.index.value).padStart(3, "0")}-agent-image-${image.contentHash.slice(0, 16)}.${image.image.extension}`);
+    const imageSourceKey = evidenceSourceKey({
+        kind: image.kind,
+        sessionId: image.sessionId,
+        label: image.image.label,
+    });
+    const staged = await stageEvidenceBytes(collection, {
+        contentHash: image.contentHash,
+        bytes: raw,
+        fileName: path.basename(relativePath),
+        kind: image.kind,
+        sourceKey: imageSourceKey,
+    });
+    collection.entries.push(evidenceEntry({
+        context: collection.context,
+        kind: image.kind,
+        packId: collection.packId,
+        localPath: staged.local_path,
+        relativePath,
+        stagedInPack: staged.staged_in_pack,
+        sourceKey: imageSourceKey,
+        mediaType: image.metadata.media_type,
+        redactedSummary: "Raw image explicitly attached to an agent session, preserved in private durable storage.",
+        bytes: raw,
+        codexSessionId: image.sessionId,
+        contentAddress: image.contentAddress(image.contentHash.slice(0, 16), image.image.extension),
+        artifactMetadata: image.metadata,
+    }));
+}

package/dist/adapters/raw-evidence-sanitize.js

@@ -205,4 +205,60 @@ function withRedactionContentMetadata(metadata, options) {
         original_byte_size: options.originalBytes.byteLength,
         sanitized_byte_size: options.sanitizedBytes.byteLength,
     };
+}
+// ---------------------------------------------------------------------------
+// Masking with a receipt
+// ---------------------------------------------------------------------------
+/**
+ * Mask secret-like values in a transcript and record that it happened, because
+ * masking is invisible in the uploaded bytes and an operator has to be able to
+ * see that this file went up altered.
+ */
+export function maskSecretsInTranscript(collection, options) {
+    const sanitized = sanitizeTextEvidenceForUpload({
+        text: options.raw.toString("utf8"),
+        originalBytes: options.raw,
+        redactedFields: [`${options.kind}.body`],
+        secretLikeFileName: options.secretLikeFileName,
+    });
+    if (sanitized.status === "redacted") {
+        collection.redacted.push({
+            kind: options.kind,
+            label: options.evidenceLabel,
+            redaction: sanitized.redaction,
+            completenessLabel: sanitized.completenessLabel,
+        });
+        console.error("[raw-evidence] text evidence sanitized", JSON.stringify({
+            kind: options.kind,
+            mode: sanitized.completenessLabel,
+            original_bytes: options.raw.byteLength,
+            uploaded_bytes: sanitized.bytes.byteLength,
+        }));
+    }
+    return sanitized;
+}
+/**
+ * Mask secret-like values in a diff and record that it happened. A diff carries
+ * whatever a person pasted into a config file, so this is the branch that most
+ * often fires — and an operator has to see that the bytes went up altered.
+ */
+export function maskSecretsInGitDiff(collection, target) {
+    const sanitized = sanitizeTextEvidenceForUpload({
+        text: target.diffText,
+        redactedFields: [`git_diff.${target.label}`],
+    });
+    if (sanitized.status === "redacted") {
+        collection.redacted.push({
+            kind: "git_diff",
+            label: target.label,
+            redaction: sanitized.redaction,
+            completenessLabel: sanitized.completenessLabel,
+        });
+        console.error("[raw-evidence] git diff sanitized", JSON.stringify({
+            mode: sanitized.completenessLabel,
+            original_bytes: Buffer.byteLength(target.diffText, "utf8"),
+            uploaded_bytes: sanitized.bytes.byteLength,
+        }));
+    }
+    return sanitized;
 }