@haystackeditor/cli 0.15.31 → 0.16.0

package/dist/index.js

@@ -24,39 +24,71 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import chalk from 'chalk';
 import { Command, Option } from 'commander';
-import { statusCommand } from './commands/status.js';
 import { withSchema } from './schema.js';
-import { initCommand } from './commands/init.js';
-import { authListCommand, authUseCommand, loginCommand, logoutCommand, whoamiCommand, } from './commands/login.js';
-import { handleAgenticTool, handleAutoMerge, handleAutoFix, handleWaitForReviewers, isAutoMergeEnabled, isAutoFixEnabled } from './commands/config.js';
-import { installSkills, listSkills } from './commands/skills.js';
-import { cloudVerifierUniverseValidateCommand } from './commands/cloud-verifier-universe.js';
-import { cloudVerifierIdentityCensusCommand } from './commands/cloud-verifier-identity-census.js';
-import { cloudVerifierDataStoreDriftCommand } from './commands/cloud-verifier-data-store-drift.js';
-import { cloudVerifierBehaviorsValidateCommand } from './commands/cloud-verifier-behaviors.js';
-import { prepareUniverseReviewCommand } from './commands/prepare-universe-review.js';
-import { scaffoldProvisionalUniverseCommand } from './commands/scaffold-provisional-universe.js';
-import { hooksInstall, hooksStatus } from './commands/hooks.js';
-import { submitCommand } from './commands/submit.js';
-import { installSessionHooks, sessionHooksStatus } from './commands/install-session-hooks.js';
-import { listPolicies, addPolicy, removePolicy, initPolicies, addInstruction } from './commands/policy.js';
-import { triageCommand } from './commands/triage.js';
-import { designVerifyCommand } from './commands/design-verify.js';
-import { dismissCommand, markReviewedCommand, undismissCommand } from './commands/dismiss.js';
-import { requestReviewCommand } from './commands/request-review.js';
-import { reviewCommand } from './commands/review.js';
-import { prStatusCommand } from './commands/pr-status.js';
-import { prReadCommand } from './commands/pr.js';
-import { inboxListCommand } from './commands/inbox.js';
-import { askHaystackCommand } from './commands/ask.js';
-import { telemetryInstrumentCommand } from './commands/telemetry.js';
-import { setupCommand } from './commands/setup.js';
-import { schemaCommand, listSchemas } from './commands/schema-cmd.js';
-import { registerWebhook, listWebhooks, rotateWebhookSecret, setWebhookEnabled, listDeliveries, replayDelivery, } from './commands/webhooks.js';
-import { editRulesCommand, validateRulesCommand } from './commands/rules.js';
-import { systemMapValidateCommand } from './commands/system-map.js';
-import { verifyCommand } from './commands/verify.js';
-import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeTokenCommand, } from './commands/tokens.js';
+import { lazy } from './lazy.js';
+// Command modules load on first use (see src/lazy.ts). Keep new commands
+// on this pattern: a static import here puts its whole dependency graph on
+// the startup path of every invocation, including --version and --help.
+const statusCommand = lazy(() => import('./commands/status.js'), 'statusCommand');
+const initCommand = lazy(() => import('./commands/init.js'), 'initCommand');
+const authListCommand = lazy(() => import('./commands/login.js'), 'authListCommand');
+const authUseCommand = lazy(() => import('./commands/login.js'), 'authUseCommand');
+const loginCommand = lazy(() => import('./commands/login.js'), 'loginCommand');
+const logoutCommand = lazy(() => import('./commands/login.js'), 'logoutCommand');
+const whoamiCommand = lazy(() => import('./commands/login.js'), 'whoamiCommand');
+const handleAgenticTool = lazy(() => import('./commands/config.js'), 'handleAgenticTool');
+const handleAutoMerge = lazy(() => import('./commands/config.js'), 'handleAutoMerge');
+const handleAutoFix = lazy(() => import('./commands/config.js'), 'handleAutoFix');
+const handleWaitForReviewers = lazy(() => import('./commands/config.js'), 'handleWaitForReviewers');
+const isAutoMergeEnabled = lazy(() => import('./commands/config.js'), 'isAutoMergeEnabled');
+const isAutoFixEnabled = lazy(() => import('./commands/config.js'), 'isAutoFixEnabled');
+const installSkills = lazy(() => import('./commands/skills.js'), 'installSkills');
+const listSkills = lazy(() => import('./commands/skills.js'), 'listSkills');
+const cloudVerifierUniverseValidateCommand = lazy(() => import('./commands/cloud-verifier-universe.js'), 'cloudVerifierUniverseValidateCommand');
+const cloudVerifierIdentityCensusCommand = lazy(() => import('./commands/cloud-verifier-identity-census.js'), 'cloudVerifierIdentityCensusCommand');
+const cloudVerifierDataStoreDriftCommand = lazy(() => import('./commands/cloud-verifier-data-store-drift.js'), 'cloudVerifierDataStoreDriftCommand');
+const cloudVerifierBehaviorsValidateCommand = lazy(() => import('./commands/cloud-verifier-behaviors.js'), 'cloudVerifierBehaviorsValidateCommand');
+const prepareUniverseReviewCommand = lazy(() => import('./commands/prepare-universe-review.js'), 'prepareUniverseReviewCommand');
+const scaffoldProvisionalUniverseCommand = lazy(() => import('./commands/scaffold-provisional-universe.js'), 'scaffoldProvisionalUniverseCommand');
+const hooksInstall = lazy(() => import('./commands/hooks.js'), 'hooksInstall');
+const hooksStatus = lazy(() => import('./commands/hooks.js'), 'hooksStatus');
+const submitCommand = lazy(() => import('./commands/submit.js'), 'submitCommand');
+const installSessionHooks = lazy(() => import('./commands/install-session-hooks.js'), 'installSessionHooks');
+const sessionHooksStatus = lazy(() => import('./commands/install-session-hooks.js'), 'sessionHooksStatus');
+const listPolicies = lazy(() => import('./commands/policy.js'), 'listPolicies');
+const addPolicy = lazy(() => import('./commands/policy.js'), 'addPolicy');
+const removePolicy = lazy(() => import('./commands/policy.js'), 'removePolicy');
+const initPolicies = lazy(() => import('./commands/policy.js'), 'initPolicies');
+const addInstruction = lazy(() => import('./commands/policy.js'), 'addInstruction');
+const triageCommand = lazy(() => import('./commands/triage.js'), 'triageCommand');
+const designVerifyCommand = lazy(() => import('./commands/design-verify.js'), 'designVerifyCommand');
+const dismissCommand = lazy(() => import('./commands/dismiss.js'), 'dismissCommand');
+const markReviewedCommand = lazy(() => import('./commands/dismiss.js'), 'markReviewedCommand');
+const undismissCommand = lazy(() => import('./commands/dismiss.js'), 'undismissCommand');
+const requestReviewCommand = lazy(() => import('./commands/request-review.js'), 'requestReviewCommand');
+const reviewCommand = lazy(() => import('./commands/review.js'), 'reviewCommand');
+const prStatusCommand = lazy(() => import('./commands/pr-status.js'), 'prStatusCommand');
+const prReadCommand = lazy(() => import('./commands/pr.js'), 'prReadCommand');
+const inboxListCommand = lazy(() => import('./commands/inbox.js'), 'inboxListCommand');
+const askHaystackCommand = lazy(() => import('./commands/ask.js'), 'askHaystackCommand');
+const telemetryInstrumentCommand = lazy(() => import('./commands/telemetry.js'), 'telemetryInstrumentCommand');
+const setupCommand = lazy(() => import('./commands/setup.js'), 'setupCommand');
+const schemaCommand = lazy(() => import('./commands/schema-cmd.js'), 'schemaCommand');
+const listSchemas = lazy(() => import('./commands/schema-cmd.js'), 'listSchemas');
+const registerWebhook = lazy(() => import('./commands/webhooks.js'), 'registerWebhook');
+const listWebhooks = lazy(() => import('./commands/webhooks.js'), 'listWebhooks');
+const rotateWebhookSecret = lazy(() => import('./commands/webhooks.js'), 'rotateWebhookSecret');
+const setWebhookEnabled = lazy(() => import('./commands/webhooks.js'), 'setWebhookEnabled');
+const listDeliveries = lazy(() => import('./commands/webhooks.js'), 'listDeliveries');
+const replayDelivery = lazy(() => import('./commands/webhooks.js'), 'replayDelivery');
+const editRulesCommand = lazy(() => import('./commands/rules.js'), 'editRulesCommand');
+const validateRulesCommand = lazy(() => import('./commands/rules.js'), 'validateRulesCommand');
+const systemMapValidateCommand = lazy(() => import('./commands/system-map.js'), 'systemMapValidateCommand');
+const verifyCommand = lazy(() => import('./commands/verify.js'), 'verifyCommand');
+const headlessLoginCommand = lazy(() => import('./commands/tokens.js'), 'headlessLoginCommand');
+const headlessLogoutCommand = lazy(() => import('./commands/tokens.js'), 'headlessLogoutCommand');
+const listTokensCommand = lazy(() => import('./commands/tokens.js'), 'listTokensCommand');
+const revokeTokenCommand = lazy(() => import('./commands/tokens.js'), 'revokeTokenCommand');
 // `mcp` is imported lazily inside its command action (below), NOT at the top level.
 // It is the only module that pulls in `@modelcontextprotocol/sdk`; keeping it out of
 // the startup import graph means a missing/broken SDK can never crash core commands
@@ -99,17 +131,14 @@ const program = new Command();
 program
     .name('haystack')
     .description('Haystack CLI — automated PR review, triage, and merge queue')
-    .version(getVersion());
+    .version(getVersion())
+    // commander 13 made surplus positional arguments an error; the CLI has always
+    // ignored them. Every command created below inherits this setting.
+    .allowExcessArguments();
 program
     .command('schema [name]')
     .description('Print the JSON Schema for a command\'s --json output')
-    .action((name) => {
-    if (!name) {
-        listSchemas();
-        return;
-    }
-    schemaCommand(name);
-});
+    .action((name) => (name ? schemaCommand(name) : listSchemas()));
 program
     .command('init')
     .description('Create .haystack.json configuration')
@@ -130,9 +159,9 @@ program
     .option('--json', 'Agent mode: emit NDJSON events on stdout, read answers on stdin (no TTY prompts)')
     .option('--repo <repo...>', 'Repo(s) to configure (owner/name); skips the repo picker')
     .option('-y, --yes', 'Accept defaults non-interactively (keep all discovered items, confirm write, ENABLE auto-merge — pass --no-auto-merge to opt out)')
-    // Defining --no-auto-merge also accepts --auto-merge; default is "ask" unless
-    // one is explicitly passed (detected via getOptionValueSource below).
-    .option('--no-auto-merge', 'Set auto-merge in the written config (--auto-merge / --no-auto-merge; omit to be asked)')
+    // Only the negative form exists; there is no --auto-merge. Without the flag the
+    // wizard asks (detected via getOptionValueSource below).
+    .option('--no-auto-merge', 'Turn auto-merge off in the written config (omit to be asked)')
     .option('--answers <file>', 'JSON file of {questionId: value} pre-supplied answers')
     .addHelpText('after', `
 Steps: verify GitHub App → select repos → scan (rules/policies/instructions) →
@@ -154,9 +183,9 @@ Examples:
   haystack setup --json --repo owner/name
 `)
     .action((options, command) => {
-    // Tri-state auto-merge: undefined (ask) unless --auto-merge/--no-auto-merge
-    // was explicitly passed. commander defaults autoMerge to true because of the
-    // --no- form, so check the value source rather than the value.
+    // auto-merge: false when --no-auto-merge was passed, otherwise undefined (ask).
+    // commander defaults autoMerge to true because of the --no- form, so check
+    // the value source rather than the value.
     const autoMergeExplicit = command.getOptionValueSource('autoMerge') === 'cli';
     return setupCommand({
         json: options.json,
@@ -172,55 +201,53 @@ program
     .action(statusCommand);
 const verify = program
     .command('verify')
-    .description('Verify a change in matched cloud universes, or bisect a historical regression')
-    .argument('[specimen]', 'Launch specimen to run (default: all)')
-    .option('--repo <owner/repo>', 'GitHub repository to verify through the authenticated hosted service')
-    .option('--base <ref>', 'Base revision for a repository run')
-    .option('--head <ref>', 'Head revision for a repository run')
+    .description('Verify the current change with the hosted Haystack fleet')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--base <ref>', 'Base revision (default: merge base of HEAD and origin/default branch)')
+    .option('--head <ref>', 'Head revision (default: current HEAD commit)')
     .option('--intent-file <path>', 'Optional intent JSON with problem, goal, and intended_outcomes')
     .option('--idempotency-key <key>', 'Stable retry key (default: derived from repository, refs, and intent)')
     .option('--account <login>', 'Use a specific saved Haystack account')
-    .addOption(new Option('--no-wait', 'Return after the hosted run is queued').default(undefined))
+    .option('--no-wait', 'Return after the hosted run is queued')
     .option('--interval <seconds>', 'Hosted polling interval (default 5)')
     .option('--timeout <minutes>', 'Maximum hosted wait (default 35)')
-    .option('--intent-transcript <file>', 'Coding-agent transcript used as intent evidence')
-    .option('--server <url>', 'Verifier control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--token <token>', 'Bearer token for a control plane that requires auth (or HAYSTACK_VERIFY_TOKEN)')
-    .option('--no-open', 'Do not open the live results page')
     .option('--json', 'Machine-readable run status and results')
     .addHelpText('after', `
-Launch specimens:
-  posthog-js-478   Replay PostHog/posthog-js PR #478 in matched browser environments (latent-issue mode)
-  analytics-js-255 Identity routing regression with sandbox bisect
-  all              Run each reproduced specimen as an isolated chapter (default)
-
-Repository verification uses the authenticated hosted fleet and resolves refs
-once. Intent is optional. Hosted status also resumes these runs.
-
-For launch specimens, run the local control plane from the Haystack repository:
-  pnpm dev
+Run inside a git checkout after pushing your current commit. The repository
+comes from origin, head from HEAD, and base from git merge-base HEAD with
+origin's default branch (origin/HEAD, falling back to origin/main).
+Explicit --repo, --base, and --head values override these defaults.
+Intent is optional. Hosted status resumes an existing run.
 
 Examples:
-  haystack verify --repo owner/repo --base main --head feature --json
+  haystack verify
+  haystack verify --json
+  haystack verify --repo owner/repo --base main --head feature --no-wait
   haystack verify history owner/repo --limit 20
-  haystack verify hosted start owner/repo --base <sha> --head <sha> --intent-file <path>
-  haystack verify posthog-js-478         # start a run, then:
-  haystack verify reproducibility posthog-js-478 --runs 3
-  haystack verify watch                  # block until it finishes (exit 1 = tests failed)
-  haystack verify status                 # one-screen verdicts + live environment URLs
-  haystack verify findings               # every problem found, with the readings that moved
-  haystack verify show latest 3          # one test in full: readings, timeline, SDK log
-  haystack verify diff latest 3          # base-vs-head screenshot differ (1/2/3 views)
-  haystack verify open latest 3 --live   # open a failing test's live environment
-  haystack verify cleanup latest 3       # retained-state deletion/reference status
-  haystack verify refork latest 3 attempt:fix-2 # checkpoint a durable child
-  haystack verify shell latest 3         # terminal into that live universe
-  haystack verify artifacts latest       # pull screenshots / DOM / video locally
-  haystack verify sandboxes --kill-stale # reclaim E2B capacity from superseded runs
-  haystack verify reseal <specimen>      # rebuild a sealed bundle + restart control plane
+  haystack verify hosted status cv_<48 lowercase hex characters> --wait
 `)
-    .action((specimen, options) => runPublicCommand(() => verifyCommand(specimen, options), options.json));
-const verifyRunArg = 'Run id, chapter id (newest run of that chapter), or "latest" (default)';
+    .action(options => runPublicCommand(() => verifyCommand(options), options.json));
+/**
+ * Options for a `verify` subcommand: its own values, plus any option the user
+ * passed to an ancestor (`haystack verify --no-wait hosted status ...`).
+ * Ancestors' defaults are not inherited. verify's lone --no-wait gets
+ * commander's implicit default of true, which would otherwise make
+ * `verify hosted status` wait although it waits only with --wait.
+ */
+function verifyCommandOptions(command) {
+    const commands = [];
+    for (let current = command; current; current = current.parent) {
+        commands.unshift(current);
+    }
+    const options = { ...command.opts() };
+    for (const current of commands) {
+        for (const [name, value] of Object.entries(current.opts())) {
+            if (current.getOptionValueSource(name) !== 'default')
+                options[name] = value;
+        }
+    }
+    return options;
+}
 verify
     .command('history')
     .description('Read your recent finished hosted verification runs without starting a run')
@@ -237,7 +264,7 @@ Examples:
   haystack verify history owner/repo --limit 50 --account my-login --json
 `)
     .action(async (repository, _options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const options = verifyCommandOptions(cmd);
     const { verifyHistoryCommand } = await import('./commands/verify-history.js');
     return runPublicCommand(() => verifyHistoryCommand(repository, options), options.json);
 });
@@ -260,17 +287,16 @@ hostedVerify
     .command('start')
     .description('Start an authenticated production verification and wait for its terminal result')
     .argument('<repository>', 'Exact GitHub owner/repository name')
-    // `verify` already owns --base/--head for the local specimen launcher.
+    // `verify` already owns --base/--head for repository verification.
     // Re-declaring these as Commander requiredOption values makes the parent
     // consume them and the child then reject a valid invocation. Runtime
     // validation below accepts the inherited values and still fails closed.
     .option('--base <sha>', 'Required: exact 40-character lowercase base commit SHA')
     .option('--head <sha>', 'Required: exact 40-character lowercase head commit SHA')
-    .option('--intent-file <path>', 'Required for this alias: JSON with exactly problem, goal, and intended_outcomes')
+    .option('--intent-file <path>', 'Optional JSON with exactly problem, goal, and intended_outcomes')
     .option('--idempotency-key <key>', 'Stable retry key (default: deterministic from repository and commits)')
-    .option('--replay-plan-from <run-id>', 'Reuse the exact validated risk plan from a completed owned run')
     .option('--account <login>', 'Use a specific saved Haystack account')
-    .option('--no-wait', 'Return after the production workflow is queued')
+    .option('--no-wait', 'Return after the hosted run is queued')
     .option('--interval <seconds>', 'Polling interval while waiting (default 5)')
     .option('--timeout <minutes>', 'Maximum wait (default 35)')
     .option('--json', 'Versioned machine-readable run status and terminal output')
@@ -278,18 +304,15 @@ hostedVerify
 The default idempotency key makes an exact retry return the original run. Pass
 --idempotency-key with a new stable key only when you intentionally want a
 fresh production execution of the same commit pair.
---replay-plan-from requires the same repository and exact commit pair and emits
-a schema-9 terminal receipt with replay provenance.
 
 Examples:
   haystack verify hosted start owner/repo --base <sha> --head <sha> --intent-file <path>
-  haystack verify hosted start owner/repo --base <sha> --head <sha> --intent-file <path> --replay-plan-from cv_<48 lowercase hex characters>
   haystack verify hosted start owner/repo --base <sha> --head <sha> --intent-file <path> --no-wait --json
 `)
     .action(async (repository, _options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const options = verifyCommandOptions(cmd);
     const { verifyHostedStartCommand } = await import('./commands/verify-hosted.js');
-    return runPublicCommand(() => verifyHostedStartCommand(repository, options), options.json);
+    return runPublicCommand(() => verifyHostedStartCommand(repository, { ...options, base: options.base, head: options.head }), options.json);
 });
 hostedVerify
     .command('status')
@@ -305,43 +328,37 @@ Example:
   haystack verify hosted status cv_<48 lowercase hex characters> --wait --json
 `)
     .action(async (runId, _options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const options = verifyCommandOptions(cmd);
     const { verifyHostedStatusCommand } = await import('./commands/verify-hosted.js');
     return runPublicCommand(() => verifyHostedStatusCommand(runId, options), options.json);
 });
 hostedVerify
     .command('reproducibility')
-    .description('Replay one exact hosted risk plan or run fresh plans to report drift')
+    .description('Repeat independent fleet runs and report each run receipt')
     .argument('<repository>', 'Exact GitHub owner/repository name')
     .option('--base <sha>', 'Required: exact 40-character lowercase base commit SHA')
     .option('--head <sha>', 'Required: exact 40-character lowercase head commit SHA')
-    .option('--intent-file <path>', 'Required: agent-supplied JSON reused for every hosted run in the series')
-    .option('--runs <n>', 'Number of sequential production runs (default 3; min 2, max 10)')
+    .option('--intent-file <path>', 'Optional intent JSON reused for every fleet run')
+    .option('--runs <n>', 'Number of sequential fleet runs (default 3; min 2, max 10)')
     .option('--series-key <key>', 'Stable series key for resumable idempotent retries')
-    .option('--fresh-plans', 'Run the planner independently for every run instead of replaying the first plan')
     .option('--account <login>', 'Use a specific saved Haystack account')
     .option('--interval <seconds>', 'Polling interval for each run (default 5)')
     .option('--timeout <minutes>', 'Maximum wait per run (default 35)')
-    .option('--json', 'Versioned machine-readable reproducibility report')
+    .option('--json', 'Machine-readable series with each fleet run receipt')
     .addHelpText('after', `
-The first run creates a fresh risk plan. Every later run replays that exact
-validated plan against the same repository and commit pair with a distinct,
-series-derived idempotency key. A reproducible verdict requires schema-9 replay
-provenance, stable assessment outcomes, and no inconclusive cells.
-
-With --fresh-plans, every run plans independently. A reproducible verdict then
-requires one stable-id plan variant, one assessment variant, no replay
-provenance, and no inconclusive cells. Use this mode to detect planner drift;
-use the default mode to isolate executor or assessment drift.
+Each run independently plans and verifies the same exact commit pair. The
+series key gives each run a distinct, resumable idempotency key.
+Independent plans do not share an execution identity: the report leaves
+reproducibility unestablished and exits 2. A timeout stops the series and
+includes the command to resume the active run.
 
 Example:
-  haystack verify hosted reproducibility owner/repo --base <sha> --head <sha> --intent-file <path> --runs 3
-  haystack verify hosted reproducibility owner/repo --base <sha> --head <sha> --intent-file <path> --runs 3 --fresh-plans
+  haystack verify hosted reproducibility owner/repo --base <sha> --head <sha> --runs 3 --json
 `)
     .action(async (repository, _options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const options = verifyCommandOptions(cmd);
     const { verifyHostedReproducibilityCommand } = await import('./commands/verify-hosted-reproducibility.js');
-    return runPublicCommand(() => verifyHostedReproducibilityCommand(repository, options), options.json);
+    return runPublicCommand(() => verifyHostedReproducibilityCommand(repository, { ...options, base: options.base, head: options.head }), options.json);
 });
 hostedVerify
     .command('mcp')
@@ -353,7 +370,7 @@ No credential, repository source, provider metadata, or sandbox mutation tool
 is exposed through this production server.
 `)
     .action(async (_options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const options = verifyCommandOptions(cmd);
     try {
         const { runHostedVerifyMcpServer } = await import('./commands/verify-hosted-mcp.js');
         await runHostedVerifyMcpServer(options);
@@ -363,48 +380,15 @@ is exposed through this production server.
         process.exit(1);
     }
 });
-verify
-    .command('reproducibility')
-    .description('Separate frozen-plan drift from executor/judgment nondeterminism')
-    .argument('<specimen>', 'Specimen id, e.g. posthog-js-478')
-    .option('--runs <n>', 'Number of sequential runs to compare (default 3; min 2, max 20)')
-    .option('--scope <scope>', 'executor replays one frozen plan (default); planner/full independently replan each run', 'executor')
-    .option('--plan-source <runId>', 'executor scope: replay this existing structured frozen plan for every run')
-    .option('--interval <seconds>', 'Polling interval for each run (default 3)')
-    .option('--timeout <minutes>', 'Per-run timeout (default: wait forever)')
-    .option('--server <url>', 'Verifier control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--token <token>', 'Bearer token for a control plane that requires auth (or HAYSTACK_VERIFY_TOKEN)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable stable/unstable cell report')
-    .action(async (specimen, commandOptions, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...commandOptions };
-    const { verifyReproducibilityCommand } = await import('./commands/verify-reproducibility.js');
-    return runPublicCommand(() => verifyReproducibilityCommand(specimen, options), options.json);
-});
-verify
-    .command('status')
-    .description('One screen for a run: per-test verdicts, counts, live environments and expiry')
-    .argument('[run]', verifyRunArg)
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable summary')
-    .action(async (run, _options, cmd) => {
-    // optsWithGlobals: the parent `verify` command also declares --json/--server
-    // and commander's default parsing lets it consume those flags even when
-    // they appear after the subcommand; the merged view (self wins) restores them.
-    const options = cmd.optsWithGlobals();
-    const { verifyStatusCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyStatusCommand(run, options), options.json);
-});
 verify
     .command('cases <run>')
     .description('List cloud verification cases available to explore for 24 hours after completion')
     .option('--repo <owner/repo>', 'Required exact GitHub repository; uses your Haystack login')
     .option('--json', 'Machine-readable case IDs and expiry times')
     .action(async (run, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
+    const options = verifyCommandOptions(cmd);
     const { verifyCasesCommand } = await import('./commands/verify-explore.js');
-    return runPublicCommand(() => verifyCasesCommand(run, options), options.json);
+    return runPublicCommand(() => verifyCasesCommand(run, { ...options, repo: options.repo }), options.json);
 });
 verify
     .command('explore <run> <case-id>')
@@ -420,210 +404,106 @@ verify
     .option('--no-wait', 'Return after submitting the action')
     .option('--json', 'Machine-readable action and command output')
     .action(async (run, caseId, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
+    const options = verifyCommandOptions(cmd);
     const { verifyExploreCommand } = await import('./commands/verify-explore.js');
-    return runPublicCommand(() => verifyExploreCommand(run, caseId, options), options.json);
-});
-verify
-    .command('watch')
-    .description('Follow a run until it finishes; exit 0 all passed, 1 tests failed, 2 run/infra broke')
-    .argument('[run]', verifyRunArg)
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--interval <seconds>', 'Poll interval (default 3)')
-    .option('--timeout <minutes>', 'Give up after this long (default: wait forever)')
-    .option('--json', 'Suppress streaming; print the final summary as JSON')
-    .action(async (run, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyWatchCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyWatchCommand(run, options), options.json);
-});
-verify
-    .command('list')
-    .description('Runs newest first: chapter, verdict counts, age (control plane, else disk)')
-    .option('--limit <n>', 'Max runs to show (default 20)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable list')
-    .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyListCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyListCommand(options), options.json);
-});
-verify
-    .command('findings')
-    .description('Every problem the run found, in one screen: what failed, which readings moved, live links')
-    .argument('[run]', verifyRunArg)
-    .option('--full', 'Print the judge\'s full explanation for each finding')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable findings')
-    .action(async (run, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyFindingsCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyFindingsCommand(run, options), options.json);
-});
-verify
-    .command('open')
-    .description('Open a run artifact (screenshot/video/DOM) or a failing test\'s live environment')
-    .argument('<run>', verifyRunArg)
-    .argument('<target>', 'Test selector (ordinal/title), or an artifact file name (….png/.webm/.html)')
-    .option('--live', 'Open the test\'s live environment URL instead of an artifact')
-    .option('--side <side>', 'base or head (default head)')
-    .option('--step <n>', 'Open the screenshot captured after replay step n')
-    .option('--kind <kind>', 'screenshot | video | dom (default: video, else last screenshot)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .action(async (run, target, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyOpenCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyOpenCommand(run, target, options));
-});
-verify
-    .command('diff')
-    .description('Open a base-vs-head screenshot differ for one test (1 what changed / 2 before / 3 after)')
-    .argument('<run>', verifyRunArg)
-    .argument('<cell>', 'Test selector: ordinal, cell id, or title substring')
-    .option('--step <n>', 'Compare only the screenshot captured after replay step n')
-    .option('--out <dir>', 'Where to build the diff page (default: a temp directory)')
-    .option('--no-open', 'Build the page but do not open it')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable result (implies --no-open)')
-    .action(async (run, cell, _options, cmd) => {
-    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
-    const { verifyDiffCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyDiffCommand(run, cell, options), options.json);
-});
-verify
-    .command('cleanup')
-    .description('Show exact retained-state references, provider deletion, and cleanup-SLO status')
-    .argument('<run>', verifyRunArg)
-    .argument('<cell>', 'Stable test selector: ordinal, riskCellId, or exact planner cellKey')
-    .option('--side <side>', 'base or head (default head)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable cleanup status')
-    .action(async (run, cell, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyCleanupCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyCleanupCommand(run, cell, options), options.json);
-});
-verify
-    .command('reopen')
-    .description('Attach fresh E2B compute to retained Archil state from a test or exact fork ID')
-    .argument('<source>', 'Run selector, or an exact archil:…:branch:… fork ID')
-    .argument('[cell]', 'Stable test selector for a run: ordinal, riskCellId, or exact planner cellKey')
-    .option('--side <side>', 'base or head (default head)')
-    .option('--open-browser', 'Open the restarted application in a browser')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable attachment details')
-    .action(async (source, cell, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyReopenCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyReopenCommand(source, cell, options), options.json);
+    return runPublicCommand(() => verifyExploreCommand(run, caseId, { ...options, repo: options.repo }), options.json);
 });
-verify
-    .command('refork')
-    .description('Checkpoint a reopened Archil universe into a durable child fork')
-    .argument('<source>', 'Run selector, or an exact archil:…:branch:… parent fork ID')
-    .argument('<cell-or-child-key>', 'Stable test selector for a run, or child key for an exact fork ID')
-    .argument('[child-key]', 'Structured stable child key when source is a run')
-    .option('--side <side>', 'base or head (default head; only applies to a run)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable parent, child, checkpoint, and expiry')
-    .action(async (source, cellOrChildKey, childKey, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyReforkCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyReforkCommand(source, cellOrChildKey, childKey, options), options.json);
-});
-verify
-    .command('shell')
-    .description('Terminal into a failing test\'s live universe (e2b sandbox connect)')
-    .argument('<run>', verifyRunArg)
-    .argument('<cell>', 'Stable test selector: ordinal, riskCellId, or exact planner cellKey')
-    .option('--side <side>', 'base or head (default head; only failing tests keep a universe alive)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .action(async (run, cell, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyShellCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyShellCommand(run, cell, options));
-});
-verify
-    .command('show')
-    .description('One test in full: finding, changed readings, request timeline, SDK log lines')
-    .argument('<run>', verifyRunArg)
-    .argument('<cell>', 'Test ordinal, cell id, planner cell key, or title substring')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--no-timeline', 'Skip the request timeline')
-    .option('--json', 'Machine-readable detail')
-    .action(async (run, cell, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyShowCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyShowCommand(run, cell, options), options.json);
-});
-verify
-    .command('artifacts')
-    .description('Pull a run\'s screenshots, DOM snapshots and videos to a local directory')
-    .argument('<run>', verifyRunArg)
-    .option('--out <dir>', 'Destination (default: ./verify-artifacts/<runId>)')
-    .option('--cell <selector>', 'Only artifacts for one test (ordinal, cell id, or title substring)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable result')
-    .action(async (run, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyArtifactsCommand } = await import('./commands/verify-ops.js');
-    return runPublicCommand(() => verifyArtifactsCommand(run, options), options.json);
+const caseBatch = program
+    .command('case-batch')
+    .description('Submit and poll product-fuzzing case batches on the hosted coordinator (CASE-BATCH-V1)');
+caseBatch
+    .command('submit')
+    .description('Submit an ordered batch of already-generated cases against one frozen world pair')
+    .requiredOption('--repository <owner/repo>', 'Exact GitHub owner/repository name')
+    .requiredOption('--base <sha>', 'Exact 40-character lowercase base commit SHA')
+    .requiredOption('--head <sha>', 'Exact 40-character lowercase head commit SHA')
+    .requiredOption('--cases <file>', 'JSON file: the ordered ProductCase array (or { "cases": [...] })')
+    .requiredOption('--combinations <file>', 'JSON file: the combination space each case start resolves against')
+    .option('--base-world <id>', 'Existing frozen base world (frz_ plus 16 hex); omit to prepare it')
+    .option('--head-world <id>', 'Existing frozen head world (frz_ plus 16 hex); omit to prepare it')
+    .option('--max-concurrent <n>', 'Concurrency ceiling, 1-500 (default: the case count, capped at 500)')
+    .option('--per-case-wall-ms <ms>', 'Per-case wall budget, 1000-600000 (default 120000)')
+    .option('--total-budget-ms <ms>', 'Launch budget for the batch, 10000-1800000 (default 1800000)')
+    .option('--idempotency-key <key>', 'Stable retry key (default: deterministic from the whole submission)')
+    .option('--source-patch <file>', 'JSON file with the precompute-captured { cacheKey, patchSha256, patchGzBase64 }')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned machine-readable admission receipt')
+    .addHelpText('after', `
+Inputs travel inline and the whole request is bounded at 8 MiB. No source patch
+is sent unless --source-patch names one.
+
+--max-concurrent is a ceiling, not a reservation: admitted concurrency is the
+smaller of it and what the fleet's free capacity allows, and the batch's own
+receipt reports both. --per-case-wall-ms kills a case that overruns and records
+it as UNKNOWN/wall-budget rather than dropping it. --total-budget-ms bounds
+launches only; cases already launched run to their own wall budget.
+
+Example:
+  haystack case-batch submit --repository owner/repo --base <sha> --head <sha> \\
+    --cases cases.json --combinations space.json --max-concurrent 200 --json
+`)
+    .action(async (options) => {
+    const { caseBatchSubmitCommand } = await import('./commands/case-batch.js');
+    return runPublicCommand(() => caseBatchSubmitCommand(options), options.json);
 });
-verify
-    .command('sandboxes')
-    .description('E2B sandbox inventory with run attribution; --kill-stale reclaims superseded ones')
-    .option('--kill-stale', 'Kill verifier-attributed sandboxes superseded by newer runs (never unattributed ones)')
-    .option('--kill-run <runId>', 'Kill every sandbox attributed to one run')
-    .option('--server <url>', 'Control-plane URL, preferred over direct E2B access (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .option('--json', 'Machine-readable inventory')
-    .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifySandboxesCommand } = await import('./commands/verify-sandboxes.js');
-    return runPublicCommand(() => verifySandboxesCommand(options), options.json);
+caseBatch
+    .command('status')
+    .description('Read a case batch and every per-case outcome, optionally watching until terminal')
+    .argument('<run-id>', 'Case batch run id (cv_ followed by 48 lowercase hex characters)')
+    .requiredOption('--repository <owner/repo>', 'Exact GitHub owner/repository name')
+    .option('--watch', 'Keep polling until the batch is terminal or --max-wall expires')
+    .option('--interval <seconds>', 'Polling interval while watching, 1-300 (default 10)')
+    .option('--max-wall <minutes>', 'Maximum total polling wall, 1-240 (default 45)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned machine-readable snapshot with every per-case row')
+    .addHelpText('after', `
+Case rows are read with bounded pagination and the cursor is followed to the
+end of the list. A batch that ends incomplete still prints every per-case
+outcome; the command then exits 2 with a summary of what is missing. Exit 2
+also covers a cancelled batch, unproven cleanup, and a wait that hits
+--max-wall.
+
+Example:
+  haystack case-batch status cv_<48 hex> --repository owner/repo --watch --json
+`)
+    .action(async (runId, options) => {
+    const { caseBatchStatusCommand } = await import('./commands/case-batch.js');
+    return runPublicCommand(() => caseBatchStatusCommand(runId, options), options.json);
 });
-verify
-    .command('reseal')
-    .description('Rebuild a sealed specimen bundle (guarded) and restart the control plane onto it')
-    .argument('<specimen>', 'Specimen id, e.g. posthog-js-478')
-    .option('--source <dir>', 'Specimen source directory holding reseal.sh')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--repo-root <path>', 'Repository holding demo/cloud-verifier (default: walk up from cwd)')
-    .option('--no-restart', 'Only rebuild the bundle; leave the running server on the old checkout')
-    .action(async (specimen, _options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    const { verifyResealCommand } = await import('./commands/verify-reseal.js');
-    return runPublicCommand(() => verifyResealCommand(specimen, options));
+caseBatch
+    .command('cancel')
+    .description('Request cancellation of an owned case batch')
+    .argument('<run-id>', 'Case batch run id (cv_ followed by 48 lowercase hex characters)')
+    .requiredOption('--repository <owner/repo>', 'Exact GitHub owner/repository name')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned machine-readable cancellation receipt')
+    .addHelpText('after', `
+A claimed batch stays draining until its current owner proves physical VM
+cleanup and posts its terminal checkpoint.
+`)
+    .action(async (runId, options) => {
+    const { caseBatchCancelCommand } = await import('./commands/case-batch.js');
+    return runPublicCommand(() => caseBatchCancelCommand(runId, options), options.json);
 });
-verify
-    .command('mcp')
-    .description('Run a stdio MCP server exposing the verifier to agents (verify_start/verify_wait/…)')
-    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
-    .option('--token <token>', 'Bearer token for a control plane that requires auth (or HAYSTACK_VERIFY_TOKEN)')
-    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
-    .action(async (_options, cmd) => {
-    const options = cmd.optsWithGlobals();
-    try {
-        // Lazy import, same reasoning as the top-level `mcp` command: only this
-        // path needs @modelcontextprotocol/sdk.
-        const { runVerifyMcpServer } = await import('./commands/verify-mcp.js');
-        await runVerifyMcpServer(options);
-    }
-    catch (err) {
-        console.error(chalk.red('verify mcp server failed:'), err instanceof Error ? err.message : err);
-        process.exit(1);
-    }
+caseBatch
+    .command('bundle')
+    .description('Download a case batch replay bundle, verifying every artifact digest')
+    .argument('<run-id>', 'Case batch run id (cv_ followed by 48 lowercase hex characters)')
+    .requiredOption('--repository <owner/repo>', 'Exact GitHub owner/repository name')
+    .requiredOption('--out <dir>', 'Directory to write the verified bundle into')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned machine-readable list of verified artifacts')
+    .addHelpText('after', `
+The manifest is fetched first and checked against the digest the service sealed
+it under; that sealed digest is required, because the manifest is the one
+artifact with no parent digest to check it against. Every artifact the manifest
+lists (and every artifact those pages list) is then fetched and checked against
+the manifest's own sha256 and byte length before it is written. Any failure
+stops the command; it never writes unverified bytes.
+`)
+    .action(async (runId, options) => {
+    const { caseBatchBundleCommand } = await import('./commands/case-batch.js');
+    return runPublicCommand(() => caseBatchBundleCommand(runId, options), options.json);
 });
 program
     .command('login')
@@ -1285,12 +1165,14 @@ hooks
     .command('install-session')
     .description('Install session-start and Stop hooks for coding CLIs')
     .option('--cli <name>', 'Target CLI: claude, codex, gemini, or all')
+    .option('--shared', 'Write Claude Code hooks to the committed .claude/settings.json instead of settings.local.json')
     .addHelpText('after', `
 Configures your coding CLI to run \`haystack triage --hook\` on session start.
 This shows pending PR analysis results when you open a new terminal session.
 Claude Code also runs \`haystack verify precompute --hook\` when a session stops.
 
-  Claude Code:  Native SessionStart and Stop hooks (.claude/settings.json)
+  Claude Code:  Native SessionStart and Stop hooks (.claude/settings.local.json;
+                --shared writes the committed .claude/settings.json)
   Codex CLI:    AGENTS.md instructions
   Gemini CLI:   GEMINI.md instructions
 
@@ -1548,4 +1430,10 @@ program
 if (process.argv.length === 2) {
     program.help();
 }
-program.parse();
+await program.parseAsync();
+// Runs only after the command's action has settled; --version, --help and
+// commands that call process.exit never reach it. See src/utils/update-check.ts.
+{
+    const { notifyIfUpdateAvailable } = await import('./utils/update-check.js');
+    await notifyIfUpdateAvailable(getVersion());
+}