@haystackeditor/cli 0.15.31 → 0.16.0

package/dist/commands/case-batch.js

@@ -0,0 +1,713 @@
+/**
+ * `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, 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');
+    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),
+    });
+    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,
+        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,
+        combinations: combinations,
+        cases,
+        limits,
+        source,
+    });
+    return { repository, request, caseCount: cases.length, limits };
+}
+export async function caseBatchSubmitCommand(options) {
+    // Validate every local input before touching credentials or the network.
+    const prepared = prepareCaseBatchSubmission(options);
+    const { auth } = await authFor(prepared.repository.fullName, options.account);
+    if (!options.json) {
+        console.error(chalk.dim(`Submitting ${prepared.caseCount} cases to the hosted coordinator…`));
+    }
+    const { status, body } = await gatewayJson(GATEWAY, auth.token, {
+        method: 'POST',
+        body: JSON.stringify(prepared.request),
+    });
+    if (!isJsonObject(body) || typeof body.runId !== 'string' || !RUN_ID.test(body.runId)) {
+        throw new CaseBatchResponseError('Case batch admission did not return a run id.');
+    }
+    const runId = body.runId;
+    // The search route answers 202 for a newly admitted run and 200 for an
+    // identical replay of an admitted idempotency key.
+    const admitted = status === 200 ? 'existing' : 'created';
+    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.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,
+        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`);
+}
+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 });
+        }
+        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.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;
+}
+export async function caseBatchBundleCommand(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 verified = [];
+    const done = new Set(['manifest.json']);
+    let totalBytes = manifest.bytes.byteLength;
+    for (;;) {
+        const next = [...pending.values()].find(ref => !done.has(ref.path));
+        if (!next)
+            break;
+        done.add(next.path);
+        if (verified.length >= MAX_BUNDLE_ARTIFACTS) {
+            throw new CaseBatchResponseError(`Bundle lists more than ${MAX_BUNDLE_ARTIFACTS} artifacts.`);
+        }
+        if (!options.json)
+            console.error(chalk.dim(`Fetching ${next.path}…`));
+        const artifact = await fetchBundleArtifact(runId, repository.fullName, auth.token, next.path);
+        if (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 own PNGs; follow one level at a time until the
+        // closure is complete. Only verified bytes are ever parsed.
+        const json = next.path.endsWith('.json');
+        if (json) {
+            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({ ...next, json });
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('case-batch', {
+            operation: 'bundle',
+            run_id: runId,
+            repository: repository.fullName,
+            out_dir: outDir,
+            manifest: { path: 'manifest.json', sha256: manifest.sha256, bytes: manifest.bytes.byteLength },
+            artifacts: verified.map(ref => ({ path: ref.path, sha256: ref.sha256, bytes: ref.bytes, verified: true })),
+            artifact_count: verified.length,
+            total_bytes: totalBytes,
+        }), 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.byteLength} 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.`);
+}
+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,
+};