@bli-cockpit/cli 0.2.46 → 0.2.48

package/dist/commands/ops-render.js

@@ -80,6 +80,8 @@ export function renderOpsStatus(payload, dim) {
                 lines.push(dim(`       scheduled by ${row.configFile} (${row.cron ?? "?"})`));
         }
     }
+    if (payload.fleet)
+        lines.push(...renderFleet(payload.fleet, dim));
     const slack = payload.skips?.slack;
     const external = payload.skips?.external;
     if (slack || external) {
@@ -93,6 +95,33 @@ export function renderOpsStatus(payload, dim) {
     }
     return lines;
 }
+/**
+ * The laptops. Red first, because a person reading this at 9am should not have
+ * to scroll past nine healthy machines to find the dead one.
+ */
+export function renderFleet(fleet, dim) {
+    const lines = ["", `FLEET  ${fleet.summary ?? "(no summary)"}`];
+    if (fleet.readError) {
+        lines.push(`  the fleet could not be read (${fleet.readError}); nothing is known about any machine`);
+        return lines;
+    }
+    const devices = fleet.devices ?? [];
+    const rank = (colour) => colour === "red" ? 0 : colour === "amber" ? 1 : 2;
+    const ordered = [...devices].sort((left, right) => rank(left.colour) - rank(right.colour));
+    if (ordered.length === 0) {
+        lines.push(dim("  no live collector device is registered at all"));
+    }
+    for (const device of ordered) {
+        const text = `  ${device.line ?? device.deviceId ?? "(device)"}`;
+        // A healthy machine is dimmed, never dropped: "which laptops are fine" is
+        // the other half of the question, and a list that only shows failures
+        // cannot answer "is everybody else collecting?".
+        lines.push(device.colour === "red" || device.colour === "amber" ? text : dim(text));
+    }
+    if (fleet.noDeviceLine)
+        lines.push(dim(`  ${fleet.noDeviceLine}`));
+    return lines;
+}
 function renderSkipLedger(ledger, dim) {
     const lines = [];
     const name = ledger.relation ?? "skips";

package/dist/commands/ops.js

@@ -78,6 +78,12 @@ async function runOpsStatus(command, io, tower) {
         unhealthy: unhealthy.length,
         unhealthy_ids: unhealthy.map((row) => row.id ?? "?"),
         with_skips: Boolean(command.skips),
+        // The laptops (BLI-3550), counted on the same line: a run that shows a
+        // green board and says nothing about the fleet cannot answer "was
+        // anybody's machine dead this morning?".
+        fleet_devices: payload.fleet?.counts?.devices ?? null,
+        fleet_red: payload.fleet?.counts?.red ?? null,
+        fleet_amber: payload.fleet?.counts?.amber ?? null,
     })}`);
     return unhealthy.length > 0 ? 1 : 0;
 }

package/dist/commands/public-root.js

@@ -15,7 +15,7 @@ export async function runCockpitCli(argv, io) {
   }
 
   if (command === "--version" || command === "-V" || command === "version") {
-    writeLine(io?.stdout ?? process.stdout, "0.2.46");
+    writeLine(io?.stdout ?? process.stdout, "0.2.48");
     return 0;
   }
 

package/dist/commands/session-sync.js

@@ -143,17 +143,34 @@ function claudeAttributionReadFailureCount(scan) {
 }
 export function sourceScanRetryReason(source, scan) {
     const reasons = new Set();
-    const readFailureCount = source === "codex"
-        ? codexAttributionReadFailureCount(scan)
-        : claudeAttributionReadFailureCount(scan);
-    if (readFailureCount > 0) {
-        reasons.add(`${source}_session_store_read_failed`);
-    }
+    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, {
@@ -447,25 +464,47 @@ export async function runAttributedWorktreeSync(options) {
     });
     // Same conditions as before, one per line, each writing down its own reason.
     // The old version was a single boolean chain: correct, and completely mute.
-    const failureReasons = new Set();
-    const fail = (condition, reason) => {
+    //
+    // Since BLI-3551 each condition also writes down the LABEL it is classified
+    // by, beside the rendered string a person reads. The health receipt reads the
+    // label; nothing parses the sentence back apart.
+    const failureRecords = new Map();
+    const add = (record) => {
+        if (!failureRecords.has(record.rendered)) {
+            failureRecords.set(record.rendered, record);
+        }
+    };
+    const fail = (condition, label, rendered = label) => {
         if (condition)
-            failureReasons.add(reason);
+            add({ label, rendered });
     };
     for (const { worktree, sync } of outcomes) {
         if (sync.status !== "uploaded") {
             // The spooled reason is the most specific thing anyone has, so lead with
             // it and name the worktree it belongs to — a fleet failure is usually one
             // repo, and "which one" is the first question asked.
-            failureReasons.add(sync.status === "spooled" && sync.failure_reason
-                ? `${worktree.worktree_label}:${sync.failure_reason}`
-                : `${worktree.worktree_label}:upload_${sync.status}`);
+            add(sync.status === "spooled" && sync.failure_reason
+                ? {
+                    label: sync.failure_class,
+                    rendered: `${worktree.worktree_label}:${sync.failure_reason}`,
+                    http_status: sync.failure_http_status,
+                }
+                : {
+                    label: "upload_not_completed",
+                    rendered: `${worktree.worktree_label}:upload_${sync.status}`,
+                });
         }
         for (const reason of sync.raw_evidence_failure_reasons ?? []) {
-            failureReasons.add(`raw_evidence:${reason}`);
+            add({
+                label: "raw_evidence_upload_failed",
+                rendered: `raw_evidence:${reason}`,
+            });
         }
         for (const reason of sync.raw_evidence_retry_reasons ?? []) {
-            failureReasons.add(`raw_evidence_retry:${reason}`);
+            add({
+                label: "raw_evidence_retry_required",
+                rendered: `raw_evidence_retry:${reason}`,
+            });
         }
         fail(sync.raw_evidence_deferred_byte_budget > 0, "deferred_byte_budget");
         fail(sync.raw_evidence_deferred_object_budget > 0, "deferred_object_budget");
@@ -474,28 +513,110 @@ export async function runAttributedWorktreeSync(options) {
     fail(claudeAttribution.session_limit_applied, "claude_session_limit_applied");
     fail(codexAttributionReadFailureCount(codexAttribution) > 0, "codex_session_read_failed");
     fail(claudeAttributionReadFailureCount(claudeAttribution) > 0, "claude_session_read_failed");
-    const codexScanRetry = sourceScanRetryReason("codex", codexAttribution);
-    if (codexScanRetry)
-        failureReasons.add(`codex_scan:${codexScanRetry}`);
-    const claudeScanRetry = sourceScanRetryReason("claude_code", claudeAttribution);
-    if (claudeScanRetry)
-        failureReasons.add(`claude_scan:${claudeScanRetry}`);
-    fail(reportRequired && !report.posted, `session_report_unposted:${report.reason ?? "unknown"}`);
+    // BLI-3551: the scan's RETRY reason and the scan's FAILURE reason are two
+    // different questions, and answering both with one function is what put
+    // `claude_scan:repo_not_on_disk` on every tick of three machines. A repo that
+    // is not on disk is a label on the session (the attribution umbrella finding:
+    // nothing was deleted, the transcript simply names a path git no longer
+    // knows). It still widens the next scan window; it is not a failed sync.
+    const codexScanFailure = sourceScanFailureReason("codex", codexAttribution);
+    if (codexScanFailure) {
+        add({ label: "codex_scan_read_failed", rendered: `codex_scan:${codexScanFailure}` });
+    }
+    const claudeScanFailure = sourceScanFailureReason("claude_code", claudeAttribution);
+    if (claudeScanFailure) {
+        add({
+            label: "claude_scan_read_failed",
+            rendered: `claude_scan:${claudeScanFailure}`,
+        });
+    }
+    // BLI-3551: a tick that observed only sessions from outside the operator's
+    // approved roots has nothing to post, and that is the consent boundary
+    // working — not a failure. It used to fail as
+    // `session_report_unposted:no_successful_sync`, whose word "session" then
+    // classified as `auth_failed`; one machine reported a broken credential 377
+    // times in 38 hours while its token had eleven weeks left. The withhold
+    // decision itself is untouched (adapters/attribution-core.ts) — only what it
+    // is CALLED.
+    const sessionsOutsideRoot = sessions.filter((session) => OUTSIDE_APPROVED_ROOT_REASONS.has(session.attribution_reason)).length;
+    const nothingInRoot = nothingInRootCount({
+        sessionCount: sessions.length,
+        outsideRootCount: sessionsOutsideRoot,
+        outcomes,
+        reportPosted: report.posted,
+        reportReason: report.reason,
+    });
+    fail(reportRequired && !report.posted && nothingInRoot === null, "session_report_unposted", `session_report_unposted:${report.reason ?? "unknown"}`);
     // `ok` may already be false from the per-worktree loop above; the outcome
     // scan re-derives that, so the two agree by construction.
-    ok = ok && failureReasons.size === 0;
-    if (!ok && failureReasons.size === 0) {
-        failureReasons.add(SYNC_FAILED_WITHOUT_REASON);
+    ok = ok && failureRecords.size === 0;
+    if (!ok && failureRecords.size === 0) {
+        add({
+            label: SYNC_FAILED_WITHOUT_REASON,
+            rendered: SYNC_FAILED_WITHOUT_REASON,
+        });
+    }
+    const notice = ok && nothingInRoot !== null ? `nothing_in_root:${nothingInRoot}` : null;
+    if (notice) {
+        // The success branch says something too: this is the receipt that proves a
+        // quiet machine is a working machine, and the count is what tells a coach
+        // that someone is working entirely outside the approved boundary.
+        console.error("[session-sync] nothing to collect inside the approved roots", JSON.stringify({
+            reason: "nothing_in_root",
+            sessions_outside_root: nothingInRoot,
+            collection_root_count: collectionRoots.length,
+            next_action: "widen the approved roots (an operator decision) if this machine should be collecting here",
+        }));
     }
+    const records = [...failureRecords.values()].sort((a, b) => a.rendered.localeCompare(b.rendered));
     return {
         ok,
-        failure_reasons: [...failureReasons].sort(),
+        failure_reasons: records.map((record) => record.rendered),
+        failure_records: records,
+        notice,
+        sessions_observed: sessions.length,
+        sessions_outside_root: sessionsOutsideRoot,
         outcomes,
         codexAttribution,
         claudeAttribution,
         summary,
     };
 }
+/**
+ * Reasons attribution gives when a session's working directory is not inside
+ * any approved collection root.
+ *
+ * Exact labels, not a pattern — the same discipline the classifier now follows.
+ * `attribution-core.ts` writes both of these and nothing else means
+ * "outside the boundary".
+ */
+const OUTSIDE_APPROVED_ROOT_REASONS = new Set([
+    "cwd_outside_scanned_worktrees",
+    "no_matching_worktree_signals",
+]);
+/**
+ * How many observed sessions were outside the approved roots, when that
+ * accounts for ALL of them and nothing else went wrong — otherwise `null`.
+ *
+ * Deliberately narrow. It requires that no worktree was synced at all (so no
+ * upload could have succeeded or failed), that every session observed this tick
+ * names an outside-the-root reason, and that the unposted report is the
+ * `no_successful_sync` shape rather than a spooled report that failed to flush.
+ * Anything else keeps its failure.
+ */
+export function nothingInRootCount(options) {
+    if (options.reportPosted)
+        return null;
+    if (options.reportReason !== "no_successful_sync")
+        return null;
+    if (options.outcomes.length > 0)
+        return null;
+    if (options.sessionCount === 0)
+        return null;
+    return options.outsideRootCount === options.sessionCount
+        ? options.outsideRootCount
+        : null;
+}
 export const ATTRIBUTION_STATE_RANK = CODEX_SESSION_ATTRIBUTION_STATE_RANK;
 function normalizeCodexResult(result) {
     return {

package/dist/dev-build.js

@@ -0,0 +1,186 @@
+/**
+ * Is this collector a DEV BUILD? One predicate, two callers.
+ *
+ * BLI-3554. Edward's device row carried 47 `npm_install_eacces` receipts
+ * stamped `cli_version` 0.1.50 between 2026-09-02T16:55Z and 2026-09-03T06:25Z.
+ * 0.1.50 was never a published install on that machine — it was the workspace
+ * version in `packages/cockpit-local-collector/package.json` at the time, so
+ * every one of those rows came from an agent or a test running the built
+ * collector inside a worktree. They land in the same production
+ * `cockpit_install_events` table the fleet reader (BLI-3550,
+ * `apps/dashboard/src/lib/ops/fleet-liveness.ts`) alarms on, so a developer's
+ * sandbox failure reads as a fleet machine in trouble.
+ *
+ * The predicate is deliberately NOT a version comparison. A version equal to
+ * the workspace version is a symptom: it changes on every release, it is equal
+ * for the one machine that legitimately runs the newest published build the
+ * day it ships, and it says nothing about where the code was loaded from.
+ * What we can actually observe is the FILE the running code was loaded from:
+ *
+ * - a published install lives under a `node_modules/` prefix
+ *   (`/opt/homebrew/lib/node_modules/@bli-cockpit/cli/dist/…`,
+ *   `C:\\Users\\x\\AppData\\Roaming\\npm\\node_modules\\@bli-cockpit\\cli\\dist\\…`),
+ *   and that is the whole fleet;
+ * - a dev build lives inside a checkout of this repo — a
+ *   `packages/cockpit-local-collector/` (or `packages/cockpit-cli/`) ancestor
+ *   whose `package.json` names the workspace, with a `.git` marker or a
+ *   `.claude/worktrees` segment above it.
+ *
+ * `COCKPIT_DEV=1` forces dev. `COCKPIT_DEV=0` forces the opposite — that is the
+ * escape hatch for a deliberate live test from a checkout, documented in
+ * `docs/runbooks/cockpit-collector-receipts.md`.
+ *
+ * Suppression only bites when the target is a PRODUCTION dashboard. Pointing a
+ * checkout at `http://localhost:3000` is how the receipt path itself is
+ * developed, and refusing to post there would make this predicate the reason
+ * the next receipt bug cannot be reproduced.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/** The workspaces whose `dist/` a developer or agent runs from a checkout. */
+const WORKSPACE_PACKAGE_NAMES = new Set([
+    "@bli-cockpit/local-collector",
+    "@bli-cockpit/cli",
+]);
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["0", "false", "no", "off"]);
+/**
+ * Walks up from the running module. Pure apart from the two injected readers,
+ * so a Windows layout can be asserted from a macOS test run.
+ */
+export function detectDevBuild(probe = {}) {
+    const env = probe.env ?? process.env;
+    const rawFlag = (env.COCKPIT_DEV ?? "").trim().toLowerCase();
+    if (TRUE_VALUES.has(rawFlag)) {
+        return { devBuild: true, reason: "cockpit_dev_env" };
+    }
+    if (FALSE_VALUES.has(rawFlag)) {
+        // Deliberate live test from a checkout: the operator has said so out loud,
+        // and the path evidence below is not allowed to overrule them.
+        return { devBuild: false, reason: "cockpit_dev_env_disabled" };
+    }
+    const pathApi = probe.pathApi ?? path;
+    const modulePath = probe.modulePath ?? currentModulePath();
+    if (!modulePath)
+        return { devBuild: false, reason: "not_a_checkout" };
+    if (hasNodeModulesSegment(modulePath)) {
+        // Every published install is under a `node_modules/` prefix, on both host
+        // families. This branch is the whole fleet, and it is checked first so a
+        // machine that happens to have a repo checkout somewhere above its global
+        // npm prefix cannot be mislabelled.
+        return { devBuild: false, reason: "published_install" };
+    }
+    const readPackageName = probe.readPackageName ?? defaultReadPackageName;
+    const pathExists = probe.pathExists ?? defaultPathExists;
+    const packageRoot = findWorkspacePackageRoot(pathApi.dirname(modulePath), pathApi, readPackageName);
+    if (!packageRoot)
+        return { devBuild: false, reason: "not_a_checkout" };
+    if (!hasCheckoutMarkerAbove(packageRoot, pathApi, pathExists)) {
+        return { devBuild: false, reason: "not_a_checkout" };
+    }
+    return { devBuild: true, reason: "workspace_checkout" };
+}
+/**
+ * Should this process withhold fleet receipts (install events, heartbeat)?
+ *
+ * Two facts, in this order: is the code a dev build, and is the target the
+ * production fleet. A dev build talking to `localhost` still posts, because
+ * that is the only way to exercise the receipt path at all.
+ */
+export function shouldSuppressFleetReceipts(options) {
+    const verdict = detectDevBuild(options.probe ?? {});
+    if (!verdict.devBuild)
+        return { suppressed: false, reason: verdict.reason };
+    if (isLocalDashboardUrl(options.dashboardUrl)) {
+        return { suppressed: false, reason: "local_dashboard" };
+    }
+    return { suppressed: true, reason: verdict.reason };
+}
+/** A dashboard on this machine — safe for a checkout to post at. */
+export function isLocalDashboardUrl(dashboardUrl) {
+    let hostname;
+    try {
+        hostname = new URL(dashboardUrl).hostname.toLowerCase();
+    }
+    catch {
+        // An unparseable URL is not demonstrably local, and this predicate only
+        // ever widens suppression when it says false.
+        return false;
+    }
+    const bare = hostname.replace(/^\[|\]$/gu, "");
+    return (bare === "localhost" ||
+        bare === "127.0.0.1" ||
+        bare === "::1" ||
+        bare === "0.0.0.0" ||
+        bare.endsWith(".localhost"));
+}
+function currentModulePath() {
+    try {
+        return fileURLToPath(import.meta.url);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Case-insensitive on purpose: Windows spells the same folder
+ * `Node_Modules` without complaint, and both separators appear on that host
+ * because a POSIX-style path survives most Node APIs there.
+ */
+function hasNodeModulesSegment(modulePath) {
+    return modulePath
+        .split(/[\\/]+/u)
+        .some((segment) => segment.toLowerCase() === "node_modules");
+}
+function findWorkspacePackageRoot(startDir, pathApi, readPackageName) {
+    let dir = startDir;
+    // Bounded: `path.dirname` reaches a fixed point at `/` or `C:\`, and the
+    // depth guard keeps a pathological symlink loop from spinning a sync walk.
+    for (let depth = 0; depth < 64; depth += 1) {
+        const name = readPackageName(pathApi.join(dir, "package.json"));
+        if (name && WORKSPACE_PACKAGE_NAMES.has(name))
+            return dir;
+        const parent = pathApi.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * A repo checkout marker at or above the workspace package: `.git` (a
+ * directory in a normal clone, a FILE in a `git worktree`), or the
+ * `.claude/worktrees` staging area agents run from.
+ */
+function hasCheckoutMarkerAbove(packageRoot, pathApi, pathExists) {
+    let dir = packageRoot;
+    for (let depth = 0; depth < 64; depth += 1) {
+        if (pathExists(pathApi.join(dir, ".git")))
+            return true;
+        if (pathExists(pathApi.join(dir, ".claude", "worktrees")))
+            return true;
+        const parent = pathApi.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+    return false;
+}
+function defaultReadPackageName(packageJsonPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+        return typeof parsed.name === "string" ? parsed.name : null;
+    }
+    catch {
+        return null;
+    }
+}
+function defaultPathExists(candidate) {
+    try {
+        return fs.existsSync(candidate);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/evidence-upload-client.js

@@ -1,6 +1,7 @@
-import { COMMIT_CRASHED_PLATFORM, RAW_EVIDENCE_UPLOAD_DEFAULT_CHUNK_BYTES, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, RAW_EVIDENCE_UPLOAD_MAX_OBJECTS_PER_BEGIN, RawEvidenceLegacyUploadResponseSchema, RawEvidenceRedactionMetadataSchema, RawEvidenceUploadBeginResponseSchema, RawEvidenceUploadCommitResponseSchema, isPermanentUploadFailure, } from "@bli-cockpit/telemetry-core";
+import { COMMIT_CRASHED_PLATFORM, RAW_EVIDENCE_UPLOAD_DEFAULT_CHUNK_BYTES, RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES, RAW_EVIDENCE_UPLOAD_MAX_OBJECTS_PER_BEGIN, RawEvidenceLegacyUploadResponseSchema, RawEvidenceRedactionMetadataSchema, RawEvidenceUploadBeginResponseSchema, RawEvidenceUploadCommitResponseSchema, isPermanentUploadFailure, isRekeyableUploadConflict, } from "@bli-cockpit/telemetry-core";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
+import { rekeyedEvidencePointer } from "./evidence-upload-rekey.js";
 import { describeError } from "./health-detail.js";
 const DEFAULT_MAX_ATTEMPTS = 3;
 const RETRY_DELAY_MS = 250;
@@ -182,10 +183,18 @@ export async function uploadRawEvidenceFilesChunked(options) {
                 resolvedEntries.add(entry);
                 continue;
             }
-            const outcome = await uploadOneObject(options, entry, disposition, chunkSizeBytes);
-            await reportAbandonedUpload(options, disposition, outcome);
+            // A conflict a different name can settle gets one, here, before the
+            // upload is attempted (BLI-3552). Anything else comes back unchanged and
+            // fails on its own reason inside `uploadOneObject`.
+            const resolved = await rekeyConflictedEntry(options, entry, disposition, chunkSizeBytes);
+            const outcome = await uploadOneObject(options, resolved.entry, resolved.disposition, chunkSizeBytes);
+            await reportAbandonedUpload(options, resolved.disposition, outcome);
             outcomes.push(outcome);
-            for (const duplicate of entry.duplicates) {
+            // The duplicates of a re-keyed primary were re-keyed with it: a duplicate
+            // is byte-identical and shared the primary's key, so it shares the new
+            // one too. Leaving them on the old key would point their evidence refs at
+            // somebody else's durable object.
+            for (const duplicate of resolved.entry.duplicates) {
                 outcomes.push(duplicateOutcome(outcome, duplicate));
             }
             resolvedEntries.add(entry);
@@ -281,6 +290,105 @@ function conformReasonLabel(reason) {
     const conformed = reason.replace(/[^a-z0-9_:.-]/gi, "_").slice(0, 120);
     return conformed.length > 0 ? conformed : "upload_failed_unlabelled";
 }
+/**
+ * Settle a re-keyable conflict by asking for a second name (BLI-3552).
+ *
+ * `hash_mismatch_committed_object` means the key already holds different bytes
+ * that are already durable. Re-sending is the loop; deleting the durable object
+ * to make room is destroying evidence. The third answer is to offer this
+ * content under a name derived from its own hash, which is what this does, once
+ * per object per sync.
+ *
+ * Every path that cannot get there returns the ORIGINAL pair, so the object
+ * fails on the conflict reason `begin` actually gave rather than on a label
+ * invented here. Nothing is written off permanently either way: the upload
+ * cursor only remembers successes, so the next eligible sync offers the bytes
+ * again — at delivery-backoff cadence now instead of every 15 minutes.
+ */
+async function rekeyConflictedEntry(options, entry, disposition, chunkSizeBytes) {
+    if (disposition.disposition !== "conflict" ||
+        !isRekeyableUploadConflict(disposition.reason)) {
+        return { entry, disposition };
+    }
+    const contentHashPrefix = (entry.file.pointer.content_hash_sha256 ?? "none").slice(0, 12);
+    const rekeyedPointer = rekeyedEvidencePointer(entry.file.pointer);
+    if (!rekeyedPointer) {
+        // The key already names this content and the server still says it holds
+        // something else. A rename cannot answer that; a person has to.
+        console.error("[evidence-rekey] the key already carries this content hash; leaving the conflict for a person", JSON.stringify({
+            reason: disposition.reason,
+            kind: entry.file.kind ?? "unknown",
+            content_hash_prefix: contentHashPrefix,
+            byte_size: entry.bytes.byteLength,
+        }));
+        return { entry, disposition };
+    }
+    const rekeyedEntry = {
+        ...entry,
+        file: { ...entry.file, pointer: rekeyedPointer },
+        duplicates: entry.duplicates.map((duplicate) => ({
+            ...duplicate,
+            pointer: rekeyedEvidencePointer(duplicate.pointer) ?? duplicate.pointer,
+        })),
+    };
+    const rekeyedDisposition = await beginOneObject(options, rekeyedEntry, chunkSizeBytes);
+    if (!rekeyedDisposition) {
+        return { entry, disposition };
+    }
+    console.error("[evidence-rekey] committed object holds other content; offering these bytes under their own hash", JSON.stringify({
+        reason: disposition.reason,
+        kind: entry.file.kind ?? "unknown",
+        content_hash_prefix: contentHashPrefix,
+        byte_size: entry.bytes.byteLength,
+        chunk_count: entry.chunkCount,
+        rekeyed_disposition: rekeyedDisposition.disposition,
+        rekeyed_reason: rekeyedDisposition.reason ?? "none",
+        duplicate_count: entry.duplicates.length,
+    }));
+    return { entry: rekeyedEntry, disposition: rekeyedDisposition };
+}
+/**
+ * `begin` for a single object. Null whenever the answer cannot be trusted —
+ * transport failure, an unparseable body, a duplicate or missing key, or a
+ * pointer id that is not the one we sent — and the caller then keeps the
+ * original conflict rather than acting on a guess.
+ */
+async function beginOneObject(options, entry, chunkSizeBytes) {
+    const objectKey = entry.file.pointer.object_key ?? "";
+    const response = await requestJson(options, "/api/ambient/evidence/upload/begin", {
+        schema_version: "ambient-raw-evidence-upload-begin.v1",
+        generated_at: options.generatedAt,
+        provenance: options.provenance,
+        objects: [
+            {
+                pointer: entry.file.pointer,
+                chunk_size_bytes: chunkSizeBytes,
+                chunk_count: entry.chunkCount,
+            },
+        ],
+    });
+    if (!response.ok) {
+        console.error("[evidence-rekey] begin refused the re-keyed object; keeping the original conflict", JSON.stringify({
+            reason: "rekey_begin_rejected",
+            http_status: response.status,
+            server_reason: safeFailureDetail(response.body) ?? "none",
+            kind: entry.file.kind ?? "unknown",
+        }));
+        return null;
+    }
+    const parsed = RawEvidenceUploadBeginResponseSchema.safeParse(response.body);
+    if (!parsed.success)
+        return null;
+    const dispositions = readBeginDispositions(parsed.data);
+    const disposition = dispositions?.get(objectKey);
+    if (!disposition)
+        return null;
+    if (disposition.raw_evidence_pointer_id !==
+        entry.file.pointer.raw_evidence_pointer_id) {
+        return null;
+    }
+    return disposition;
+}
 async function uploadOneObject(options, entry, disposition, chunkSizeBytes) {
     const objectKey = entry.file.pointer.object_key ?? "";
     if (disposition.disposition === "already_committed") {

package/dist/evidence-upload-rekey.js

@@ -0,0 +1,40 @@
+/** How much of the content hash goes into the name, matching the pack keys. */
+const KEY_HASH_PREFIX_LENGTH = 16;
+/**
+ * The same object under a name that carries its own content hash.
+ *
+ * `null` when a re-key cannot help and must not be attempted:
+ * - there is no object key to rewrite;
+ * - the last segment already starts with this content's hash prefix, so the
+ *   re-keyed name would be the identical string and the second `begin` would
+ *   answer the identical conflict;
+ * - the key has no `/`, which the server's namespace rules make impossible, so
+ *   rewriting it would be inventing a key rather than deriving one.
+ *
+ * The new segment is `<hash16>-<old segment>`: still inside the operator's
+ * readable namespace (so `evidenceObjectKeyBelongsToWorkContext` still passes),
+ * still inside the key charset, and still legible to a person doing an incident
+ * walk — they can see which pack file it came from.
+ */
+export function rekeyedEvidencePointer(pointer) {
+    const objectKey = pointer.object_key;
+    if (!objectKey)
+        return null;
+    const cut = objectKey.lastIndexOf("/");
+    if (cut <= 0 || cut === objectKey.length - 1)
+        return null;
+    const prefix = objectKey.slice(0, cut);
+    const segment = objectKey.slice(cut + 1);
+    // A pointer with no content hash cannot name itself, and the upload routes
+    // reject it anyway; there is nothing to re-key it to.
+    const hash = (pointer.content_hash_sha256 ?? "").slice(0, KEY_HASH_PREFIX_LENGTH);
+    if (!hash || segment.startsWith(`${hash}-`) || segment.startsWith(hash)) {
+        return null;
+    }
+    const rekeyed = `${prefix}/${hash}-${segment}`;
+    return {
+        ...pointer,
+        object_key: rekeyed,
+        raw_evidence_pointer_id: rekeyed,
+    };
+}