@bli-cockpit/cli 0.2.236 → 0.2.238

package/dist/evidence-upload-plan.js

@@ -8,55 +8,9 @@ export async function loadPlannedEntries(options, chunkSizeBytes, outcomes) {
     const loaded = [];
     const loadedByObjectKey = new Map();
     for (const file of options.files) {
-        let stat;
-        try {
-            stat = await fs.stat(file.local_path);
-        }
-        catch (error) {
-            // `file_read_failed` is a durable ledger label and stays. Beside it: a
-            // staged object that vanished (the GC won a race) and one the process
-            // has no permission to open are the same word and opposite repairs
-            // (BLI-3238).
-            console.error("[evidence-upload] staged object could not be stat'd", JSON.stringify({
-                reason: "file_read_failed",
-                stage: "stat",
-                ...describeError(error),
-            }));
-            outcomes.push(failedOutcome(file, "file_read_failed"));
-            continue;
-        }
-        if (stat.size === 0) {
-            outcomes.push(failedOutcome(file, "empty_file"));
+        const bytes = await readStagedUploadBytes(file, outcomes);
+        if (!bytes)
             continue;
-        }
-        if (stat.size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
-            outcomes.push(failedOutcome(file, "file_too_large"));
-            continue;
-        }
-        let bytes;
-        try {
-            bytes = await fs.readFile(file.local_path);
-        }
-        catch (error) {
-            // Stat succeeded and the read did not — narrower than the stat failure
-            // above and worth telling apart, so it carries its own stage label.
-            console.error("[evidence-upload] staged object could not be read after a successful stat", JSON.stringify({
-                reason: "file_read_failed",
-                stage: "read",
-                byte_size: stat.size,
-                ...describeError(error),
-            }));
-            outcomes.push(failedOutcome(file, "file_read_failed"));
-            continue;
-        }
-        if (bytes.byteLength === 0) {
-            outcomes.push(failedOutcome(file, "empty_file"));
-            continue;
-        }
-        if (bytes.byteLength > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
-            outcomes.push(failedOutcome(file, "file_too_large"));
-            continue;
-        }
         // Content-addressed keys collide for byte-identical files (e.g. a resumed
         // session copied twice); upload once and share the outcome instead of
         // racing a second upload against a committed ledger row.
@@ -80,6 +34,58 @@ export async function loadPlannedEntries(options, chunkSizeBytes, outcomes) {
     }
     return loaded;
 }
+async function readStagedUploadBytes(file, outcomes) {
+    let stat;
+    try {
+        stat = await fs.stat(file.local_path);
+    }
+    catch (error) {
+        // `file_read_failed` is a durable ledger label and stays. Beside it: a
+        // staged object that vanished (the GC won a race) and one the process
+        // has no permission to open are the same word and opposite repairs
+        // (BLI-3238).
+        console.error("[evidence-upload] staged object could not be stat'd", JSON.stringify({
+            reason: "file_read_failed",
+            stage: "stat",
+            ...describeError(error),
+        }));
+        outcomes.push(failedOutcome(file, "file_read_failed"));
+        return null;
+    }
+    if (stat.size === 0) {
+        outcomes.push(failedOutcome(file, "empty_file"));
+        return null;
+    }
+    if (stat.size > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+        outcomes.push(failedOutcome(file, "file_too_large"));
+        return null;
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(file.local_path);
+    }
+    catch (error) {
+        // Stat succeeded and the read did not — narrower than the stat failure
+        // above and worth telling apart, so it carries its own stage label.
+        console.error("[evidence-upload] staged object could not be read after a successful stat", JSON.stringify({
+            reason: "file_read_failed",
+            stage: "read",
+            byte_size: stat.size,
+            ...describeError(error),
+        }));
+        outcomes.push(failedOutcome(file, "file_read_failed"));
+        return null;
+    }
+    if (bytes.byteLength === 0) {
+        outcomes.push(failedOutcome(file, "empty_file"));
+        return null;
+    }
+    if (bytes.byteLength > RAW_EVIDENCE_UPLOAD_MAX_FILE_BYTES) {
+        outcomes.push(failedOutcome(file, "file_too_large"));
+        return null;
+    }
+    return bytes;
+}
 export function batches(items, size) {
     const out = [];
     for (let offset = 0; offset < items.length; offset += size) {
@@ -112,43 +118,11 @@ export async function resolveBeginBatch(options, totalLoadedCount, batch, chunkS
     // (after retries) covers a new dashboard whose ledger migration has not
     // been applied yet. Both still serve the legacy v1 route.
     if (begin.status === 404 || begin.status >= 500) {
-        // Until BLI-3483 this downgrade abandoned the entire chunked path
-        // without a word, and the comment above named two causes that the fleet
-        // had no way to tell apart — an old dashboard versus an unapplied ledger
-        // migration. This is the BLI-2528 shape exactly: the code knew, the
-        // operator did not. Once per run, because `break` leaves the loop.
-        console.error("[evidence-upload] chunked upload unavailable; falling back to the legacy single-shot route", JSON.stringify({
-            reason: begin.status === 404
-                ? "begin_route_absent"
-                : "begin_server_error_after_retries",
-            http_status: begin.status,
-            server_reason: safeFailureDetail(begin.body) ?? "none",
-            objects_in_batch: batch.length,
-            objects_unresolved: totalLoadedCount - resolvedEntries.size,
-        }));
+        reportBeginFallback(begin, batch.length, totalLoadedCount - resolvedEntries.size);
         return true;
     }
-    if (!begin.ok) {
-        // The server's own `{ reason }` sat unread in this body while the ledger
-        // recorded the transport status and nothing else (BLI-3483); the commit
-        // path has read it since BLI-2528 and this one now does the same.
-        const beginDetail = safeFailureDetail(begin.body);
-        const beginReason = `begin_failed_http_${begin.status}${beginDetail ? `_${beginDetail}` : ""}`;
-        console.error("[evidence-upload] begin refused these objects", JSON.stringify({
-            reason: "begin_rejected",
-            http_status: begin.status,
-            server_reason: beginDetail ?? "none",
-            objects_in_batch: batch.length,
-        }));
-        for (const entry of batch) {
-            outcomes.push(failedOutcome(entry.file, beginReason));
-            for (const duplicate of entry.duplicates) {
-                outcomes.push(failedOutcome(duplicate, beginReason));
-            }
-            resolvedEntries.add(entry);
-        }
-        return false;
-    }
+    if (!begin.ok)
+        return rejectBeginBatch(begin, batch, outcomes, resolvedEntries);
     const parsedBegin = RawEvidenceUploadBeginResponseSchema.safeParse(begin.body);
     if (!parsedBegin.success) {
         for (const entry of batch) {
@@ -177,6 +151,43 @@ export async function resolveBeginBatch(options, totalLoadedCount, batch, chunkS
     }
     return false;
 }
+function rejectBeginBatch(begin, batch, outcomes, resolvedEntries) {
+    // The server's own `{ reason }` sat unread in this body while the ledger
+    // recorded the transport status and nothing else (BLI-3483); the commit
+    // path has read it since BLI-2528 and this one now does the same.
+    const beginDetail = safeFailureDetail(begin.body);
+    const beginReason = `begin_failed_http_${begin.status}${beginDetail ? `_${beginDetail}` : ""}`;
+    console.error("[evidence-upload] begin refused these objects", JSON.stringify({
+        reason: "begin_rejected",
+        http_status: begin.status,
+        server_reason: beginDetail ?? "none",
+        objects_in_batch: batch.length,
+    }));
+    for (const entry of batch) {
+        outcomes.push(failedOutcome(entry.file, beginReason));
+        for (const duplicate of entry.duplicates) {
+            outcomes.push(failedOutcome(duplicate, beginReason));
+        }
+        resolvedEntries.add(entry);
+    }
+    return false;
+}
+function reportBeginFallback(begin, objectsInBatch, objectsUnresolved) {
+    // Until BLI-3483 this downgrade abandoned the entire chunked path
+    // without a word, and the comment above named two causes that the fleet
+    // had no way to tell apart — an old dashboard versus an unapplied ledger
+    // migration. This is the BLI-2528 shape exactly: the code knew, the
+    // operator did not. Once per run, because `break` leaves the loop.
+    console.error("[evidence-upload] chunked upload unavailable; falling back to the legacy single-shot route", JSON.stringify({
+        reason: begin.status === 404
+            ? "begin_route_absent"
+            : "begin_server_error_after_retries",
+        http_status: begin.status,
+        server_reason: safeFailureDetail(begin.body) ?? "none",
+        objects_in_batch: objectsInBatch,
+        objects_unresolved: objectsUnresolved,
+    }));
+}
 /**
  * One accepted object: settle a re-keyable conflict if `begin` reported one
  * (BLI-3552), then chunk/commit it, then tell the server if the attempt was

package/dist/evidence-upload-terminal.js

@@ -11,19 +11,9 @@ import { requestJson, safeFailureDetail } from "./evidence-upload-transport.js";
  * summarize a run's outcomes into the shape every caller reads.
  */
 /**
- * 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.
+ * A committed key holding different bytes needs a new content-derived name.
+ * Retry re-keying once without deleting durable evidence. If no safe name can
+ * be offered, retain the original conflict so the cursor never claims success.
  */
 export async function rekeyConflictedEntry(options, entry, disposition, chunkSizeBytes) {
     if (disposition.disposition !== "conflict" ||
@@ -216,43 +206,7 @@ export async function uploadWithLegacyFallback(options, loaded, outcomes) {
                 },
             ],
         });
-        if (response.ok) {
-            const parsedLegacy = RawEvidenceLegacyUploadResponseSchema.safeParse(response.body);
-            if (!parsedLegacy.success) {
-                outcome = failedOutcome(entry.file, "legacy_upload_invalid_response");
-            }
-            else {
-                const receipt = parsedLegacy.data.uploaded.find((candidate) => candidate.raw_evidence_pointer_id ===
-                    entry.file.pointer.raw_evidence_pointer_id);
-                if (!receipt ||
-                    parsedLegacy.data.bucket !== entry.file.pointer.storage_bucket ||
-                    !legacyUploadReceiptMatchesPointer(entry.file.pointer, receipt)) {
-                    outcome = failedOutcome(entry.file, "legacy_upload_receipt_mismatch");
-                }
-                else {
-                    const pointer = pointerWithLegacyUploadResponse(entry.file.pointer, parsedLegacy.data);
-                    outcome = {
-                        pointer,
-                        object_key: entry.file.pointer.object_key ?? "",
-                        codex_session_id: entry.file.codex_session_id ?? null,
-                        kind: entry.file.kind ?? "unknown",
-                        artifact_metadata: entry.file.artifact_metadata,
-                        upload_state: "uploaded",
-                        reason: "legacy_single_shot_upload",
-                        uploaded_chunk_count: 1,
-                    };
-                }
-            }
-        }
-        else if (response.status === 409) {
-            // The pre-ledger route cannot prove that a conflicting object contains
-            // these exact bytes. Fail closed instead of seeding the cursor with an
-            // unverified pointer.
-            outcome = failedOutcome(entry.file, "legacy_upload_conflict_http_409");
-        }
-        else {
-            outcome = failedOutcome(entry.file, `legacy_upload_failed_http_${response.status}`);
-        }
+        outcome = legacyUploadOutcome(entry.file, response);
         outcomes.push(outcome);
         for (const duplicate of entry.duplicates) {
             outcomes.push(duplicateOutcome(outcome, duplicate));
@@ -260,6 +214,47 @@ export async function uploadWithLegacyFallback(options, loaded, outcomes) {
     }
     return summarizeOutcomes(outcomes, true);
 }
+function legacyUploadOutcome(file, response) {
+    let outcome;
+    if (response.ok) {
+        const parsedLegacy = RawEvidenceLegacyUploadResponseSchema.safeParse(response.body);
+        if (!parsedLegacy.success) {
+            outcome = failedOutcome(file, "legacy_upload_invalid_response");
+        }
+        else {
+            const receipt = parsedLegacy.data.uploaded.find((candidate) => candidate.raw_evidence_pointer_id ===
+                file.pointer.raw_evidence_pointer_id);
+            if (!receipt ||
+                parsedLegacy.data.bucket !== file.pointer.storage_bucket ||
+                !legacyUploadReceiptMatchesPointer(file.pointer, receipt)) {
+                outcome = failedOutcome(file, "legacy_upload_receipt_mismatch");
+            }
+            else {
+                const pointer = pointerWithLegacyUploadResponse(file.pointer, parsedLegacy.data);
+                outcome = {
+                    pointer,
+                    object_key: file.pointer.object_key ?? "",
+                    codex_session_id: file.codex_session_id ?? null,
+                    kind: file.kind ?? "unknown",
+                    artifact_metadata: file.artifact_metadata,
+                    upload_state: "uploaded",
+                    reason: "legacy_single_shot_upload",
+                    uploaded_chunk_count: 1,
+                };
+            }
+        }
+    }
+    else if (response.status === 409) {
+        // The pre-ledger route cannot prove that a conflicting object contains
+        // these exact bytes. Fail closed instead of seeding the cursor with an
+        // unverified pointer.
+        outcome = failedOutcome(file, "legacy_upload_conflict_http_409");
+    }
+    else {
+        outcome = failedOutcome(file, `legacy_upload_failed_http_${response.status}`);
+    }
+    return outcome;
+}
 function pointerWithLegacyUploadResponse(pointer, body) {
     const entry = body.uploaded.find((candidate) => candidate.raw_evidence_pointer_id === pointer.raw_evidence_pointer_id);
     if (!entry)

package/dist/image-description-session.js

@@ -1,25 +1,9 @@
 /**
- * One sync's handling of the images inside transcripts (BLI-16977).
- *
- * `prepareTranscript` takes a transcript's text just before it is masked and staged and does four
- * things, in this order:
- *
- *  1. FIND every embedded image (`transcript-images.ts` in telemetry-core) and group them by sha256.
- *  2. DESCRIBE each distinct image that this machine has not already sent: one POST per image to
- *     the describe door, a few at a time, inside a per-sync count and time budget. The state file
- *     remembers what was sent, so a screenshot that appears in 40 turns, or in 3 sessions, is sent
- *     once. A failure never fails the transcript.
- *  3. REPLACE, only when this machine's mode (set per machine from Tower, kept on file by
- *     `image-mode-state.ts`; the fleet default is `IMAGE_HANDLING_MODE` in telemetry-core) says
- *     `describe_and_drop`: every image whose description is stored becomes its short marker. An
- *     image with no stored description is KEPT. In `describe_and_keep` (the default) the text
- *     comes back byte for byte as it went in.
- *  4. SLIM, only in `describe_and_drop`: the slim transcript (src/slim/): the duplicate copies and
- *     the bookkeeping go, every line stays. In `describe_and_keep` the slim form is not computed
- *     and not uploaded.
- *
- * Metadata only in the logs: counts, sizes, hashes, reason labels. Never image bytes, never a
- * description.
+ * Share image descriptions and count/time budgets across one sync's transcripts.
+ * Describe each distinct image once. Keep images without stored descriptions;
+ * only describe_and_drop replaces described images and then runs the slim rules.
+ * Failures never fail the transcript. Logs contain metadata, never image bytes
+ * or descriptions.
  */
 import { IMAGE_DESCRIBE_MAX_BYTES, IMAGE_HANDLING_MODE, base64Of, findEmbeddedImages, replaceImagesWithMarkers, } from "@bli-cockpit/telemetry-core";
 import { postImageToDescribeDoor } from "./image-describe-client.js";
@@ -38,144 +22,18 @@ export async function openImageDescriptions(options) {
     const described = new Set(await readDescribedImageKeys(options.stateDir));
     const orderedKeys = [...described];
     const failedImages = await readFailedImages(options.stateDir);
-    let stateDirty = false;
+    const stateDirty = false;
     const settledThisRun = new Map();
     const now = options.now ?? Date.now;
     const startedAt = now();
     const maxPerRun = options.maxPerRun ?? IMAGE_DESCRIBE_MAX_PER_RUN;
     const maxRunMs = options.maxRunMs ?? IMAGE_DESCRIBE_MAX_RUN_MS;
-    let sentThisRun = 0;
-    const markDescribed = (sha256) => {
-        const key = imageStateKey(sha256);
-        if (described.has(key))
-            return;
-        described.add(key);
-        orderedKeys.push(key);
-    };
-    async function sendOne(image, text, input) {
-        sentThisRun += 1;
-        const outcome = await postImageToDescribeDoor({ fetchImpl, dashboardUrl: options.dashboardUrl, deviceToken: options.deviceToken, sleep: options.sleep }, {
-            schema_version: "image-describe.v1",
-            sha256: image.sha256,
-            media_type: image.mediaType,
-            byte_size: image.byteSize,
-            content_base64: base64Of(text, image),
-            source: input.source,
-            session_id: input.sessionId.slice(0, 200),
-        });
-        const key = imageStateKey(image.sha256);
-        if (outcome.ok) {
-            markDescribed(image.sha256);
-            settledThisRun.set(image.sha256, outcome.status);
-            if (failedImages[key]) {
-                delete failedImages[key];
-                stateDirty = true;
-            }
-            return;
-        }
-        settledThisRun.set(image.sha256, `failed:${outcome.reason}`);
-        rememberFailure(key, outcome);
-    }
-    /**
-     * BLI-16979: the door answered about THIS image and could not describe it (a 4xx such as
-     * `describer_rejected_image`, or a 5xx). Wait before sending the same bytes again, instead of
-     * re-sending them every sync. A transport error, a 401 and a 429 say nothing about the image, so
-     * they are not remembered.
-     */
-    function rememberFailure(key, outcome) {
-        if (outcome.httpStatus < 400 || outcome.httpStatus === 401 || outcome.httpStatus === 429)
-            return;
-        const attempts = (failedImages[key]?.attempts ?? 0) + 1;
-        const delay = imageRetryDelayMs(attempts, outcome.permanent);
-        failedImages[key] = { reason: outcome.reason, attempts, retry_after: now() + delay };
-        stateDirty = true;
-        console.error(TAG + " image not described, will not be re-sent until later", JSON.stringify({ reason: outcome.reason, http_status: outcome.httpStatus, attempts, retry_in_hours: Math.round(delay / 3_600_000), sha256_prefix: key.slice(0, 16) }));
-    }
-    async function describeAndReplace(input) {
-        const images = findEmbeddedImages(input.text);
-        if (images.length === 0)
-            return { text: input.text, imageCount: 0, uniqueCount: 0, replacedCount: 0, charsSaved: 0 };
-        const unique = new Map();
-        for (const image of images)
-            if (!unique.has(image.sha256))
-                unique.set(image.sha256, image);
-        const counts = { already: 0, described_now: 0, known: 0, too_large: 0, over_budget: 0, failed: 0, backing_off: 0 };
-        const failedReasons = {};
-        const toSend = [];
-        for (const image of unique.values()) {
-            if (described.has(imageStateKey(image.sha256))) {
-                counts.already += 1;
-                continue;
-            }
-            const earlier = settledThisRun.get(image.sha256);
-            if (earlier)
-                continue;
-            if (image.byteSize > IMAGE_DESCRIBE_MAX_BYTES) {
-                settledThisRun.set(image.sha256, "too_large");
-                counts.too_large += 1;
-                continue;
-            }
-            const earlierFailure = failedImages[imageStateKey(image.sha256)];
-            if (earlierFailure && earlierFailure.retry_after > now()) {
-                counts.backing_off += 1;
-                continue;
-            }
-            toSend.push(image);
-        }
-        let next = 0;
-        const worker = async () => {
-            while (next < toSend.length) {
-                const image = toSend[next++];
-                if (sentThisRun >= maxPerRun || now() - startedAt > maxRunMs) {
-                    counts.over_budget += 1;
-                    continue;
-                }
-                await sendOne(image, input.text, input);
-            }
-        };
-        await Promise.all(Array.from({ length: Math.min(CONCURRENCY, toSend.length) }, worker));
-        for (const image of toSend) {
-            const settled = settledThisRun.get(image.sha256);
-            if (settled === "described")
-                counts.described_now += 1;
-            else if (settled === "known")
-                counts.known += 1;
-            else if (settled?.startsWith("failed:")) {
-                counts.failed += 1;
-                const reason = settled.slice("failed:".length);
-                failedReasons[reason] = (failedReasons[reason] ?? 0) + 1;
-            }
-        }
-        if (counts.described_now + counts.known > 0 || stateDirty) {
-            await writeImageDescriptionState(options.stateDir, { described: orderedKeys, failed: failedImages });
-            stateDirty = false;
-        }
-        const replaced = mode === "describe_and_drop"
-            ? replaceImagesWithMarkers(input.text, images, (image) => described.has(imageStateKey(image.sha256)))
-            : { text: input.text, replacedCount: 0, charsSaved: 0 };
-        console.error(TAG + " transcript prepared", JSON.stringify({
-            mode,
-            source: input.source,
-            images: images.length,
-            unique: unique.size,
-            ...counts,
-            failed_reasons: failedReasons,
-            replaced: replaced.replacedCount,
-            chars_saved: replaced.charsSaved,
-            kept_without_description: mode === "describe_and_drop" ? images.length - replaced.replacedCount : 0,
-        }));
-        return {
-            text: replaced.text,
-            imageCount: images.length,
-            uniqueCount: unique.size,
-            replacedCount: replaced.replacedCount,
-            charsSaved: replaced.charsSaved,
-        };
-    }
+    const sentThisRun = 0;
+    const run = { options, mode, fetchImpl, described, orderedKeys, failedImages, stateDirty, settledThisRun, now, startedAt, maxPerRun, maxRunMs, sentThisRun };
     return {
         mode,
         async prepareTranscript(input) {
-            const afterImages = await describeAndReplace(input);
+            const afterImages = await describeAndReplace(run, input);
             if (mode !== "describe_and_drop")
                 return { ...afterImages, text: input.text, changed: false, slim: null };
             const slim = slimOrKeep(afterImages.text, input.source, { sessionId: input.sessionId });
@@ -183,11 +41,152 @@ export async function openImageDescriptions(options) {
         },
     };
 }
+function markDescribed(run, sha256) {
+    const { described, orderedKeys } = run;
+    const key = imageStateKey(sha256);
+    if (described.has(key))
+        return;
+    described.add(key);
+    orderedKeys.push(key);
+}
+async function sendOne(run, image, text, input) {
+    const { options, fetchImpl, settledThisRun, failedImages } = run;
+    run.sentThisRun += 1;
+    const outcome = await postImageToDescribeDoor({ fetchImpl, dashboardUrl: options.dashboardUrl, deviceToken: options.deviceToken, sleep: options.sleep }, {
+        schema_version: "image-describe.v1",
+        sha256: image.sha256,
+        media_type: image.mediaType,
+        byte_size: image.byteSize,
+        content_base64: base64Of(text, image),
+        source: input.source,
+        session_id: input.sessionId.slice(0, 200),
+    });
+    const key = imageStateKey(image.sha256);
+    if (outcome.ok) {
+        markDescribed(run, image.sha256);
+        settledThisRun.set(image.sha256, outcome.status);
+        if (failedImages[key]) {
+            delete failedImages[key];
+            run.stateDirty = true;
+        }
+        return;
+    }
+    settledThisRun.set(image.sha256, `failed:${outcome.reason}`);
+    rememberFailure(run, key, outcome);
+}
+/**
+ * Remember image-specific HTTP failures for backoff. Transport failures, 401
+ * and 429 say nothing about the image and must not be remembered.
+ */
+function rememberFailure(run, key, outcome) {
+    const { failedImages, now } = run;
+    if (outcome.httpStatus < 400 || outcome.httpStatus === 401 || outcome.httpStatus === 429)
+        return;
+    const attempts = (failedImages[key]?.attempts ?? 0) + 1;
+    const delay = imageRetryDelayMs(attempts, outcome.permanent);
+    failedImages[key] = { reason: outcome.reason, attempts, retry_after: now() + delay };
+    run.stateDirty = true;
+    console.error(TAG + " image not described, will not be re-sent until later", JSON.stringify({ reason: outcome.reason, http_status: outcome.httpStatus, attempts, retry_in_hours: Math.round(delay / 3_600_000), sha256_prefix: key.slice(0, 16) }));
+}
+async function describeAndReplace(run, input) {
+    const { mode, described, options, orderedKeys, failedImages } = run;
+    const images = findEmbeddedImages(input.text);
+    if (images.length === 0)
+        return { text: input.text, imageCount: 0, uniqueCount: 0, replacedCount: 0, charsSaved: 0 };
+    const unique = new Map();
+    for (const image of images)
+        if (!unique.has(image.sha256))
+            unique.set(image.sha256, image);
+    const counts = { already: 0, described_now: 0, known: 0, too_large: 0, over_budget: 0, failed: 0, backing_off: 0 };
+    const toSend = selectImagesToDescribe(run, unique, counts);
+    await sendPendingImages(run, toSend, counts, input);
+    const failedReasons = countImageOutcomes(run, toSend, counts);
+    if (counts.described_now + counts.known > 0 || run.stateDirty) {
+        await writeImageDescriptionState(options.stateDir, { described: orderedKeys, failed: failedImages });
+        run.stateDirty = false;
+    }
+    const replaced = mode === "describe_and_drop"
+        ? replaceImagesWithMarkers(input.text, images, (image) => described.has(imageStateKey(image.sha256)))
+        : { text: input.text, replacedCount: 0, charsSaved: 0 };
+    console.error(TAG + " transcript prepared", JSON.stringify({
+        mode,
+        source: input.source,
+        images: images.length,
+        unique: unique.size,
+        ...counts,
+        failed_reasons: failedReasons,
+        replaced: replaced.replacedCount,
+        chars_saved: replaced.charsSaved,
+        kept_without_description: mode === "describe_and_drop" ? images.length - replaced.replacedCount : 0,
+    }));
+    return {
+        text: replaced.text,
+        imageCount: images.length,
+        uniqueCount: unique.size,
+        replacedCount: replaced.replacedCount,
+        charsSaved: replaced.charsSaved,
+    };
+}
+function selectImagesToDescribe(run, unique, counts) {
+    const { described, settledThisRun, failedImages, now } = run;
+    const toSend = [];
+    for (const image of unique.values()) {
+        if (described.has(imageStateKey(image.sha256))) {
+            counts.already += 1;
+            continue;
+        }
+        const earlier = settledThisRun.get(image.sha256);
+        if (earlier)
+            continue;
+        if (image.byteSize > IMAGE_DESCRIBE_MAX_BYTES) {
+            settledThisRun.set(image.sha256, "too_large");
+            counts.too_large += 1;
+            continue;
+        }
+        const earlierFailure = failedImages[imageStateKey(image.sha256)];
+        if (earlierFailure && earlierFailure.retry_after > now()) {
+            counts.backing_off += 1;
+            continue;
+        }
+        toSend.push(image);
+    }
+    return toSend;
+}
+async function sendPendingImages(run, toSend, counts, input) {
+    const { now, maxPerRun, startedAt, maxRunMs } = run;
+    let next = 0;
+    const worker = async () => {
+        while (next < toSend.length) {
+            const image = toSend[next++];
+            if (run.sentThisRun >= maxPerRun || now() - startedAt > maxRunMs) {
+                counts.over_budget += 1;
+                continue;
+            }
+            await sendOne(run, image, input.text, input);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(CONCURRENCY, toSend.length) }, worker));
+}
+function countImageOutcomes(run, toSend, counts) {
+    const { settledThisRun } = run;
+    const failedReasons = {};
+    for (const image of toSend) {
+        const settled = settledThisRun.get(image.sha256);
+        if (settled === "described")
+            counts.described_now += 1;
+        else if (settled === "known")
+            counts.known += 1;
+        else if (settled?.startsWith("failed:")) {
+            counts.failed += 1;
+            const reason = settled.slice("failed:".length);
+            failedReasons[reason] = (failedReasons[reason] ?? 0) + 1;
+        }
+    }
+    return failedReasons;
+}
 /**
- * What the uploader sends for this transcript text, worked out offline (BLI-17013). Keep mode: the
- * text as it is. Drop mode: every image whose key is in `describedKeys` becomes its marker, then
- * the slim rules run, the same two steps as `prepareTranscript` above, with no describe-door call.
- * `cockpit sources check` uses it so a complete upload is judged against the bytes actually uploaded.
+ * Let source checks compare against the actual upload form without network calls.
+ * Drop mode replaces known images, then slims; keep mode preserves all text.
  */
 export function uploadFormOfTranscript(text, source, mode, describedKeys) {
     if (mode !== "describe_and_drop")
@@ -197,10 +196,8 @@ export function uploadFormOfTranscript(text, source, mode, describedKeys) {
     return slimTranscript(replaced.text, source).text;
 }
 /**
- * The image step for one build of an envelope. When a sync-wide budget is shared across worktrees
- * the session lives on it (one count budget and one state file for the whole sync); otherwise this
- * build gets its own. A failure to open it is logged by name and the transcripts simply go up as
- * they are.
+ * Reuse the sync-wide image budget across worktrees. If opening fails, log the
+ * reason and upload the original transcripts.
  */
 export async function openImageStepForSync(options) {
     if (options.budget?.images)