@haystackeditor/cli 0.15.31 → 0.17.0

package/dist/utils/secret-paths.js

@@ -0,0 +1,115 @@
+import { scanForSecrets } from './secrets.js';
+/**
+ * File names that conventionally hold credentials. The precompute upload
+ * withholds these regardless of content, because a scanner cannot recognise
+ * every secret format (a raw key file has no telltale prefix).
+ */
+const EXACT_NAMES = new Set([
+    '.env',
+    'credentials.json',
+    '.npmrc',
+    '.pypirc',
+    '.netrc',
+]);
+// Committed templates are how teams document which variables a service needs.
+const ENV_TEMPLATES = new Set(['.env.example', '.env.sample']);
+const SUFFIXES = ['.pem', '.key', '.p12', '.pfx', '.keystore', '.tfvars'];
+const PREFIXES = ['id_rsa', 'id_ed25519', 'secrets.'];
+/** True when a repository-relative path names a conventionally secret-bearing file. */
+export function isSecretBearingPath(path) {
+    const segments = path.split('/').filter(segment => segment.length > 0);
+    if (segments.length === 0)
+        return false;
+    for (let index = 0; index + 1 < segments.length; index += 1) {
+        if (segments[index] === '.haystack' && segments[index + 1] === 'secrets')
+            return true;
+    }
+    const name = segments[segments.length - 1].toLowerCase();
+    if (EXACT_NAMES.has(name))
+        return true;
+    if (name.startsWith('.env.'))
+        return !ENV_TEMPLATES.has(name);
+    if (SUFFIXES.some(suffix => name.endsWith(suffix)))
+        return true;
+    if (PREFIXES.some(prefix => name.startsWith(prefix)))
+        return true;
+    return name.startsWith('service-account') && name.endsWith('.json');
+}
+const GIT_ESCAPES = {
+    a: 7, b: 8, t: 9, n: 10, v: 11, f: 12, r: 13, '"': 34, '\\': 92,
+};
+/** Reverses git's C-style path quoting (named escapes and octal bytes). */
+function unquoteGitPath(quoted) {
+    const bytes = [];
+    for (let index = 0; index < quoted.length; index += 1) {
+        const character = quoted[index];
+        if (character !== '\\') {
+            bytes.push(...Buffer.from(character, 'utf8'));
+            continue;
+        }
+        const next = quoted[index + 1];
+        const octal = quoted.slice(index + 1, index + 4);
+        if (next !== undefined && next in GIT_ESCAPES) {
+            bytes.push(GIT_ESCAPES[next]);
+            index += 1;
+        }
+        else if (/^[0-7]{3}$/.test(octal)) {
+            bytes.push(Number.parseInt(octal, 8));
+            index += 3;
+        }
+        else {
+            throw new Error('Unrecognised escape in a git path.');
+        }
+    }
+    return Buffer.from(bytes).toString('utf8');
+}
+/** Path named by a `diff --git a/P b/P` header produced with --no-renames. */
+export function pathFromDiffHeader(header) {
+    const prefix = 'diff --git ';
+    if (!header.startsWith(prefix))
+        throw new Error('Not a diff header.');
+    const rest = header.slice(prefix.length);
+    // Without renames both sides name the same path, so the header is symmetric.
+    const side = rest.slice(0, (rest.length - 1) / 2);
+    const quoted = side.startsWith('"');
+    const other = quoted ? `"b/${side.slice(3)}` : `b/${side.slice(2)}`;
+    if (rest !== `${side} ${other}` || !side.startsWith(quoted ? '"a/' : 'a/')) {
+        throw new Error('Unexpected diff header.');
+    }
+    return quoted ? unquoteGitPath(side.slice(1, -1)).slice(2) : side.slice(2);
+}
+/**
+ * Scans only the lines a `git diff --no-renames` patch adds and returns, per
+ * file, the name of the first high-severity secret pattern found. The matched
+ * value never leaves this function.
+ */
+export function findSecretsInPatch(patch) {
+    const hits = new Map();
+    let currentPath;
+    let inHunk = false;
+    let added = [];
+    const flush = () => {
+        if (currentPath === undefined || added.length === 0)
+            return;
+        const finding = scanForSecrets(added.join('\n'), currentPath)
+            .find(item => item.severity === 'high');
+        if (finding && !hits.has(currentPath))
+            hits.set(currentPath, finding.pattern);
+    };
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('diff --git ')) {
+            flush();
+            currentPath = pathFromDiffHeader(line);
+            inHunk = false;
+            added = [];
+        }
+        else if (line.startsWith('@@')) {
+            inHunk = true;
+        }
+        else if (inHunk && line.startsWith('+')) {
+            added.push(line.slice(1));
+        }
+    }
+    flush();
+    return hits;
+}

package/dist/utils/secrets.js

@@ -160,7 +160,6 @@ function isSafePattern(match) {
  */
 export function scanForSecrets(content, filename) {
     const findings = [];
-    const lines = content.split('\n');
     for (const secretPattern of SECRET_PATTERNS) {
         // Reset regex state
         secretPattern.pattern.lastIndex = 0;

package/dist/utils/telemetry.js

@@ -7,11 +7,11 @@
  * All calls are non-blocking and never throw — telemetry failures must not
  * break CLI commands.
  */
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import * as os from 'os';
-import { createHash } from 'node:crypto';
+import * as os from 'node:os';
+import { randomBytes } from 'node:crypto';
 const POSTHOG_HOST = 'https://us.i.posthog.com';
 const POSTHOG_API_KEY = process.env.HAYSTACK_POSTHOG_KEY || 'phc_7wHrCoMlcwuftLe6N38hPb9wKHb4OK0wNw9ayeRySad';
 const CURRENT_FILE_DIR = dirname(fileURLToPath(import.meta.url));
@@ -55,25 +55,45 @@ function minimizeMetadata(metadata) {
     }
     return minimized;
 }
+const TELEMETRY_ID_PATTERN = /^[0-9a-f]{24}$/;
+let cachedTelemetryId;
 /**
- * Pseudonymous stable machine identifier for PostHog distinct_id.
- * The local username and hostname are never transmitted.
- * Never throws — falls back to hostname-only or 'anonymous'.
+ * Pseudonymous stable install identifier for PostHog distinct_id: 24 random
+ * hex chars generated once and kept in ~/.haystack/telemetry-id (0600). It is
+ * not derived from the username or hostname, so it cannot be reversed to
+ * them. A missing, unreadable or malformed file gets a fresh id. Never throws.
  */
 function getDistinctId() {
+    if (cachedTelemetryId)
+        return `cli:${cachedTelemetryId}`;
+    let idPath;
     try {
-        const hostname = os.hostname();
+        idPath = join(os.homedir(), '.haystack', 'telemetry-id');
+        const stored = readFileSync(idPath, 'utf8').trim();
+        if (TELEMETRY_ID_PATTERN.test(stored)) {
+            cachedTelemetryId = stored;
+            return `cli:${stored}`;
+        }
+    }
+    catch {
+        // Missing or unreadable: a new id is generated below.
+        cachedTelemetryId = undefined;
+    }
+    const fresh = randomBytes(12).toString('hex');
+    cachedTelemetryId = fresh;
+    if (idPath) {
         try {
-            const localMachine = `${os.userInfo().username}\0${hostname}`;
-            return `cli:${createHash('sha256').update(localMachine).digest('hex').slice(0, 24)}`;
+            mkdirSync(dirname(idPath), { recursive: true });
+            writeFileSync(idPath, `${fresh}\n`, { mode: 0o600 });
+            chmodSync(idPath, 0o600);
         }
         catch {
-            return `cli:${createHash('sha256').update(hostname).digest('hex').slice(0, 24)}`;
+            // Could not persist (read-only home, etc.): this process keeps the
+            // random id and the next run tries again. Telemetry must not break the CLI.
+            cachedTelemetryId = fresh;
         }
     }
-    catch {
-        return 'cli:anonymous';
-    }
+    return `cli:${fresh}`;
 }
 /**
  * Track an error event. Fire-and-forget — never throws.

package/dist/utils/update-check.js

@@ -0,0 +1,151 @@
+/**
+ * "New version available" notice.
+ *
+ * Runs after a command finishes, never before it starts. At most once per 24
+ * hours (timestamp in ~/.haystack/update-check.json, mode 0600) it asks the
+ * npm registry for the latest @haystackeditor/cli with a 1.5 second timeout,
+ * and prints one dim stderr line when that version is newer than this one.
+ *
+ * It stays off when stdout is not a TTY, when --json is passed, and when
+ * HAYSTACK_NO_UPDATE_CHECK or CI is set, so scripts and agents never see it.
+ * Failures print nothing unless DEBUG is set.
+ */
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import chalk from 'chalk';
+export const UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+export const UPDATE_CHECK_TIMEOUT_MS = 1500;
+export const LATEST_URL = 'https://registry.npmjs.org/@haystackeditor/cli/latest';
+/** Parse `X.Y.Z` or `X.Y.Z-pre`; anything else is not comparable. */
+function parseVersion(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/.exec(version.trim());
+    if (!match)
+        return null;
+    return {
+        core: [Number(match[1]), Number(match[2]), Number(match[3])],
+        prerelease: match[4] !== undefined,
+    };
+}
+/**
+ * True when `latest` is a strictly newer release than `current`. A prerelease
+ * `latest` is never offered. A release with the same core as a prerelease
+ * `current` is newer (0.16.0 is newer than 0.16.0-rc.1).
+ */
+export function isNewerVersion(latest, current) {
+    const l = parseVersion(latest);
+    const c = parseVersion(current);
+    if (!l || !c || l.prerelease)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (l.core[i] !== c.core[i])
+            return l.core[i] > c.core[i];
+    }
+    return c.prerelease;
+}
+/** True when no check has run within the interval (or the clock went backwards). */
+export function isCheckDue(state, now, intervalMs = UPDATE_CHECK_INTERVAL_MS) {
+    if (!state)
+        return true;
+    const elapsed = now - state.lastCheckedAt;
+    return elapsed < 0 || elapsed >= intervalMs;
+}
+export function isUpdateCheckEnabled({ argv, env, stdoutIsTTY }) {
+    if (!stdoutIsTTY)
+        return false;
+    if (env.HAYSTACK_NO_UPDATE_CHECK || env.CI)
+        return false;
+    return !argv.includes('--json');
+}
+export function defaultStatePath() {
+    return join(homedir(), '.haystack', 'update-check.json');
+}
+function readState(statePath, debug) {
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf8');
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            debug(`could not read ${statePath}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed.lastCheckedAt === 'number' ? { lastCheckedAt: parsed.lastCheckedAt } : null;
+    }
+    catch (err) {
+        debug(`ignoring unreadable ${statePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+function writeState(statePath, state) {
+    mkdirSync(dirname(statePath), { recursive: true, mode: 0o700 });
+    writeFileSync(statePath, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    // writeFileSync only applies `mode` when it creates the file.
+    chmodSync(statePath, 0o600);
+}
+/**
+ * Returns the newer version when one should be announced, otherwise null.
+ * The timestamp is recorded before the request so an offline machine pays the
+ * timeout at most once per interval.
+ */
+export async function checkForUpdate(deps) {
+    const { currentVersion, now, statePath, fetchLatest, debug } = deps;
+    if (!isCheckDue(readState(statePath, debug), now))
+        return null;
+    try {
+        writeState(statePath, { lastCheckedAt: now });
+    }
+    catch (err) {
+        debug(`could not write ${statePath}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), UPDATE_CHECK_TIMEOUT_MS);
+    try {
+        const latest = await fetchLatest(controller.signal);
+        return isNewerVersion(latest, currentVersion) ? latest : null;
+    }
+    catch (err) {
+        debug(`registry lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function fetchLatestFromRegistry(signal) {
+    const response = await fetch(LATEST_URL, { signal, headers: { accept: 'application/json' } });
+    if (!response.ok)
+        throw new Error(`registry returned HTTP ${response.status}`);
+    const body = (await response.json());
+    if (typeof body.version !== 'string')
+        throw new Error('registry response has no version');
+    return body.version;
+}
+/** Entry point for src/index.ts, called once the command has finished. */
+export async function notifyIfUpdateAvailable(currentVersion) {
+    const environment = {
+        argv: process.argv.slice(2),
+        env: process.env,
+        stdoutIsTTY: process.stdout.isTTY === true,
+    };
+    if (!isUpdateCheckEnabled(environment))
+        return;
+    const debug = (message) => {
+        if (process.env.DEBUG)
+            console.error(`haystack: update check: ${message}`);
+    };
+    const newer = await checkForUpdate({
+        currentVersion,
+        now: Date.now(),
+        statePath: defaultStatePath(),
+        fetchLatest: fetchLatestFromRegistry,
+        debug,
+    });
+    if (!newer)
+        return;
+    console.error(chalk.dim(`haystack ${newer} is available (you have ${currentVersion}). Update: npm i -g @haystackeditor/cli@latest`));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.15.31",
+  "version": "0.17.0",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc && cp -r src/assets dist/assets",
     "dev": "tsc --watch",
+    "lint": "eslint src",
     "start": "node dist/index.js",
     "benchmark:telemetry": "pnpm build && node scripts/benchmark-telemetry-overhead.mjs",
     "benchmark:telemetry:corpus": "pnpm build && node scripts/benchmark-open-source-telemetry.mjs",
@@ -39,23 +40,27 @@
     "url": "https://github.com/haystackeditor/haystack-review/issues"
   },
   "dependencies": {
-    "@babel/core": "7.29.0",
+    "@aws-sdk/client-ssm": "3.987.0",
+    "@babel/core": "8.0.6",
+    "@inquirer/prompts": "8.7.2",
     "@modelcontextprotocol/sdk": "1.26.0",
-    "chalk": "5.6.2",
-    "commander": "12.1.0",
+    "chalk": "6.0.0",
+    "commander": "15.0.0",
     "fast-glob": "3.3.3",
-    "glob": "10.5.0",
-    "inquirer": "9.3.8",
-    "ws": "8.21.0",
-    "yaml": "2.8.2",
-    "zod": "3.25.76"
+    "ws": "8.21.3",
+    "yaml": "2.9.1",
+    "zod": "4.6.5"
   },
   "devDependencies": {
-    "@types/inquirer": "9.0.9",
-    "@types/node": "20.19.30",
+    "@eslint/js": "8.57.1",
+    "@types/node": "22.19.8",
     "@types/ws": "8.18.1",
-    "typescript": "5.9.3",
-    "vitest": "4.1.10"
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/parser": "7.18.0",
+    "eslint": "8.57.1",
+    "globals": "13.24.0",
+    "typescript": "6.0.3",
+    "vitest": "5.0.1"
   },
   "files": [
     "dist",
@@ -63,6 +68,6 @@
   ],
   "bundledDependencies": [],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.18"
   }
 }

package/schemas/case-batch.v1.json

@@ -0,0 +1,235 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://docs.haystackeditor.com/cli/schemas/case-batch.v1.json",
+  "title": "Haystack hosted case batch (CASE-BATCH-V1)",
+  "description": "Machine-readable output of `haystack case-batch submit|status|cancel|finalize|bundle --json`. The run-side shapes mirror infra/lambda/haystack-design-verifier-shared/case_batch_contracts.ts.",
+  "type": "object",
+  "required": ["schema_version", "operation", "run_id"],
+  "properties": {
+    "schema_version": { "const": "1.0.1" },
+    "operation": { "enum": ["submit", "status", "cancel", "finalize", "bundle"] },
+    "run_id": { "type": "string", "pattern": "^cv_[0-9a-f]{48}$" },
+    "repository": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,100}/[A-Za-z0-9_.-]{1,100}$" },
+    "admitted": { "enum": ["created", "existing"] },
+    "base_commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "head_commit": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+    "base_world": { "type": "string", "pattern": "^frz_[0-9a-f]{16}$" },
+    "head_world": { "type": "string", "pattern": "^frz_[0-9a-f]{16}$" },
+    "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$" },
+    "cases": {
+      "description": "On submit, the number of cases sent. On status, the per-case rows.",
+      "oneOf": [
+        { "type": "integer", "minimum": 1, "maximum": 5000 },
+        {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "position", "status", "outcome_status", "unknown_reason", "wall_ms", "cleanup_proven"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,160}$" },
+              "position": { "type": "integer", "minimum": 0, "maximum": 4999 },
+              "label": { "type": "string" },
+              "condition_id": { "type": "string" },
+              "status": { "enum": ["running", "completed", "incomplete"] },
+              "launched_at_ms": { "type": "integer", "minimum": 0 },
+              "finished_at_ms": { "type": ["integer", "null"], "minimum": 0 },
+              "outcome_status": { "enum": ["AGREE", "DIFFER", "UNKNOWN", null] },
+              "unknown_reason": {
+                "type": ["string", "null"],
+                "description": "Open by ruling 1: an unrecognised reason still reads as UNKNOWN."
+              },
+              "wall_ms": { "type": ["integer", "null"], "minimum": 0 },
+              "cleanup_proven": { "type": ["boolean", "null"] },
+              "comparison_path": { "type": ["string", "null"] },
+              "case_bundle_path": { "type": ["string", "null"] },
+              "differing_outcomes": { "type": "array", "items": { "type": "string" } },
+              "detail": { "type": ["string", "null"] },
+              "execution_path": { "enum": ["resident-sealed-plan", "sealed-plan", "record-replay", null] },
+              "node_ids": {
+                "description": "v4: the node each arm's VM was placed on; null when the outcome names none.",
+                "type": ["object", "null"],
+                "required": ["base1", "head"],
+                "properties": {
+                  "base1": { "type": ["string", "null"] },
+                  "head": { "type": ["string", "null"] }
+                }
+              },
+              "failure": {
+                "description": "v4: the typed failure behind an UNKNOWN that is not an arrival or wall outcome, and behind an arrival-failed whose two arms stalled on the same step (error_class same-step-stall); null otherwise. Source is open like unknown_reason: a source added later still reads.",
+                "type": ["object", "null"],
+                "required": ["source", "arm", "error_class", "error_code", "node_id"],
+                "properties": {
+                  "source": { "type": "string", "description": "control-plane, transport, harness or runner" },
+                  "arm": { "enum": ["base1", "head", null] },
+                  "error_class": { "type": "string" },
+                  "error_code": { "type": ["string", "null"] },
+                  "node_id": { "type": ["string", "null"] }
+                }
+              },
+              "phases": { "type": ["object", "null"] },
+              "vm_ids": { "type": "array", "items": { "type": "string" } },
+              "lease_ids": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      ]
+    },
+    "limits": {
+      "type": "object",
+      "required": ["max_concurrent_cases", "per_case_wall_ms", "total_budget_ms"],
+      "properties": {
+        "max_concurrent_cases": { "type": "integer", "minimum": 1, "maximum": 500 },
+        "per_case_wall_ms": { "type": "integer", "minimum": 1000, "maximum": 600000 },
+        "total_budget_ms": { "type": "integer", "minimum": 10000, "maximum": 1800000 }
+      }
+    },
+    "source_patch_attached": { "type": "boolean" },
+    "status": { "enum": ["queued", "preparing", "searching", "draining", "completed", "incomplete", "cancelled"] },
+    "terminal": { "type": "boolean" },
+    "timed_out": { "type": "boolean" },
+    "generation": { "type": "integer", "minimum": 0 },
+    "observed_at": { "type": "string" },
+    "cleanup_complete": { "type": "boolean" },
+    "vm_ids": { "type": "integer", "minimum": 0 },
+    "worlds": {
+      "type": "object",
+      "properties": {
+        "base": { "type": ["string", "null"] },
+        "head": { "type": ["string", "null"] }
+      }
+    },
+    "clocks": {
+      "type": "object",
+      "properties": {
+        "preparation_started_at": { "type": ["string", "null"] },
+        "search_started_at": { "type": ["string", "null"] },
+        "launches_closed_at": { "type": ["string", "null"] },
+        "finished_at": { "type": ["string", "null"] },
+        "search_budget_ms": { "type": "integer", "minimum": 0 },
+        "search_wall_ms": { "type": "integer", "minimum": 0 },
+        "drain_wall_ms": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "totals": {
+      "type": "object",
+      "required": ["cases", "launched", "settled", "agree", "differ", "unknown", "cleanup_proven", "cleanup_unproven", "leases_released"],
+      "properties": {
+        "cases": { "type": "integer", "minimum": 0 },
+        "launched": { "type": "integer", "minimum": 0 },
+        "settled": { "type": "integer", "minimum": 0 },
+        "agree": { "type": "integer", "minimum": 0 },
+        "differ": { "type": "integer", "minimum": 0 },
+        "unknown": { "type": "integer", "minimum": 0 },
+        "cleanup_proven": { "type": "integer", "minimum": 0 },
+        "cleanup_unproven": { "type": "integer", "minimum": 0 },
+        "leases_released": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "admission": {
+      "type": "object",
+      "required": ["requested_cases", "admitted_cases", "pool", "free_vm_slots", "reserved_vm_slots", "worker_processes", "cases_per_process"],
+      "properties": {
+        "requested_cases": { "type": "integer", "minimum": 0 },
+        "admitted_cases": { "type": "integer", "minimum": 0 },
+        "pool": { "enum": ["small", "big"] },
+        "free_vm_slots": { "type": "integer", "minimum": 0 },
+        "reserved_vm_slots": { "type": "integer", "minimum": 0 },
+        "worker_processes": { "type": "integer", "minimum": 0 },
+        "cases_per_process": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "unknown_reasons": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1 } },
+    "cases_returned": { "type": "integer", "minimum": 0 },
+    "cases_truncated": { "type": "boolean" },
+    "pages": { "type": "integer", "minimum": 1 },
+    "waves": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["wave", "at_ms", "launched"],
+        "properties": {
+          "wave": { "type": "integer", "minimum": 0 },
+          "at_ms": { "type": "integer", "minimum": 0 },
+          "launched": { "type": "integer", "minimum": 0 }
+        }
+      }
+    },
+    "waves_truncated": { "type": "boolean" },
+    "exit_code": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "error": { "type": "string" },
+    "cancel_requested": { "const": true },
+    "previous_status": { "description": "On finalize, the batch's recorded status just before it.", "type": "string" },
+    "last_updated_at": { "description": "On finalize, the batch record's last update before it.", "type": "string" },
+    "eligibility": { "description": "On finalize, what made the batch finalizable.", "enum": ["cancel-requested", "stale"] },
+    "reason": { "description": "On finalize, the operator's reason, recorded as the batch error.", "type": "string" },
+    "finalized_at": { "type": "string" },
+    "next_command": { "type": "string" },
+    "out_dir": { "type": "string" },
+    "manifest": {
+      "type": "object",
+      "required": ["path", "sha256", "bytes"],
+      "properties": {
+        "path": { "const": "manifest.json" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "sha256", "bytes", "verified"],
+        "properties": {
+          "path": { "type": "string" },
+          "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+          "bytes": { "type": "integer", "minimum": 0 },
+          "verified": { "const": true }
+        }
+      }
+    },
+    "artifact_count": { "type": "integer", "minimum": 0 },
+    "pending": {
+      "description": "On bundle, the listed PNGs the service reported as still uploading (HTTP 409, reason artifact-pending): the coordinator publishes a batch's PNGs after it is terminal. Nothing is written for them. Non-empty means the command exited 75 (EX_TEMPFAIL); retry, for example with --only for each path.",
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "failed": {
+      "description": "On bundle, the listed PNGs the service reported as failed for good (HTTP 410, reason artifact-failed): the coordinator gave up on their upload and recorded why. Nothing is written for them and a retry cannot fetch them. Non-empty with nothing pending means the command exited 1.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "error_class", "status", "message"],
+        "properties": {
+          "path": { "type": "string" },
+          "error_class": { "type": "string" },
+          "status": { "type": ["integer", "null"] },
+          "message": { "type": "string" }
+        }
+      }
+    },
+    "total_bytes": { "type": "integer", "minimum": 0 }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "operation": { "const": "status" } }, "required": ["operation"] },
+      "then": { "required": ["repository", "status", "terminal", "timed_out", "totals", "cases", "cases_returned", "cases_truncated", "exit_code"] }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "submit" } }, "required": ["operation"] },
+      "then": { "required": ["repository", "admitted", "base_commit", "head_commit", "idempotency_key", "cases", "limits", "next_command"] }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "cancel" } }, "required": ["operation"] },
+      "then": { "required": ["repository", "cancel_requested"] }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "finalize" } }, "required": ["operation"] },
+      "then": { "required": ["repository", "status", "terminal", "cleanup_complete", "generation", "previous_status", "last_updated_at", "eligibility", "reason", "finalized_at"] }
+    },
+    {
+      "if": { "properties": { "operation": { "const": "bundle" } }, "required": ["operation"] },
+      "then": { "required": ["repository", "out_dir", "manifest", "artifacts", "artifact_count", "total_bytes"] }
+    }
+  ]
+}