@haystackeditor/cli 0.15.20 → 0.15.22

package/dist/commands/verify.js

@@ -0,0 +1,130 @@
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { setVerifyToken, verifyAuthHeaders } from './verify-core.js';
+const DEFAULT_CONTROL_PLANE = 'http://127.0.0.1:3000';
+export const VERIFY_SPECIMENS = new Set(['all', 'posthog-js-478', 'analytics-js-255']);
+export function parseStartRunResponse(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Verifier returned an invalid JSON response.');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Verifier returned an invalid response object.');
+    }
+    const response = parsed;
+    const requiredString = (field) => {
+        const value = response[field];
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new Error(`Verifier response is missing a valid ${field}.`);
+        }
+        return value;
+    };
+    return {
+        runId: requiredString('runId'),
+        status: requiredString('status'),
+        resultsUrl: requiredString('resultsUrl'),
+    };
+}
+export function verifierErrorReason(raw, contentType) {
+    if (!contentType?.toLowerCase().includes('application/json'))
+        return raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return `malformed JSON error response (${error instanceof Error ? error.message : String(error)}); raw body: ${raw}`;
+    }
+    if (parsed
+        && typeof parsed === 'object'
+        && !Array.isArray(parsed)
+        && typeof parsed.error === 'string'
+        && parsed.error.trim() !== '') {
+        return parsed.error;
+    }
+    return `JSON error response omitted a string error; raw body: ${raw}`;
+}
+function openResults(url) {
+    const platform = process.platform;
+    const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+async function readIntentTranscript(path) {
+    if (!path)
+        return undefined;
+    const absolutePath = resolve(path);
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read intent transcript at ${absolutePath}: ${message}`);
+    }
+}
+export async function startVerificationRun(specimenArg, options) {
+    const specimen = specimenArg || 'all';
+    if (!VERIFY_SPECIMENS.has(specimen)) {
+        throw new Error(`Unknown or unreproduced specimen "${specimen}". Choose all, posthog-js-478, or analytics-js-255.`);
+    }
+    setVerifyToken(options.token);
+    const server = (options.server || process.env.HAYSTACK_VERIFY_SERVER || DEFAULT_CONTROL_PLANE)
+        .replace(/\/+$/, '');
+    const intentTranscript = await readIntentTranscript(options.intentTranscript);
+    let response;
+    try {
+        response = await fetch(`${server}/api/cloud-verifier/runs`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...verifyAuthHeaders() },
+            body: JSON.stringify({
+                specimen,
+                repoPath: options.repo ? resolve(options.repo) : undefined,
+                baseRef: options.base,
+                headRef: options.head,
+                intentTranscript,
+                planSourceRunId: options.planSourceRunId,
+            }),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not reach the Haystack verifier at ${server}. Start the demo control plane with \`pnpm dev\` and retry. ${message}`);
+    }
+    const raw = await response.text();
+    if (response.status === 401) {
+        throw new Error(`Control plane at ${server} requires a token (HTTP 401). Pass --token or set HAYSTACK_VERIFY_TOKEN.`);
+    }
+    if (!response.ok) {
+        const reason = verifierErrorReason(raw, response.headers.get('content-type'));
+        throw new Error(`Verifier rejected the run (${response.status}): ${reason}`);
+    }
+    return parseStartRunResponse(raw);
+}
+export async function verifyCommand(specimenArg, options) {
+    if (!options.json) {
+        console.error(chalk.dim('Preparing the cloud verification run…'));
+    }
+    const started = await startVerificationRun(specimenArg, options);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({
+            schema_version: '1.0.0',
+            run_id: started.runId,
+            status: started.status,
+            results_url: started.resultsUrl,
+        }, null, 2)}\n`);
+    }
+    else {
+        console.log('');
+        console.log(`${chalk.green('✓')} Verification started: ${chalk.bold(started.runId)}`);
+        console.log(`  ${chalk.dim('Results:')} ${chalk.cyan(started.resultsUrl)}`);
+    }
+    if (options.open !== false) {
+        openResults(started.resultsUrl);
+    }
+}

package/dist/index.js

@@ -48,6 +48,7 @@ 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';
 // `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
@@ -164,6 +165,331 @@ program
     .command('status')
     .description('Check if .haystack.json exists and is valid')
     .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 <path>', 'Repository to analyze (defaults to the selected launch specimen)')
+    .option('--base <ref>', 'Base revision for a repository run')
+    .option('--head <ref>', 'Head revision for a repository run')
+    .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 id, status, and results URL')
+    .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)
+
+The local control plane must be running. From the Haystack repository:
+  pnpm dev
+
+Examples:
+  haystack verify hosted start owner/repo --base <sha> --head <sha>
+  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
+`)
+    .action((specimen, options) => runPublicCommand(() => verifyCommand(specimen, options), options.json));
+const verifyRunArg = 'Run id, chapter id (newest run of that chapter), or "latest" (default)';
+const hostedVerify = verify
+    .command('hosted')
+    .description('Run the production Cloud Verifier against exact GitHub commits');
+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.
+    // 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('--idempotency-key <key>', 'Stable retry key (default: deterministic from repository and commits)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--no-wait', 'Return after the production workflow 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')
+    .addHelpText('after', `
+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.
+
+Examples:
+  haystack verify hosted start owner/repo --base <sha> --head <sha>
+  haystack verify hosted start owner/repo --base <sha> --head <sha> --no-wait --json
+`)
+    .action(async (repository, _options, cmd) => {
+    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const { verifyHostedStartCommand } = await import('./commands/verify-hosted.js');
+    return runPublicCommand(() => verifyHostedStartCommand(repository, options), options.json);
+});
+hostedVerify
+    .command('status')
+    .description('Read an owned production verification, optionally waiting until terminal')
+    .argument('<run-id>', 'Hosted run id (cv_ followed by 48 lowercase hex characters)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--wait', 'Keep polling until the run reaches a terminal status')
+    .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')
+    .addHelpText('after', `
+Example:
+  haystack verify hosted status cv_<48 lowercase hex characters> --wait --json
+`)
+    .action(async (runId, _options, cmd) => {
+    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const { verifyHostedStatusCommand } = await import('./commands/verify-hosted.js');
+    return runPublicCommand(() => verifyHostedStatusCommand(runId, options), options.json);
+});
+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('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);
+});
+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);
+});
+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);
+});
+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));
+});
+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);
+    }
+});
 program
     .command('login')
     .description('Add or refresh a saved GitHub account (use --headless for CI tokens)')

package/dist/schema.d.ts

@@ -19,6 +19,7 @@ export declare const SCHEMA_VERSIONS: {
     readonly traces: "1.0.0";
     readonly submit: "1.0.0";
     readonly action: "1.0.0";
+    readonly 'cloud-verifier': "1.0.0";
     readonly error: "1.0.0";
 };
 export type SchemaName = keyof typeof SCHEMA_VERSIONS;

package/dist/schema.js

@@ -19,6 +19,7 @@ export const SCHEMA_VERSIONS = {
     traces: '1.0.0',
     submit: '1.0.0',
     action: '1.0.0',
+    'cloud-verifier': '1.0.0',
     error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/types.d.ts

@@ -719,11 +719,52 @@ declare const TriageConfigSchema: z.ZodObject<{
     maxTurns?: Partial<Record<"code-review" | "rules-validator" | "intent-drift", number>> | undefined;
     timeoutMs?: number | undefined;
 }>;
+declare const PreferencesSchema: z.ZodObject<{
+    /** Run analysis automatically for PR webhook events (default: true) */
+    automatic_analysis: z.ZodOptional<z.ZodBoolean>;
+    /** Enable sandbox-backed verification for this repository */
+    sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+    /** Enroll submitted PRs in auto-merge by default */
+    auto_merge: z.ZodOptional<z.ZodBoolean>;
+    /** Allow Haystack to attempt automatic fixes */
+    auto_fix: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    automatic_analysis?: boolean | undefined;
+    sandbox_enabled?: boolean | undefined;
+    auto_merge?: boolean | undefined;
+    auto_fix?: boolean | undefined;
+}, {
+    automatic_analysis?: boolean | undefined;
+    sandbox_enabled?: boolean | undefined;
+    auto_merge?: boolean | undefined;
+    auto_fix?: boolean | undefined;
+}>;
 export declare const HaystackConfigSchema: z.ZodObject<{
     /** Config version (must be "1") */
     version: z.ZodLiteral<"1">;
     /** Project name (for display) */
     name: z.ZodOptional<z.ZodString>;
+    /** Repository-level Haystack behavior */
+    preferences: z.ZodOptional<z.ZodObject<{
+        /** Run analysis automatically for PR webhook events (default: true) */
+        automatic_analysis: z.ZodOptional<z.ZodBoolean>;
+        /** Enable sandbox-backed verification for this repository */
+        sandbox_enabled: z.ZodOptional<z.ZodBoolean>;
+        /** Enroll submitted PRs in auto-merge by default */
+        auto_merge: z.ZodOptional<z.ZodBoolean>;
+        /** Allow Haystack to attempt automatic fixes */
+        auto_fix: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    }, {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    }>>;
     /** Package manager override (auto-detected if not specified) */
     package_manager: z.ZodOptional<z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>>;
     /** Development server configuration */
@@ -1315,6 +1356,12 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         root?: string | undefined;
         depends_on?: string[] | undefined;
     }> | undefined;
+    preferences?: {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    } | undefined;
     package_manager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     dev_server?: {
         command: string;
@@ -1442,6 +1489,12 @@ export declare const HaystackConfigSchema: z.ZodObject<{
         root?: string | undefined;
         depends_on?: string[] | undefined;
     }> | undefined;
+    preferences?: {
+        automatic_analysis?: boolean | undefined;
+        sandbox_enabled?: boolean | undefined;
+        auto_merge?: boolean | undefined;
+        auto_fix?: boolean | undefined;
+    } | undefined;
     package_manager?: "npm" | "pnpm" | "yarn" | "bun" | undefined;
     dev_server?: {
         command: string;
@@ -1559,6 +1612,7 @@ export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
 export type SecretDeclaration = z.infer<typeof SecretDeclarationSchema>;
 export type MergeQueueConfig = z.infer<typeof MergeQueueConfigSchema>;
 export type TriageConfig = z.infer<typeof TriageConfigSchema>;
+export type Preferences = z.infer<typeof PreferencesSchema>;
 /**
  * Project detection results
  */

package/dist/types.js

@@ -280,6 +280,19 @@ const TriageConfigSchema = z.object({
     timeoutMs: z.number().int().positive().optional(),
 });
 // =============================================================================
+// REPOSITORY PREFERENCES
+// =============================================================================
+const PreferencesSchema = z.object({
+    /** Run analysis automatically for PR webhook events (default: true) */
+    automatic_analysis: z.boolean().optional(),
+    /** Enable sandbox-backed verification for this repository */
+    sandbox_enabled: z.boolean().optional(),
+    /** Enroll submitted PRs in auto-merge by default */
+    auto_merge: z.boolean().optional(),
+    /** Allow Haystack to attempt automatic fixes */
+    auto_fix: z.boolean().optional(),
+});
+// =============================================================================
 // MAIN CONFIG
 // =============================================================================
 export const HaystackConfigSchema = z.object({
@@ -287,6 +300,8 @@ export const HaystackConfigSchema = z.object({
     version: z.literal('1'),
     /** Project name (for display) */
     name: z.string().optional(),
+    /** Repository-level Haystack behavior */
+    preferences: PreferencesSchema.optional(),
     /** Package manager override (auto-detected if not specified) */
     package_manager: z.enum(['npm', 'pnpm', 'yarn', 'bun']).optional(),
     /** Development server configuration */

package/dist/utils/haystack-api.d.ts

@@ -27,7 +27,7 @@ export declare class HaystackApiError extends Error {
  * class it failed with, and the next command to run.
  */
 export declare function classifyHttpError(response: Response, context: string): Promise<HaystackApiError>;
-export declare function haystackJson<T>(path: string, token: string, init?: RequestInit): Promise<T>;
+export declare function haystackJson<T>(path: string, token: string, init?: RequestInit, acceptedStatuses?: readonly number[]): Promise<T>;
 export declare function fetchCliIdentity(token: string): Promise<CliIdentity>;
 export declare function fetchHaystackInstallations(token: string): Promise<UserInstallation[]>;
 export declare function fetchGitHubJson<T>(path: string, token: string, init?: RequestInit): Promise<T>;

package/dist/utils/haystack-api.js

@@ -69,12 +69,12 @@ export async function classifyHttpError(response, context) {
     }
     return new HaystackApiError(response.status, `${context}: unexpected response (HTTP ${response.status})${suffix}.`);
 }
-export async function haystackJson(path, token, init = {}) {
+export async function haystackJson(path, token, init = {}, acceptedStatuses = []) {
     const response = await fetch(`${HAYSTACK_API_BASE}${path}`, {
         ...init,
         headers: headers(token, init.headers),
     });
-    if (!response.ok) {
+    if (!response.ok && !acceptedStatuses.includes(response.status)) {
         throw await classifyHttpError(response, `Haystack API ${path}`);
     }
     return response.json();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.15.20",
+  "version": "0.15.22",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {
-    "haystack": "./dist/index.js"
+    "haystack": "dist/index.js"
   },
   "scripts": {
     "build": "rm -rf dist && tsc && cp -r src/assets dist/assets",