@haystackeditor/cli 0.15.31 → 0.17.0

package/dist/commands/case-batch.js

@@ -0,0 +1,1011 @@
+/**
+ * `haystack case-batch` — submit an already-generated product-fuzzing case
+ * batch to the hosted coordinator, poll it, cancel it, and fetch its replay
+ * bundle. Lane D of docs/case-batch-coordinator.md: the laptop only submits
+ * and polls.
+ *
+ * The CLI holds no fleet credential. Every request below carries exactly one
+ * credential, the caller's Haystack login bearer resolved by
+ * `resolveAuthContext`; nothing here reads HAYSTACK_API_TOKEN, a queue service
+ * token, or a control-plane lease. Case generation, ranking, confirmation,
+ * shrinking and judging stay on the submitting side and are not here either.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, resolve, sep } from 'node:path';
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { classifyHttpError, HaystackApiError, haystackApiUrl } from '../utils/haystack-api.js';
+import { boundedCaseBatchJson, buildCaseBatchRequest, CASE_BATCH_MAX_CASES, CASE_BATCH_MAX_CONCURRENT_CASES, CASE_BATCH_MAX_INPUT_BYTES, CASE_BATCH_MAX_CASE_WALL_MS, CASE_BATCH_MAX_TOTAL_BUDGET_MS, CASE_BATCH_MIN_CASE_WALL_MS, CASE_BATCH_MIN_TOTAL_BUDGET_MS, CaseBatchRequestValidationError, CaseBatchResponseError, isJsonObject, isTerminalCaseBatchStatus, parseCaseBatchCommit, parseCaseBatchIdempotencyKey, parseCaseBatchLimits, parseCaseBatchRepository, parseCaseBatchSnapshot, parseCaseBatchSource, parseCaseBatchWorld, parseProductCases, } from './case-batch-contract.js';
+/** The CLI gateway mount. The same worker handlers are `/v1/case-batches` and
+ * `/api/cloud-verifier/case-batches`; CLI callers use the agent gateway, as
+ * they already do for `/api/agent/cloud-verifier/searches`.
+ *
+ * BLOCKED ON THE SERVER LANE. No handler serves this path in this repository
+ * yet, and the auth worker does not proxy it: `isSearchProxyPath` in
+ * `infra/auth-worker/index.js` covers `/api/agent/cloud-verifier/searches`
+ * only, and `agent/cloudflare/src/combination-search-route.ts` has no
+ * case-batch sibling. Until Lane A of `docs/case-batch-coordinator.md` lands
+ * `POST/GET /v1/case-batches`, `GET/DELETE /v1/case-batches/:runId`,
+ * `GET /v1/case-batches/:runId/bundle[/path]` and the matching auth-worker
+ * proxy entry, every command in this file reaches a 404 in production. That
+ * lane must merge first; this file is written against the frozen contract
+ * ahead of it, which is what the implementation plan assigns to Lane D.
+ *
+ * Three things the server side must hold for this file to work as written:
+ * the 8 MiB request bound, `repository`-scoped reads with `limit` and
+ * `caseCursor` pagination, and a bundle route that serves each sealed object's
+ * SHA-256 as its ETag (the manifest's is required here, because the manifest
+ * is the one artifact with no parent digest to check it against). */
+const GATEWAY = '/api/agent/cloud-verifier/case-batches';
+const RUN_ID = /^cv_[0-9a-f]{48}$/;
+/** Page size for the bounded case pagination; the search read route caps
+ * `limit` at 500 and the batch read mirrors it. */
+const CASE_PAGE_LIMIT = 500;
+/** A hard stop on pagination independent of what the server reports, so a
+ * cursor that never terminates cannot spin the CLI forever. */
+const MAX_CASE_PAGES = Math.ceil(CASE_BATCH_MAX_CASES / CASE_PAGE_LIMIT) + 2;
+const DEFAULT_POLL_INTERVAL_SECONDS = 10;
+const DEFAULT_POLL_MAX_WALL_MINUTES = 45;
+const MAX_POLL_INTERVAL_SECONDS = 300;
+const MAX_POLL_MAX_WALL_MINUTES = 240;
+/** Per-case wall default. The MVP measured 66.8 s min / 78.8 s median /
+ * 103.8 s max over its 48 executed cases (docs/case-batch-coordinator.md), so
+ * this sits above the measured maximum: the default kills a hung guest without
+ * killing a case that runs at today's measured cost. The 15 s acceptance
+ * target is what the fleet work is chasing, not a safe default to impose. */
+const DEFAULT_PER_CASE_WALL_MS = 120_000;
+/** Launch budget default: the contract ceiling. The budget bounds launches,
+ * not the run, and a shorter one silently truncates a large batch. */
+const DEFAULT_TOTAL_BUDGET_MS = CASE_BATCH_MAX_TOTAL_BUDGET_MS;
+const MAX_BUNDLE_ARTIFACTS = 20_000;
+const MAX_BUNDLE_BYTES = 512 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 64 * 1024 * 1024;
+function readJsonFile(path, flag) {
+    if (typeof path !== 'string' || path.length === 0) {
+        throw new CaseBatchRequestValidationError(`${flag} is required and must name a JSON file.`);
+    }
+    let source;
+    try {
+        source = readFileSync(path, 'utf8');
+    }
+    catch (error) {
+        throw new CaseBatchRequestValidationError(`Could not read ${flag} "${path}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (Buffer.byteLength(source) > CASE_BATCH_MAX_INPUT_BYTES) {
+        throw new CaseBatchRequestValidationError(`${flag} "${path}" is larger than the ${CASE_BATCH_MAX_INPUT_BYTES}-byte case-batch request bound.`);
+    }
+    try {
+        return JSON.parse(source);
+    }
+    catch {
+        throw new CaseBatchRequestValidationError(`${flag} "${path}" must contain valid JSON.`);
+    }
+}
+function flagInteger(value, fallback, flag, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d{1,15}$/.test(value)) {
+        throw new CaseBatchRequestValidationError(`${flag} must be a whole number from ${minimum} to ${maximum}.`);
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
+        throw new CaseBatchRequestValidationError(`${flag} must be a whole number from ${minimum} to ${maximum}.`);
+    }
+    return parsed;
+}
+function requireRunId(runId) {
+    if (!RUN_ID.test(runId)) {
+        throw new CaseBatchRequestValidationError('Run id must be the exact cv_ id returned by `haystack case-batch submit` (cv_ plus 48 lowercase hex characters).');
+    }
+    return runId;
+}
+/** Every outbound request. The header set is built here and nowhere else, so
+ * the credential surface of this command is one line: the login bearer. */
+async function gatewayFetch(path, token, init = { method: 'GET' }) {
+    const headers = new Headers();
+    headers.set('Authorization', `Bearer ${token}`);
+    headers.set('Accept', init.accept ?? 'application/json');
+    headers.set('User-Agent', 'Haystack-CLI');
+    if (init.body !== undefined)
+        headers.set('Content-Type', 'application/json');
+    return fetch(haystackApiUrl(path), {
+        method: init.method,
+        headers,
+        ...(init.body === undefined ? {} : { body: init.body }),
+        signal: AbortSignal.timeout(120_000),
+    });
+}
+async function gatewayJson(path, token, init = { method: 'GET' }) {
+    const response = await gatewayFetch(path, token, init);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${path}`);
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new CaseBatchResponseError(`Case batch service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return { status: response.status, body };
+}
+function repositoryQuery(repository) {
+    return `repository=${encodeURIComponent(repository)}`;
+}
+async function authFor(repository, account) {
+    const parsed = parseCaseBatchRepository(repository);
+    const auth = await resolveAuthContext({
+        preferredLogin: account,
+        owner: parsed.owner,
+        repo: parsed.name,
+    });
+    return { repository: parsed, auth };
+}
+/* ------------------------------------------------------------------ submit */
+export function defaultCaseBatchIdempotencyKey(request) {
+    return `case-batch:${createHash('sha256').update(JSON.stringify(request)).digest('hex')}`;
+}
+export function prepareCaseBatchSubmission(options) {
+    if (typeof options.repository !== 'string' || options.repository.length === 0) {
+        throw new CaseBatchRequestValidationError('--repository is required and must be an exact GitHub owner/repository name.');
+    }
+    const repository = parseCaseBatchRepository(options.repository);
+    const baseCommit = parseCaseBatchCommit(options.base, '--base');
+    const headCommit = parseCaseBatchCommit(options.head, '--head');
+    const baseWorld = options.baseWorld === undefined ? undefined : parseCaseBatchWorld(options.baseWorld, '--base-world');
+    const headWorld = options.headWorld === undefined ? undefined : parseCaseBatchWorld(options.headWorld, '--head-world');
+    if (options.driverBundle !== undefined && !/^[0-9a-f]{64}$/u.test(options.driverBundle))
+        throw new CaseBatchRequestValidationError('--driver-bundle must be the resident probe bundle sha256 (64 lowercase hex).');
+    const driver = options.driverBundle === undefined ? undefined : { mode: 'resident', bundleSha256: options.driverBundle };
+    const cases = parseProductCases(readJsonFile(options.cases, '--cases'));
+    const combinations = boundedCaseBatchJson(readJsonFile(options.combinations, '--combinations'), 'combination space');
+    const limits = parseCaseBatchLimits({
+        // A ceiling, not a reservation: effective concurrency is the smaller of
+        // this and what GET /v1/capacity leaves free. Defaulting to the batch's own
+        // size asks for exactly as much as the batch can use, capped by the
+        // contract ceiling, instead of inventing a number.
+        maxConcurrentCases: flagInteger(options.maxConcurrent, Math.min(cases.length, CASE_BATCH_MAX_CONCURRENT_CASES), '--max-concurrent', 1, CASE_BATCH_MAX_CONCURRENT_CASES),
+        perCaseWallMs: flagInteger(options.perCaseWallMs, DEFAULT_PER_CASE_WALL_MS, '--per-case-wall-ms', CASE_BATCH_MIN_CASE_WALL_MS, CASE_BATCH_MAX_CASE_WALL_MS),
+        totalBudgetMs: flagInteger(options.totalBudgetMs, DEFAULT_TOTAL_BUDGET_MS, '--total-budget-ms', CASE_BATCH_MIN_TOTAL_BUDGET_MS, CASE_BATCH_MAX_TOTAL_BUDGET_MS),
+        // Absent unless given: an absent settle is the contract's 0 and leaves the request as before.
+        ...(options.warmSettleMs === undefined ? {} : {
+            warmSettleMs: flagInteger(options.warmSettleMs, 0, '--warm-settle-ms', 0, CASE_BATCH_MAX_CASE_WALL_MS),
+        }),
+    });
+    const source = options.sourcePatch === undefined
+        ? undefined
+        : parseCaseBatchSource(readJsonFile(options.sourcePatch, '--source-patch'), baseCommit, headCommit);
+    const identity = {
+        repository: repository.fullName,
+        baseCommit,
+        headCommit,
+        baseWorld: baseWorld ?? null,
+        headWorld: headWorld ?? null,
+        driver: driver ?? null,
+        combinations,
+        cases,
+        limits,
+        source: source ? source.patchSha256 : null,
+    };
+    const idempotencyKey = parseCaseBatchIdempotencyKey(options.idempotencyKey ?? defaultCaseBatchIdempotencyKey(identity));
+    const request = buildCaseBatchRequest({
+        repository: repository.fullName,
+        baseCommit,
+        headCommit,
+        idempotencyKey,
+        baseWorld,
+        headWorld,
+        driver,
+        combinations: combinations,
+        cases,
+        limits,
+        source,
+    });
+    return { repository, request, caseCount: cases.length, limits };
+}
+/** A refused submission: the HTTP answer, and the gateway's stable reason when it gave one
+ * (`world-pair-locked`, `idempotency-conflict`, `runner-unavailable`, ...). Callers switch on
+ * `reason`, never on the message. */
+export class CaseBatchAdmissionRefusedError extends HaystackApiError {
+    reason;
+    constructor(refusal, reason) {
+        super(refusal.status, refusal.message, refusal.code);
+        this.name = 'CaseBatchAdmissionRefusedError';
+        this.reason = reason;
+    }
+}
+/** `case-batch submit` as a library call: the same validation, the same login bearer and the same
+ * request. A caller that submits many batches (the product-fuzz search) runs this in its own
+ * process, so every request after the first reuses one warm connection instead of paying for a
+ * new process and a new TLS session per call. */
+export async function submitCaseBatch(options) {
+    // Validate every local input before touching credentials or the network.
+    const prepared = prepareCaseBatchSubmission(options);
+    const { auth } = await authFor(prepared.repository.fullName, options.account);
+    const response = await gatewayFetch(GATEWAY, auth.token, { method: 'POST', body: JSON.stringify(prepared.request) });
+    if (!response.ok) {
+        const copy = response.clone();
+        const refusal = await classifyHttpError(response, `Haystack API ${GATEWAY}`);
+        let reason = null;
+        try {
+            const body = await copy.json();
+            if (isJsonObject(body) && typeof body.reason === 'string')
+                reason = body.reason;
+        }
+        catch {
+            // Not JSON: the refusal above already carries the status and the readable part of the body.
+        }
+        throw new CaseBatchAdmissionRefusedError(refusal, reason);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new CaseBatchResponseError(`Case batch service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isJsonObject(body) || typeof body.runId !== 'string' || !RUN_ID.test(body.runId)) {
+        throw new CaseBatchResponseError('Case batch admission did not return a run id.');
+    }
+    // The search route answers 202 for a newly admitted run and 200 for an
+    // identical replay of an admitted idempotency key.
+    return { runId: body.runId, admitted: response.status === 200 ? 'existing' : 'created', prepared };
+}
+/** One bounded status read as a library call, with the bearer `case-batch status` would use. */
+export async function readCaseBatchStatus(runId, repository, account) {
+    requireRunId(runId);
+    const { repository: parsed, auth } = await authFor(repository, account);
+    return readCaseBatch(runId, parsed.fullName, auth.token);
+}
+export async function caseBatchSubmitCommand(options) {
+    if (!options.json) {
+        console.error(chalk.dim('Submitting cases to the hosted coordinator…'));
+    }
+    const { runId, admitted, prepared } = await submitCaseBatch(options);
+    const nextCommand = `haystack case-batch status ${runId} --repository ${prepared.repository.fullName} --watch`;
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'submit',
+            run_id: runId,
+            admitted,
+            repository: prepared.repository.fullName,
+            base_commit: prepared.request.baseCommit,
+            head_commit: prepared.request.headCommit,
+            idempotency_key: prepared.request.idempotencyKey,
+            cases: prepared.caseCount,
+            limits: {
+                max_concurrent_cases: prepared.limits.maxConcurrentCases,
+                per_case_wall_ms: prepared.limits.perCaseWallMs,
+                total_budget_ms: prepared.limits.totalBudgetMs,
+                ...(prepared.limits.warmSettleMs === undefined ? {} : { warm_settle_ms: prepared.limits.warmSettleMs }),
+            },
+            ...(prepared.request.baseWorld ? { base_world: prepared.request.baseWorld } : {}),
+            ...(prepared.request.headWorld ? { head_world: prepared.request.headWorld } : {}),
+            source_patch_attached: prepared.request.source !== undefined,
+            next_command: nextCommand,
+        }), null, 2)}\n`);
+        return;
+    }
+    console.log(`${chalk.cyan('•')} Case batch ${chalk.bold(runId)} ${admitted === 'existing' ? 'already admitted' : 'queued'}`);
+    console.log(`  ${chalk.dim('Repository:')} ${prepared.repository.fullName}`);
+    console.log(`  ${chalk.dim('Commits:')} ${prepared.request.baseCommit.slice(0, 12)} → ${prepared.request.headCommit.slice(0, 12)}`);
+    console.log(`  ${chalk.dim('Cases:')} ${prepared.caseCount}`);
+    console.log(`  ${chalk.dim('Limits:')} max ${prepared.limits.maxConcurrentCases} concurrent (ceiling; capacity decides), `
+        + `${prepared.limits.perCaseWallMs} ms per case, ${prepared.limits.totalBudgetMs} ms launch budget`);
+    console.log(`  ${chalk.dim('Idempotency key:')} ${prepared.request.idempotencyKey}`);
+    console.log(`  ${chalk.dim('Poll:')} ${nextCommand}`);
+}
+/** One bounded read: follow `nextCaseCursor` to the end of the case list. */
+export async function readCaseBatch(runId, repository, token) {
+    const collected = new Map();
+    let cursor = null;
+    let snapshot = null;
+    let pages = 0;
+    let wavesTruncated = false;
+    let truncated = false;
+    for (;;) {
+        const query = `?${repositoryQuery(repository)}&limit=${CASE_PAGE_LIMIT}`
+            + (cursor === null ? '' : `&caseCursor=${encodeURIComponent(cursor)}`);
+        const { body } = await gatewayJson(`${GATEWAY}/${encodeURIComponent(runId)}${query}`, token);
+        const page = parseCaseBatchSnapshot(body, runId);
+        pages += 1;
+        // The freshest page owns the summary; rows are keyed by their stable case
+        // id so a checkpoint landing between pages cannot duplicate a case.
+        snapshot = page;
+        for (const record of page.cases)
+            collected.set(record.id, record);
+        if (pages === 1)
+            wavesTruncated = page.nextWaveCursor !== null;
+        if (page.nextCaseCursor === null)
+            break;
+        if (page.cases.length === 0) {
+            throw new CaseBatchResponseError('Case batch pagination returned an empty page with a cursor.');
+        }
+        if (pages >= MAX_CASE_PAGES) {
+            // The only way this read is short: the loop gave up while the server was
+            // still handing back a cursor.
+            truncated = true;
+            break;
+        }
+        cursor = page.nextCaseCursor;
+    }
+    if (!snapshot)
+        throw new CaseBatchResponseError('Case batch read returned no pages.');
+    const cases = [...collected.values()].sort((left, right) => left.position - right.position);
+    return { snapshot, cases, pages, truncated, wavesTruncated };
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+export function caseBatchPollBounds(interval, maxWall) {
+    return {
+        intervalMs: flagInteger(interval, DEFAULT_POLL_INTERVAL_SECONDS, '--interval', 1, MAX_POLL_INTERVAL_SECONDS) * 1_000,
+        maxWallMs: flagInteger(maxWall, DEFAULT_POLL_MAX_WALL_MINUTES, '--max-wall', 1, MAX_POLL_MAX_WALL_MINUTES) * 60_000,
+    };
+}
+function unknownReasonCounts(cases) {
+    const counts = new Map();
+    for (const record of cases) {
+        const reason = record.outcome?.unknownReason;
+        if (!reason)
+            continue;
+        counts.set(reason, (counts.get(reason) ?? 0) + 1);
+    }
+    return [...counts.entries()].sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+}
+function caseRow(record) {
+    const outcome = record.outcome;
+    const columns = [
+        String(record.position).padStart(5),
+        record.id.padEnd(32),
+        record.status.padEnd(10),
+        (outcome ? outcome.status : '—').padEnd(7),
+        (outcome?.unknownReason ?? '—').padEnd(22),
+        outcome ? `${outcome.wallMs} ms`.padStart(10) : ''.padStart(10),
+        outcome ? (outcome.cleanupProven ? 'cleanup:proven' : 'cleanup:UNPROVEN') : 'cleanup:pending',
+    ];
+    return `  ${columns.join('  ')}`;
+}
+function caseJson(record) {
+    const outcome = record.outcome;
+    return {
+        id: record.id,
+        position: record.position,
+        label: record.label,
+        condition_id: record.conditionId,
+        status: record.status,
+        launched_at_ms: record.launchedAtMs,
+        finished_at_ms: record.finishedAtMs,
+        outcome_status: outcome ? outcome.status : null,
+        unknown_reason: outcome ? outcome.unknownReason : null,
+        wall_ms: outcome ? outcome.wallMs : null,
+        cleanup_proven: outcome ? outcome.cleanupProven : null,
+        comparison_path: outcome ? outcome.comparisonPath : null,
+        case_bundle_path: outcome ? outcome.caseBundlePath : null,
+        differing_outcomes: outcome ? outcome.differingOutcomes : [],
+        detail: outcome ? outcome.detail : null,
+        execution_path: outcome?.executionPath ?? null,
+        // v4: null when the outcome carries none (before v4, or a settled comparison's `failure`).
+        node_ids: outcome?.nodeIds ? { base1: outcome.nodeIds.base1, head: outcome.nodeIds.head } : null,
+        failure: outcome?.failure ? { source: outcome.failure.source, arm: outcome.failure.arm,
+            error_class: outcome.failure.errorClass, error_code: outcome.failure.errorCode,
+            node_id: outcome.failure.nodeId } : null,
+        phases: outcome ? outcome.phases : null,
+        vm_ids: record.vmIds,
+        lease_ids: record.leaseIds,
+    };
+}
+/** A batch that ends `incomplete` is a run with per-case results, not one
+ * failure: every row is printed either way and the summary says what is
+ * missing. Exit 2 marks the run as not passing; it never suppresses rows. */
+export function caseBatchExitCode(snapshot, cases, timedOut) {
+    if (timedOut)
+        return 2;
+    if (!isTerminalCaseBatchStatus(snapshot.status))
+        return 0;
+    if (snapshot.status !== 'completed')
+        return 2;
+    if (snapshot.totals.cleanupUnproven > 0)
+        return 2;
+    if (cases.some(record => record.outcome?.cleanupProven === false))
+        return 2;
+    if (!snapshot.cleanupComplete)
+        return 2;
+    return 0;
+}
+function printCaseBatch(result, repository, timedOut) {
+    const { snapshot, cases } = result;
+    console.log(`${chalk.cyan('•')} Case batch ${chalk.bold(snapshot.runId)}: ${snapshot.status}`
+        + ` ${chalk.dim(`(generation ${snapshot.generation}, observed ${snapshot.observedAt})`)}`);
+    console.log(`  ${chalk.dim('Repository:')} ${repository}`);
+    console.log(`  ${chalk.dim('Worlds:')} base ${snapshot.worlds.base ?? 'pending'} · head ${snapshot.worlds.head ?? 'pending'}`);
+    if (snapshot.admission) {
+        const admission = snapshot.admission;
+        console.log(`  ${chalk.dim('Admission:')} requested ${admission.requestedCases}, admitted ${admission.admittedCases}`
+            + ` · pool ${admission.pool} with ${admission.freeVmSlots} free VM slots (${admission.reservedVmSlots} reserved)`
+            + ` · ${admission.workerProcesses} workers × ${admission.casesPerProcess}`);
+    }
+    else {
+        console.log(`  ${chalk.dim('Admission:')} not recorded yet`);
+    }
+    const totals = snapshot.totals;
+    console.log(`  ${chalk.dim('Totals:')} ${totals.settled}/${totals.cases} settled (${totals.launched} launched)`
+        + ` · AGREE ${totals.agree} · DIFFER ${totals.differ} · UNKNOWN ${totals.unknown}`);
+    console.log(`  ${chalk.dim('Cleanup:')} proven ${totals.cleanupProven}, unproven ${totals.cleanupUnproven},`
+        + ` leases released ${totals.leasesReleased}, batch cleanup ${snapshot.cleanupComplete ? 'complete' : 'incomplete'}`);
+    if (snapshot.error)
+        console.log(`  ${chalk.dim('Error:')} ${snapshot.error}`);
+    console.log(`  ${chalk.dim('Cases:')} ${cases.length} row(s) of ${totals.launched} launched`
+        + ` (${totals.cases} in the batch) over ${result.pages} page(s)`);
+    console.log(`  ${chalk.dim('   pos  id                                status      outcome  unknownReason                 wallMs  cleanup')}`);
+    for (const record of cases)
+        console.log(caseRow(record));
+    if (result.truncated) {
+        console.log(chalk.yellow(`  Pagination stopped after ${cases.length} of ${totals.launched} launched cases; re-run to read the rest.`));
+    }
+    if (result.wavesTruncated) {
+        console.log(chalk.dim('  Wave records are paginated; only the first page is shown.'));
+    }
+    const reasons = unknownReasonCounts(cases);
+    if (reasons.length) {
+        console.log(`  ${chalk.dim('Unknown reasons:')} ${reasons.map(([reason, count]) => `${reason} ${count}`).join(', ')}`);
+    }
+    if (snapshot.status === 'incomplete') {
+        console.log(chalk.yellow(`  Batch ended incomplete: ${totals.settled} of ${totals.cases} cases settled,`
+            + ` ${totals.unknown} UNKNOWN, ${totals.cleanupUnproven} with cleanup unproven.`
+            + ' Every case above carries its own outcome.'));
+    }
+    if (snapshot.status === 'cancelled') {
+        console.log(chalk.yellow('  Batch was cancelled; cases that had already settled keep their outcomes.'));
+    }
+    if (timedOut) {
+        console.log(chalk.yellow('  Polling reached its --max-wall bound; the batch is still running.'));
+        console.log(`  ${chalk.dim('Resume:')} haystack case-batch status ${snapshot.runId} --repository ${repository} --watch`);
+    }
+}
+export async function caseBatchStatusCommand(runId, options) {
+    requireRunId(runId);
+    if (typeof options.repository !== 'string' || options.repository.length === 0) {
+        throw new CaseBatchRequestValidationError('--repository is required; every case-batch read is scoped to an exact repository.');
+    }
+    const bounds = caseBatchPollBounds(options.interval, options.maxWall);
+    const { repository, auth } = await authFor(options.repository, options.account);
+    const startedAt = Date.now();
+    let result = await readCaseBatch(runId, repository.fullName, auth.token);
+    let timedOut = false;
+    if (options.watch) {
+        while (!isTerminalCaseBatchStatus(result.snapshot.status)) {
+            const elapsed = Date.now() - startedAt;
+            if (elapsed >= bounds.maxWallMs) {
+                timedOut = true;
+                break;
+            }
+            if (!options.json) {
+                console.error(chalk.dim(`Case batch ${runId}: ${result.snapshot.status}`
+                    + ` · ${result.snapshot.totals.settled}/${result.snapshot.totals.cases} settled…`));
+            }
+            await delay(Math.min(bounds.intervalMs, bounds.maxWallMs - elapsed));
+            result = await readCaseBatch(runId, repository.fullName, auth.token);
+        }
+    }
+    const exitCode = caseBatchExitCode(result.snapshot, result.cases, timedOut);
+    if (options.json) {
+        const snapshot = result.snapshot;
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'status',
+            run_id: snapshot.runId,
+            repository: repository.fullName,
+            status: snapshot.status,
+            terminal: isTerminalCaseBatchStatus(snapshot.status),
+            timed_out: timedOut,
+            generation: snapshot.generation,
+            observed_at: snapshot.observedAt,
+            cleanup_complete: snapshot.cleanupComplete,
+            vm_ids: snapshot.vmIds,
+            worlds: { base: snapshot.worlds.base, head: snapshot.worlds.head },
+            clocks: {
+                preparation_started_at: snapshot.clocks.preparationStartedAt,
+                search_started_at: snapshot.clocks.searchStartedAt,
+                launches_closed_at: snapshot.clocks.launchesClosedAt,
+                finished_at: snapshot.clocks.finishedAt,
+                search_budget_ms: snapshot.clocks.searchBudgetMs,
+                search_wall_ms: snapshot.clocks.searchWallMs,
+                drain_wall_ms: snapshot.clocks.drainWallMs,
+            },
+            totals: {
+                cases: snapshot.totals.cases,
+                launched: snapshot.totals.launched,
+                settled: snapshot.totals.settled,
+                agree: snapshot.totals.agree,
+                differ: snapshot.totals.differ,
+                unknown: snapshot.totals.unknown,
+                cleanup_proven: snapshot.totals.cleanupProven,
+                cleanup_unproven: snapshot.totals.cleanupUnproven,
+                leases_released: snapshot.totals.leasesReleased,
+            },
+            ...(snapshot.admission ? {
+                admission: {
+                    requested_cases: snapshot.admission.requestedCases,
+                    admitted_cases: snapshot.admission.admittedCases,
+                    pool: snapshot.admission.pool,
+                    free_vm_slots: snapshot.admission.freeVmSlots,
+                    reserved_vm_slots: snapshot.admission.reservedVmSlots,
+                    worker_processes: snapshot.admission.workerProcesses,
+                    cases_per_process: snapshot.admission.casesPerProcess,
+                },
+            } : {}),
+            ...(snapshot.error ? { error: snapshot.error } : {}),
+            unknown_reasons: Object.fromEntries(unknownReasonCounts(result.cases)),
+            cases_returned: result.cases.length,
+            cases_truncated: result.truncated,
+            pages: result.pages,
+            waves: snapshot.waves.map(wave => ({ wave: wave.wave, at_ms: wave.atMs, launched: wave.launched })),
+            waves_truncated: result.wavesTruncated,
+            cases: result.cases.map(caseJson),
+            exit_code: exitCode,
+        }), null, 2)}\n`);
+    }
+    else {
+        printCaseBatch(result, repository.fullName, timedOut);
+    }
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
+}
+/* ------------------------------------------------------------------ cancel */
+export async function caseBatchCancelCommand(runId, options) {
+    requireRunId(runId);
+    if (typeof options.repository !== 'string' || options.repository.length === 0) {
+        throw new CaseBatchRequestValidationError('--repository is required; cancellation is scoped to an exact repository.');
+    }
+    const { repository, auth } = await authFor(options.repository, options.account);
+    const { body } = await gatewayJson(`${GATEWAY}/${encodeURIComponent(runId)}?${repositoryQuery(repository.fullName)}`, auth.token, { method: 'DELETE' });
+    if (!isJsonObject(body) || body.runId !== runId || body.cancelRequested !== true) {
+        throw new CaseBatchResponseError('Case batch cancellation was not acknowledged for this run.');
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'cancel',
+            run_id: runId,
+            repository: repository.fullName,
+            cancel_requested: true,
+            next_command: `haystack case-batch status ${runId} --repository ${repository.fullName} --watch`,
+        }), null, 2)}\n`);
+        return;
+    }
+    console.log(`${chalk.cyan('•')} Cancellation requested for case batch ${chalk.bold(runId)}.`);
+    console.log('  A claimed batch stays draining until its owner proves physical cleanup and posts a terminal checkpoint.');
+    console.log(`  ${chalk.dim('Watch:')} haystack case-batch status ${runId} --repository ${repository.fullName} --watch`);
+}
+/* ---------------------------------------------------------------- finalize */
+/** Mirrors CASE_BATCH_FINALIZE_STATUSES and CASE_BATCH_FINALIZE_REASON_MAX in
+ * infra/lambda/haystack-design-verifier-shared/case_batch_contracts.ts. */
+const FINALIZE_STATUSES = ['cancelled', 'incomplete'];
+const FINALIZE_REASON_MAX = 1_000;
+/** A refused finalize: the HTTP answer and the gateway's typed reason (`finalize-not-stranded`,
+ * `finalize-live-claim`, `finalize-already-terminal`, `finalize-conflict`). */
+export class CaseBatchFinalizeRefusedError extends HaystackApiError {
+    reason;
+    constructor(refusal, reason) {
+        super(refusal.status, reason ? `Case batch finalize refused (${reason}): ${refusal.message}` : refusal.message, refusal.code);
+        this.name = 'CaseBatchFinalizeRefusedError';
+        this.reason = reason;
+    }
+}
+/** Operator finalize of a stranded batch: terminal with the given status, the reason recorded as its
+ * error, and its world-pair lock freed. The gateway accepts it only when the batch was cancelled or has
+ * gone 15 minutes without an update, and no claim is live. Cleanup is reported exactly as the batch
+ * last recorded it; finalize never asserts it. */
+export async function caseBatchFinalizeCommand(runId, options) {
+    requireRunId(runId);
+    if (typeof options.repository !== 'string' || options.repository.length === 0) {
+        throw new CaseBatchRequestValidationError('--repository is required; finalize is scoped to an exact repository.');
+    }
+    const status = options.status;
+    if (typeof status !== 'string' || !FINALIZE_STATUSES.includes(status)) {
+        throw new CaseBatchRequestValidationError(`--status must be one of: ${FINALIZE_STATUSES.join(', ')}.`);
+    }
+    const reason = options.reason;
+    if (typeof reason !== 'string' || reason.trim().length === 0 || reason.length > FINALIZE_REASON_MAX || reason.includes('\0')) {
+        throw new CaseBatchRequestValidationError(`--reason is required: 1 to ${FINALIZE_REASON_MAX} characters saying why the batch is stranded.`);
+    }
+    const { repository, auth } = await authFor(options.repository, options.account);
+    const path = `${GATEWAY}/${encodeURIComponent(runId)}/finalize?${repositoryQuery(repository.fullName)}`;
+    const response = await gatewayFetch(path, auth.token, { method: 'POST', body: JSON.stringify({ status, reason }) });
+    if (!response.ok) {
+        const copy = response.clone();
+        const refusal = await classifyHttpError(response, `Haystack API ${path}`);
+        let refusalReason = null;
+        try {
+            const body = await copy.json();
+            if (isJsonObject(body) && typeof body.reason === 'string')
+                refusalReason = body.reason;
+        }
+        catch {
+            // Not JSON: the refusal above already carries the status and the readable part of the body.
+        }
+        throw new CaseBatchFinalizeRefusedError(refusal, refusalReason);
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (error) {
+        throw new CaseBatchResponseError(`Case batch service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isJsonObject(body) || body.runId !== runId || body.terminal !== true || body.status !== status
+        || typeof body.cleanupComplete !== 'boolean' || typeof body.generation !== 'number'
+        || typeof body.previousStatus !== 'string' || typeof body.lastUpdatedAt !== 'string'
+        || (body.eligibility !== 'cancel-requested' && body.eligibility !== 'stale') || typeof body.finalizedAt !== 'string') {
+        throw new CaseBatchResponseError('Case batch finalize was not acknowledged for this run.');
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'finalize',
+            run_id: runId,
+            repository: repository.fullName,
+            status,
+            terminal: true,
+            cleanup_complete: body.cleanupComplete,
+            generation: body.generation,
+            previous_status: body.previousStatus,
+            last_updated_at: body.lastUpdatedAt,
+            eligibility: body.eligibility,
+            reason,
+            finalized_at: body.finalizedAt,
+        }), null, 2)}\n`);
+        return;
+    }
+    console.log(`${chalk.cyan('•')} Case batch ${chalk.bold(runId)} finalized as ${status} (was ${body.previousStatus}; ${body.eligibility}).`);
+    console.log(body.cleanupComplete
+        ? '  Its last checkpoint recorded cleanup complete.'
+        : chalk.yellow('  Its last checkpoint did NOT record cleanup complete; its VM and lease ownership rows remain for dispatcher recovery.'));
+}
+/** Parallel artifact reads. Bounded so a large bundle does not open hundreds of sockets. */
+const BUNDLE_FETCH_CONCURRENCY = 8;
+/** The bundle route's `reason` (HTTP 409) for a PNG a page lists that the coordinator has not
+ * uploaded yet. PNGs upload after the batch is terminal, off its world-pair lock. Mirrors
+ * CASE_BATCH_ARTIFACT_PENDING_REASON in infra/lambda/haystack-design-verifier-shared/case_batch_contracts.ts. */
+const ARTIFACT_PENDING_REASON = 'artifact-pending';
+/** Exit status when every other artifact verified and only PNGs are still uploading: EX_TEMPFAIL
+ * from sysexits.h, "try again later". Rerun the command, or pass the pending paths to `--only`. */
+export const CASE_BATCH_BUNDLE_PENDING_EXIT = 75;
+/** The bundle route's `reason` (HTTP 410) for a listed PNG whose upload the coordinator gave up on and
+ * recorded. Terminal: nothing will upload it. Mirrors CASE_BATCH_ARTIFACT_FAILED_REASON in
+ * infra/lambda/haystack-design-verifier-shared/case_batch_contracts.ts. */
+const ARTIFACT_FAILED_REASON = 'artifact-failed';
+/** Exit status when nothing is pending but at least one listed PNG failed to upload: the answer is final and
+ * the bundle is incomplete, so a caller must not retry and must not treat it as complete. */
+export const CASE_BATCH_BUNDLE_FAILED_EXIT = 1;
+/** A listed PNG the service reports as failed for good (its recorded upload error). Terminal, never retried. */
+export class CaseBatchArtifactFailedError extends Error {
+    path;
+    uploadError;
+    constructor(path, uploadError) {
+        super(`Bundle artifact ${path} failed to upload (${uploadError.errorClass}${uploadError.status === null ? '' : ` HTTP ${uploadError.status}`}: ${uploadError.message}).`);
+        this.path = path;
+        this.uploadError = uploadError;
+        this.name = 'CaseBatchArtifactFailedError';
+    }
+}
+/** The recorded upload error when an error body is the failed answer, else null (the caller reports the
+ * response like any other refusal). */
+function artifactFailedBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!isJsonObject(body) || body.reason !== ARTIFACT_FAILED_REASON || !isJsonObject(body.uploadError))
+        return null;
+    const { errorClass, status, message } = body.uploadError;
+    if (typeof errorClass !== 'string' || typeof message !== 'string' || (status !== null && typeof status !== 'number')) {
+        throw new CaseBatchResponseError('Bundle route answered artifact-failed without a valid uploadError.');
+    }
+    return { errorClass, status, message };
+}
+/** A listed PNG the service reports as still uploading. Retryable, never a missing artifact. */
+export class CaseBatchArtifactPendingError extends Error {
+    path;
+    constructor(path) {
+        super(`Bundle artifact ${path} is still uploading; retry it.`);
+        this.path = path;
+        this.name = 'CaseBatchArtifactPendingError';
+    }
+}
+/** True when an error body carries the pending `reason`. A body that is not JSON is not that answer,
+ * and the caller reports the response like any other refusal. */
+function isArtifactPendingBody(text) {
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    return isJsonObject(body) && body.reason === ARTIFACT_PENDING_REASON;
+}
+function safeBundlePath(path) {
+    if (typeof path !== 'string' || path.length === 0 || path.length > 512) {
+        throw new CaseBatchResponseError('Bundle manifest names an invalid artifact path.');
+    }
+    if (isAbsolute(path) || path.includes('\\') || path.includes('//')
+        // eslint-disable-next-line no-control-regex -- rejecting/stripping control characters is the point
+        || /[\u0000-\u001f\u007f]/.test(path)
+        || path.split('/').some(segment => segment === '' || segment === '.' || segment === '..')) {
+        throw new CaseBatchResponseError(`Bundle manifest names an unsafe artifact path: ${JSON.stringify(path)}`);
+    }
+    return path;
+}
+/** Collect every artifact reference in a manifest document. A reference is an
+ * object carrying `path`, a 64-hex `sha256` and an integer `bytes` — the shape
+ * the publication side already writes for manifest pages
+ * (`CombinationSearchPublicManifestPageRef`) and the only shape the bundle
+ * route will serve. Nothing else in the document is followed. */
+export function collectArtifactRefs(document, into) {
+    const visit = (value, depth) => {
+        if (depth > 64)
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, depth + 1);
+            return;
+        }
+        if (!isJsonObject(value))
+            return;
+        if (typeof value.path === 'string' && typeof value.sha256 === 'string'
+            && /^[0-9a-f]{64}$/.test(value.sha256)
+            && typeof value.bytes === 'number' && Number.isSafeInteger(value.bytes) && value.bytes >= 0) {
+            const path = safeBundlePath(value.path);
+            if (value.bytes > MAX_ARTIFACT_BYTES) {
+                throw new CaseBatchResponseError(`Bundle artifact ${path} declares ${value.bytes} bytes, above the ${MAX_ARTIFACT_BYTES}-byte per-file bound.`);
+            }
+            const existing = into.get(path);
+            if (existing && (existing.sha256 !== value.sha256 || existing.bytes !== value.bytes)) {
+                throw new CaseBatchResponseError(`Bundle manifest lists ${path} twice with different digests.`);
+            }
+            into.set(path, { path, sha256: value.sha256, bytes: value.bytes });
+        }
+        else if (typeof value.path === 'string' && typeof value.pngSha256 === 'string'
+            && /^[0-9a-f]{64}$/.test(value.pngSha256) && Object.keys(value).length === 2) {
+            // A page's image reference: the PNG's own sha256; its size is checked against the bound only.
+            const path = safeBundlePath(value.path);
+            const existing = into.get(path);
+            if (existing && existing.sha256 !== value.pngSha256) {
+                throw new CaseBatchResponseError(`Bundle manifest lists ${path} twice with different digests.`);
+            }
+            into.set(path, { path, sha256: value.pngSha256, bytes: existing?.bytes ?? null });
+        }
+        for (const item of Object.values(value))
+            visit(item, depth + 1);
+    };
+    visit(document, 0);
+}
+const SEALED_ETAG = /^(?:W\/)?"([0-9a-f]{64})"$/;
+/** Reads the sealed SHA-256 out of a bundle response's ETag. The service sets
+ * a strong entity tag `"<sha256>"`; an edge that re-encodes the body (Cloudflare
+ * serving brotli to a client that accepts it) rewrites it to the weak form
+ * `W/"<sha256>"`. Either way the quoted value is the digest of the decoded
+ * bytes, which is what the caller hashes. Absent header returns null; any
+ * other shape is refused and named. */
+export function sealedDigestFromEtag(relative, header) {
+    if (header === null)
+        return null;
+    const match = SEALED_ETAG.exec(header.trim());
+    if (!match) {
+        throw new CaseBatchResponseError(`Bundle ${relative} was served with ETag ${JSON.stringify(header)}, which is not a sealed SHA-256 entity tag (expected "<64 hex>" or W/"<64 hex>").`);
+    }
+    return match[1];
+}
+/** `requireSealedDigest` is set for the manifest, the one artifact with no
+ * parent digest to check it against: without the service's own sealed digest
+ * there is nothing to verify it with, so the fetch fails rather than
+ * proceeding while the output claims every digest was verified. */
+async function fetchBundleArtifact(runId, repository, token, relative, requireSealedDigest = false) {
+    const encoded = relative.split('/').map(encodeURIComponent).join('/');
+    const suffix = relative === 'manifest.json' ? '' : `/${encoded}`;
+    const response = await gatewayFetch(`${GATEWAY}/${encodeURIComponent(runId)}/bundle${suffix}?${repositoryQuery(repository)}`, token, { method: 'GET', accept: '*/*' });
+    if (response.status === 409) {
+        const text = await response.text();
+        if (isArtifactPendingBody(text))
+            throw new CaseBatchArtifactPendingError(relative);
+        throw await classifyHttpError(new Response(text, { status: response.status, headers: response.headers }), `Haystack API ${GATEWAY}/${runId}/bundle${suffix}`);
+    }
+    if (response.status === 410) {
+        const text = await response.text();
+        const failure = artifactFailedBody(text);
+        if (failure !== null)
+            throw new CaseBatchArtifactFailedError(relative, failure);
+        throw await classifyHttpError(new Response(text, { status: response.status, headers: response.headers }), `Haystack API ${GATEWAY}/${runId}/bundle${suffix}`);
+    }
+    if (!response.ok) {
+        throw await classifyHttpError(response, `Haystack API ${GATEWAY}/${runId}/bundle${suffix}`);
+    }
+    const etag = sealedDigestFromEtag(relative, response.headers.get('etag'));
+    if (requireSealedDigest && etag === null) {
+        throw new CaseBatchResponseError(`Bundle ${relative} was served without an ETag, so the service's sealed SHA-256 for it is unavailable and it cannot be verified.`);
+    }
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_ARTIFACT_BYTES) {
+        throw new CaseBatchResponseError(`Bundle artifact ${relative} exceeded the ${MAX_ARTIFACT_BYTES}-byte per-file bound.`);
+    }
+    return { bytes, sha256: createHash('sha256').update(bytes).digest('hex'), etag };
+}
+function writeArtifact(outDir, relative, bytes) {
+    const destination = resolve(outDir, relative);
+    const root = resolve(outDir);
+    if (destination !== root && !destination.startsWith(root + sep)) {
+        throw new CaseBatchResponseError(`Bundle artifact ${relative} resolves outside --out.`);
+    }
+    mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, bytes);
+    return destination;
+}
+/** `case-batch bundle` as a library call: the same reads and digest checks, returned instead of printed,
+ * and no process exit status. A caller in its own process (the product-fuzz page) waits on `pending` and
+ * renders `failed` without the PNG. */
+export async function downloadCaseBatchBundle(runId, options) {
+    requireRunId(runId);
+    if (typeof options.repository !== 'string' || options.repository.length === 0) {
+        throw new CaseBatchRequestValidationError('--repository is required; every bundle read is scoped to an exact repository.');
+    }
+    if (typeof options.out !== 'string' || options.out.length === 0) {
+        throw new CaseBatchRequestValidationError('--out is required and must name a directory to write the bundle into.');
+    }
+    const outDir = resolve(options.out);
+    const { repository, auth } = await authFor(options.repository, options.account);
+    // Nothing is written before the manifest is verified, so a bundle that fails
+    // its first integrity check leaves no directory and no bytes behind.
+    const manifest = await fetchBundleArtifact(runId, repository.fullName, auth.token, 'manifest.json', true);
+    // The bundle route seals each object with its own digest and serves it as the
+    // ETag; a mismatch means the served bytes are not the sealed bytes.
+    if (manifest.etag !== manifest.sha256) {
+        throw new CaseBatchResponseError(`Bundle manifest bytes hash to ${manifest.sha256}; the service sealed them under ${manifest.etag}.`);
+    }
+    let manifestDocument;
+    try {
+        manifestDocument = JSON.parse(manifest.bytes.toString('utf8'));
+    }
+    catch {
+        throw new CaseBatchResponseError('Bundle manifest is not JSON.');
+    }
+    writeArtifact(outDir, 'manifest.json', manifest.bytes);
+    const pending = new Map();
+    collectArtifactRefs(manifestDocument, pending);
+    const only = (options.only ?? []).map(entry => {
+        if (typeof entry !== 'string' || entry.length === 0)
+            throw new CaseBatchRequestValidationError('--only names an empty path.');
+        return entry;
+    });
+    // The manifest and its pages are always read: they are what every other artifact is verified against.
+    const wanted = (path) => path.startsWith('manifest-pages/') || only.length === 0
+        || only.some(entry => entry === path || (entry.endsWith('/') && path.startsWith(entry)));
+    const verified = [];
+    /** Listed PNGs the service reported as still uploading; nothing was written for them. */
+    const uploading = [];
+    /** Listed PNGs the service reported as failed for good. */
+    const failed = [];
+    const done = new Set(['manifest.json']);
+    let totalBytes = manifest.bytes.byteLength;
+    const fetchOne = async (next) => {
+        if (!options.json)
+            console.error(chalk.dim(`Fetching ${next.path}…`));
+        let artifact;
+        try {
+            artifact = await fetchBundleArtifact(runId, repository.fullName, auth.token, next.path);
+        }
+        catch (error) {
+            if (error instanceof CaseBatchArtifactFailedError) {
+                failed.push({ path: next.path, uploadError: error.uploadError });
+                return;
+            }
+            if (!(error instanceof CaseBatchArtifactPendingError))
+                throw error;
+            uploading.push(next.path);
+            return;
+        }
+        if (next.bytes !== null && artifact.bytes.byteLength !== next.bytes) {
+            throw new CaseBatchResponseError(`Bundle artifact ${next.path} is ${artifact.bytes.byteLength} bytes; the manifest declares ${next.bytes}.`);
+        }
+        if (artifact.sha256 !== next.sha256) {
+            throw new CaseBatchResponseError(`Bundle artifact ${next.path} hashes to ${artifact.sha256}; the manifest declares ${next.sha256}.`);
+        }
+        if (artifact.etag !== null && artifact.etag !== artifact.sha256) {
+            throw new CaseBatchResponseError(`Bundle artifact ${next.path} hashes to ${artifact.sha256}; the service sealed it under ${artifact.etag}.`);
+        }
+        totalBytes += artifact.bytes.byteLength;
+        if (totalBytes > MAX_BUNDLE_BYTES) {
+            throw new CaseBatchResponseError(`Bundle exceeded the ${MAX_BUNDLE_BYTES}-byte download bound.`);
+        }
+        writeArtifact(outDir, next.path, artifact.bytes);
+        // A manifest page lists its cases' PNGs and records; follow pages only. Only verified bytes are
+        // ever parsed, and a case's records are data, never a list of further artifacts.
+        const json = next.path.endsWith('.json');
+        if (next.path.startsWith('manifest-pages/')) {
+            try {
+                collectArtifactRefs(JSON.parse(artifact.bytes.toString('utf8')), pending);
+            }
+            catch (error) {
+                if (error instanceof CaseBatchResponseError)
+                    throw error;
+                throw new CaseBatchResponseError(`Bundle page ${next.path} is not JSON.`);
+            }
+        }
+        verified.push({ path: next.path, sha256: next.sha256, bytes: artifact.bytes.byteLength, json });
+    };
+    for (;;) {
+        const wave = [...pending.values()].filter(ref => !done.has(ref.path) && wanted(ref.path));
+        if (wave.length === 0)
+            break;
+        for (const ref of wave)
+            done.add(ref.path);
+        if (verified.length + wave.length > MAX_BUNDLE_ARTIFACTS) {
+            throw new CaseBatchResponseError(`Bundle lists more than ${MAX_BUNDLE_ARTIFACTS} artifacts.`);
+        }
+        let cursor = 0;
+        await Promise.all(Array.from({ length: Math.min(BUNDLE_FETCH_CONCURRENCY, wave.length) }, async () => {
+            for (let index = cursor++; index < wave.length; index = cursor++)
+                await fetchOne(wave[index]);
+        }));
+    }
+    const missing = only.filter(entry => !entry.endsWith('/') && !done.has(entry));
+    if (missing.length > 0) {
+        throw new CaseBatchResponseError(`Bundle does not list ${missing.join(', ')}.`);
+    }
+    uploading.sort();
+    failed.sort((left, right) => left.path < right.path ? -1 : left.path > right.path ? 1 : 0);
+    return { repository: repository.fullName, outDir, manifest: { sha256: manifest.sha256, bytes: manifest.bytes.byteLength },
+        verified, totalBytes, pending: uploading, failed };
+}
+export async function caseBatchBundleCommand(runId, options) {
+    const { repository, outDir, manifest, verified, totalBytes, pending: uploading, failed } = await downloadCaseBatchBundle(runId, options);
+    // Pending first: those can still arrive, so the caller retries; failed ones are final either way.
+    const exitCode = uploading.length > 0 ? CASE_BATCH_BUNDLE_PENDING_EXIT : failed.length > 0 ? CASE_BATCH_BUNDLE_FAILED_EXIT : 0;
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'bundle',
+            run_id: runId,
+            repository,
+            out_dir: outDir,
+            manifest: { path: 'manifest.json', sha256: manifest.sha256, bytes: manifest.bytes },
+            artifacts: verified.map(ref => ({ path: ref.path, sha256: ref.sha256, bytes: ref.bytes, verified: true })),
+            artifact_count: verified.length,
+            total_bytes: totalBytes,
+            pending: uploading,
+            failed: failed.map(entry => ({ path: entry.path, error_class: entry.uploadError.errorClass,
+                status: entry.uploadError.status, message: entry.uploadError.message })),
+        }), null, 2)}\n`);
+        return;
+    }
+    console.log(`${chalk.cyan('•')} Bundle for case batch ${chalk.bold(runId)} written to ${outDir}`);
+    console.log(`  ${chalk.dim('manifest.json')} ${manifest.sha256} (${manifest.bytes} bytes)`);
+    for (const ref of verified) {
+        console.log(`  ${chalk.dim(ref.path)} ${ref.sha256} (${ref.bytes} bytes)`);
+    }
+    console.log(`  ${verified.length + 1} file(s), ${totalBytes} bytes, every digest verified against the manifest.`);
+    if (uploading.length > 0) {
+        console.log(`  ${chalk.yellow(`${uploading.length} PNG(s) still uploading`)} (the batch is terminal; its PNGs publish after it):`);
+        for (const path of uploading)
+            console.log(`  ${chalk.dim(path)}`);
+        console.log(`  Retry: haystack case-batch bundle ${runId} --repository ${repository} --out ${outDir}`
+            + `${uploading.map(path => ` --only ${path}`).join('')}`);
+    }
+    if (failed.length > 0) {
+        console.log(`  ${chalk.red(`${failed.length} PNG(s) failed to upload`)} (final; the coordinator recorded why):`);
+        for (const entry of failed) {
+            console.log(`  ${chalk.dim(entry.path)} ${entry.uploadError.errorClass}`
+                + `${entry.uploadError.status === null ? '' : ` HTTP ${entry.uploadError.status}`}: ${entry.uploadError.message}`);
+        }
+    }
+}
+export const caseBatchDefaults = {
+    perCaseWallMs: DEFAULT_PER_CASE_WALL_MS,
+    totalBudgetMs: DEFAULT_TOTAL_BUDGET_MS,
+    pollIntervalSeconds: DEFAULT_POLL_INTERVAL_SECONDS,
+    pollMaxWallMinutes: DEFAULT_POLL_MAX_WALL_MINUTES,
+    casePageLimit: CASE_PAGE_LIMIT,
+};