@haystackeditor/cli 0.15.29 → 0.15.31

package/dist/commands/verify-precompute.js

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { cpSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createGzip } from 'node:zlib';
 import { isAbsolute, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -9,11 +9,21 @@ import { NotLoggedInError, resolveAuthContext } from '../utils/auth.js';
 import { findGitRoot, parseRemoteUrl, resolveDiffBaseRef, } from '../utils/git.js';
 import { HaystackApiError, haystackJson } from '../utils/haystack-api.js';
 import { trackPrecomputeEvent } from '../utils/telemetry.js';
-const TOTAL_WALL_MS = 5_000;
+import { startPrecomputeDelivery } from './precompute-delivery.js';
+// --hook has five seconds to capture the exact source and publish local custody.
+// Its detached sender owns the bounded network delivery and acknowledgement.
+// An explicit invocation still waits synchronously for the server response.
+const HOOK_WALL_MS = 5_000;
+const EXPLICIT_WALL_MS = 60_000;
 const REMOTE_COMMAND_MS = 750;
-const COMMIT_SHA = /^[0-9a-f]{40}$/;
-const REPOSITORY_COMPONENT = /^[A-Za-z0-9_.-]{1,100}$/;
-const RUN_ID = /^cv_[0-9a-f]{48}$/;
+// The published CLI cannot import verifier/contracts outside its package root.
+const hasOnlyCharacters = (value, allowed) => value.length > 0
+    && [...value].every(character => allowed.includes(character));
+const isCommitSha = (value) => value.length === 40 && hasOnlyCharacters(value, '0123456789abcdef');
+const isRepositoryComponent = (value) => value.length <= 100
+    && hasOnlyCharacters(value, 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-');
+const isRunId = (value) => value.startsWith('cv_') && value.length === 51
+    && hasOnlyCharacters(value.slice(3), '0123456789abcdef');
 const FIXED_COMMIT_ENV = {
     GIT_AUTHOR_NAME: 'haystack-stop-hook',
     GIT_AUTHOR_EMAIL: 'stop-hook@haystack.invalid',
@@ -36,7 +46,7 @@ function remainingMs(deadline) {
     return remaining;
 }
 function gitOutput(args, gitRoot, deadline, options = {}) {
-    const timeout = Math.max(1, Math.min(remainingMs(deadline), options.timeoutCapMs ?? TOTAL_WALL_MS));
+    const timeout = Math.max(1, Math.min(remainingMs(deadline), options.timeoutCapMs ?? HOOK_WALL_MS));
     try {
         return execFileSync('git', args, {
             cwd: gitRoot,
@@ -53,8 +63,8 @@ function gitOutput(args, gitRoot, deadline, options = {}) {
 function resolveOriginRepository(gitRoot) {
     try {
         const remote = parseRemoteUrl('origin');
-        if (!REPOSITORY_COMPONENT.test(remote.owner)
-            || !REPOSITORY_COMPONENT.test(remote.repo)) {
+        if (!isRepositoryComponent(remote.owner)
+            || !isRepositoryComponent(remote.repo)) {
             throw new Error('invalid repository identity');
         }
         return { owner: remote.owner, repository: remote.repo };
@@ -74,15 +84,19 @@ function resolveOriginDefaultBranch(gitRoot, deadline) {
     catch {
         // A clone does not have to carry origin/HEAD; ask the remote below.
     }
-    const remoteSummary = gitOutput(['remote', 'show', 'origin'], gitRoot, deadline, {
+    const remoteRefs = gitOutput(['ls-remote', '--symref', 'origin', 'HEAD'], gitRoot, deadline, {
         env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
         timeoutCapMs: REMOTE_COMMAND_MS,
     });
-    const match = remoteSummary.match(/^\s*HEAD branch:\s*(\S+)\s*$/m);
-    if (!match) {
+    const prefix = 'ref: refs/heads/';
+    const heads = remoteRefs.split('\n').map(line => line.split('\t'))
+        .filter(fields => fields.length === 2 && fields[1] === 'HEAD' && fields[0].startsWith(prefix))
+        .map(fields => fields[0].slice(prefix.length));
+    if (heads.length !== 1 || heads[0].length === 0) {
         throw new PrecomputeFailure('Could not resolve the origin default branch.');
     }
-    return match[1];
+    gitOutput(['check-ref-format', `refs/heads/${heads[0]}`], gitRoot, deadline);
+    return heads[0];
 }
 function deriveBaseSha(gitRoot, deadline) {
     const defaultBranch = resolveOriginDefaultBranch(gitRoot, deadline);
@@ -91,7 +105,7 @@ function deriveBaseSha(gitRoot, deadline) {
         timeoutMs: Math.max(1, Math.min(remainingMs(deadline), REMOTE_COMMAND_MS)),
     });
     const baseSha = gitOutput(['merge-base', 'HEAD', baseRef], gitRoot, deadline);
-    if (!COMMIT_SHA.test(baseSha)) {
+    if (!isCommitSha(baseSha)) {
         throw new PrecomputeFailure('Could not derive the base commit.');
     }
     return baseSha;
@@ -115,7 +129,7 @@ function deriveWorktreeTreeSha(gitRoot, deadline) {
         }
         gitOutput(['add', '-A'], gitRoot, deadline, { env: indexEnv });
         const treeSha = gitOutput(['write-tree'], gitRoot, deadline, { env: indexEnv });
-        if (!COMMIT_SHA.test(treeSha)) {
+        if (!isCommitSha(treeSha)) {
             throw new PrecomputeFailure('Could not derive the working-tree snapshot.');
         }
         return treeSha;
@@ -127,14 +141,14 @@ function deriveWorktreeTreeSha(gitRoot, deadline) {
 function deriveWorkCommit(gitRoot, baseSha, treeSha, deadline) {
     const headSha = gitOutput(['rev-parse', 'HEAD'], gitRoot, deadline);
     const headTreeSha = gitOutput(['rev-parse', 'HEAD^{tree}'], gitRoot, deadline);
-    if (!COMMIT_SHA.test(headSha) || !COMMIT_SHA.test(headTreeSha)) {
+    if (!isCommitSha(headSha) || !isCommitSha(headTreeSha)) {
         throw new PrecomputeFailure('Could not resolve the current commit.');
     }
     // A clean checkout of the base already has the exact required identity.
     if (baseSha === headSha && treeSha === headTreeSha)
         return headSha;
     const workCommit = gitOutput(['commit-tree', treeSha, '-p', baseSha, '-m', 'front-half-snapshot'], gitRoot, deadline, { env: { ...process.env, ...FIXED_COMMIT_ENV } });
-    if (!COMMIT_SHA.test(workCommit)) {
+    if (!isCommitSha(workCommit)) {
         throw new PrecomputeFailure('Could not derive the working commit.');
     }
     return workCommit;
@@ -202,7 +216,10 @@ async function buildCompressedPatch(gitRoot, baseSha, workCommit, deadline) {
         child.stdout.pipe(gzip);
     });
 }
-export async function derivePrecomputeRequest(gitRoot, owner, repository, deadline = Date.now() + TOTAL_WALL_MS) {
+export async function derivePrecomputeRequest(gitRoot, owner, repository, deadline = Date.now() + HOOK_WALL_MS) {
+    // Capture this before git and compression work so delivery latency cannot
+    // make an older stop look newer than a later one.
+    const observedAt = Date.now();
     const baseSha = deriveBaseSha(gitRoot, deadline);
     const treeSha = deriveWorktreeTreeSha(gitRoot, deadline);
     const workCommit = deriveWorkCommit(gitRoot, baseSha, treeSha, deadline);
@@ -221,6 +238,7 @@ export async function derivePrecomputeRequest(gitRoot, owner, repository, deadli
             repository,
             baseCommit: baseSha,
             workCommit,
+            observedAt,
             cacheKey,
             patchGzBase64: patchGzip.toString('base64'),
             patchSha256: createHash('sha256').update(patchGzip).digest('hex'),
@@ -231,16 +249,75 @@ function precomputeResult(response) {
     if (!response || typeof response !== 'object' || Array.isArray(response)) {
         throw new PrecomputeFailure('The precompute service returned an invalid response.');
     }
-    const { status, runId } = response;
-    if (status === 'queued' && typeof runId === 'string' && RUN_ID.test(runId)) {
-        return { outcome: 'enqueued', runId };
+    const { status, runId, walker: rawWalker } = response;
+    const walker = rawWalker === undefined ? undefined : readWalkerStatus(rawWalker);
+    if (status === 'queued' && typeof runId === 'string' && isRunId(runId)) {
+        return { outcome: 'enqueued', runId, ...(walker === undefined ? {} : { walker }) };
     }
     if (status === 'cached')
-        return { outcome: 'cached' };
+        return { outcome: 'cached', ...(walker === undefined ? {} : { walker }) };
     if (status === 'existing')
-        return { outcome: 'existing' };
+        return { outcome: 'existing', ...(walker === undefined ? {} : { walker }) };
     throw new PrecomputeFailure('The precompute service returned an invalid response.');
 }
+/** One authenticated submission of the already captured request. No source reads or retries. */
+export const deliverPrecomputeRequest = async (request, signal) => {
+    signal.throwIfAborted();
+    const auth = await resolveAuthContext({ owner: request.owner, repo: request.repository });
+    signal.throwIfAborted();
+    return precomputeResult(await haystackJson('/api/agent/cloud-verifier/front-half', auth.token, { method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(request), signal }));
+};
+function readWalkerStatus(value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const record = value;
+        if (Object.keys(record).length === 2) {
+            if ((record.status === 'queued' || record.status === 'existing')
+                && typeof record.runId === 'string' && isRunId(record.runId))
+                return { status: record.status, runId: record.runId };
+            if (record.status === 'unavailable'
+                && (record.reason === 'runner-unavailable' || record.reason === 'enqueue-failed'))
+                return { status: record.status, reason: record.reason };
+        }
+    }
+    throw new PrecomputeFailure('The precompute service returned an invalid walker status.');
+}
+function walkerMetadataDirectory(gitRoot, deadline) {
+    const common = gitOutput(['rev-parse', '--git-common-dir'], gitRoot, deadline);
+    return join(isAbsolute(common) ? common : resolve(gitRoot, common), 'haystack');
+}
+function saveWalkerStatus(directory, request, walker) {
+    // Frozen local snapshot shape: {observedAt, repository, sourceCommit, walker}.
+    // Git's common metadata directory is shared by linked worktrees and excluded
+    // from the synthetic source tree. Rename publishes one complete JSON record.
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    if (!lstatSync(directory).isDirectory())
+        throw new PrecomputeFailure('Could not save the walker status.');
+    const temporary = join(directory, `.walker-status-${randomUUID()}.tmp`);
+    const descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+    try {
+        try {
+            writeFileSync(descriptor, JSON.stringify({ observedAt: new Date(request.observedAt).toISOString(),
+                repository: `${request.owner}/${request.repository}`.toLowerCase(), sourceCommit: request.workCommit,
+                walker: readWalkerStatus(walker) }) + '\n');
+            fsyncSync(descriptor);
+        }
+        finally {
+            closeSync(descriptor);
+        }
+        renameSync(temporary, join(directory, 'walker-status.json'));
+        const parent = openSync(directory, constants.O_RDONLY);
+        try {
+            fsyncSync(parent);
+        }
+        finally {
+            closeSync(parent);
+        }
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
 function normalModeFailure(error) {
     if (error instanceof PrecomputeFailure)
         return error;
@@ -256,9 +333,14 @@ function normalModeFailure(error) {
         }
         return new PrecomputeFailure(`The precompute request failed (HTTP ${error.status}).`);
     }
+    // The deadline fired while the POST was in flight. The server may still
+    // have accepted the job, so say what happened rather than "failed".
+    if (error instanceof Error && error.name === 'AbortError') {
+        return new PrecomputeFailure('Precompute timed out.');
+    }
     return new PrecomputeFailure('The precompute request failed.');
 }
-function printResult(outcome, runId) {
+function printResult(outcome, runId, walker) {
     if (outcome === 'enqueued') {
         console.log(chalk.green(`Precompute request queued${runId ? ` (${runId})` : ''}.`));
     }
@@ -268,18 +350,36 @@ function printResult(outcome, runId) {
     else if (outcome === 'existing') {
         console.log(chalk.green('A matching precompute request already exists.'));
     }
+    if (walker?.status === 'queued')
+        console.log(`Walker queued (${walker.runId}).`);
+    else if (walker?.status === 'existing')
+        console.log(`A matching walker run already exists (${walker.runId}).`);
+    else if (walker?.status === 'unavailable')
+        console.log(walker.reason === 'runner-unavailable'
+            ? 'Walker unavailable: no runner is available for this repository.'
+            : 'Walker unavailable: the enqueue request failed.');
+    else
+        console.log('Walker status was not reported by the service.');
 }
 export async function verifyPrecomputeCommand(options) {
     const startedAt = Date.now();
-    const deadline = startedAt + TOTAL_WALL_MS;
+    const totalWallMs = options.hook ? HOOK_WALL_MS : EXPLICIT_WALL_MS;
+    const deadline = startedAt + totalWallMs;
     let outcome = 'error';
     try {
         const gitRoot = findGitRoot();
         if (!gitRoot) {
             throw new PrecomputeFailure('Run this command from a git repository.');
         }
+        const metadataDirectory = walkerMetadataDirectory(gitRoot, deadline);
         const repository = resolveOriginRepository(gitRoot);
         const derivation = await derivePrecomputeRequest(gitRoot, repository.owner, repository.repository, deadline);
+        if (options.hook) {
+            remainingMs(deadline);
+            await startPrecomputeDelivery(metadataDirectory, derivation.request);
+            outcome = 'pending';
+            return;
+        }
         let token;
         try {
             const auth = await resolveAuthContext({
@@ -312,8 +412,16 @@ export async function verifyPrecomputeCommand(options) {
         }
         const result = precomputeResult(response);
         outcome = result.outcome;
+        if (result.walker) {
+            try {
+                saveWalkerStatus(metadataDirectory, derivation.request, result.walker);
+            }
+            catch {
+                throw new PrecomputeFailure('Precompute response received, but its walker status could not be saved.');
+            }
+        }
         if (!options.hook)
-            printResult(outcome, result.runId);
+            printResult(outcome, result.runId, result.walker);
     }
     catch (error) {
         if (!options.hook)
@@ -321,7 +429,7 @@ export async function verifyPrecomputeCommand(options) {
     }
     finally {
         const wallMs = Date.now() - startedAt;
-        trackPrecomputeEvent(outcome, wallMs, Math.max(1, TOTAL_WALL_MS - wallMs));
+        trackPrecomputeEvent(outcome, wallMs, options.hook ? 1 : Math.max(1, totalWallMs - wallMs));
         if (options.hook)
             process.exitCode = 0;
     }

package/dist/commands/verify.d.ts

@@ -6,6 +6,12 @@ export interface VerifyOptions {
     base?: string;
     head?: string;
     intentTranscript?: string;
+    intentFile?: string;
+    idempotencyKey?: string;
+    account?: string;
+    wait?: boolean;
+    interval?: string;
+    timeout?: string;
     json?: boolean;
     open?: boolean;
     /** Internal reproducibility option: execute an already-frozen plan. */

package/dist/commands/verify.js

@@ -107,6 +107,28 @@ export async function startVerificationRun(specimenArg, options) {
     return parseStartRunResponse(raw);
 }
 export async function verifyCommand(specimenArg, options) {
+    if (specimenArg === undefined && (options.repo !== undefined || options.base !== undefined || options.head !== undefined)) {
+        if (!options.repo || !options.base || !options.head) {
+            throw new Error('Repository verification requires --repo owner/repo, --base <ref>, and --head <ref>.');
+        }
+        if (options.intentTranscript !== undefined) {
+            throw new Error('Repository verification accepts optional --intent-file JSON with problem, goal, and intended_outcomes.');
+        }
+        const { verifyHostedStartCommand } = await import('./verify-hosted.js');
+        await verifyHostedStartCommand(options.repo, {
+            provider: 'haystack',
+            base: options.base,
+            head: options.head,
+            intentFile: options.intentFile,
+            idempotencyKey: options.idempotencyKey,
+            account: options.account,
+            wait: options.wait,
+            interval: options.interval,
+            timeout: options.timeout,
+            json: options.json,
+        });
+        return;
+    }
     if (!options.json) {
         console.error(chalk.dim('Preparing the cloud verification run…'));
     }

package/dist/index.js

@@ -174,24 +174,35 @@ 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('--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')
+    .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('--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 id, status, and results URL')
+    .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)
 
-The local control plane must be running. From the Haystack repository:
+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
 
 Examples:
+  haystack verify --repo owner/repo --base main --head feature --json
+  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
@@ -210,6 +221,26 @@ Examples:
 `)
     .action((specimen, options) => runPublicCommand(() => verifyCommand(specimen, options), options.json));
 const verifyRunArg = 'Run id, chapter id (newest run of that chapter), or "latest" (default)';
+verify
+    .command('history')
+    .description('Read your recent finished hosted verification runs without starting a run')
+    .argument('<repository>', 'Exact GitHub owner/repository name')
+    .option('--limit <runs>', 'Number of recent finished runs to show, from 1 to 100 (default 20)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'Versioned history with execution health and separate bug counts')
+    .addHelpText('after', `
+History covers your hosted fleet runs for this repository. Reliability counts
+only these returned runs; it does not measure whether the code is bug-free.
+
+Examples:
+  haystack verify history owner/repo
+  haystack verify history owner/repo --limit 50 --account my-login --json
+`)
+    .action(async (repository, _options, cmd) => {
+    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const { verifyHistoryCommand } = await import('./commands/verify-history.js');
+    return runPublicCommand(() => verifyHistoryCommand(repository, options), options.json);
+});
 verify
     .command('precompute')
     .description('Precompute reusable verification inputs for the current working tree')
@@ -235,7 +266,7 @@ hostedVerify
     // 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')
-    .requiredOption('--intent-file <path>', 'Agent-supplied JSON with exactly problem, goal, and intended_outcomes')
+    .option('--intent-file <path>', 'Required for this alias: 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')
@@ -284,7 +315,7 @@ hostedVerify
     .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')
-    .requiredOption('--intent-file <path>', 'Agent-supplied JSON reused for every hosted run in the series')
+    .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('--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')
@@ -365,6 +396,34 @@ verify
     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 { verifyCasesCommand } = await import('./commands/verify-explore.js');
+    return runPublicCommand(() => verifyCasesCommand(run, options), options.json);
+});
+verify
+    .command('explore <run> <case-id>')
+    .description('Open or use your own copy of a saved fleet case; never changes the verification original')
+    .option('--repo <owner/repo>', 'Required exact GitHub repository; uses your Haystack login')
+    .option('--side <side>', 'base or head (default head)')
+    .option('--exec-json <argv>', 'Command arguments as a JSON array, executed inside your working sandbox')
+    .option('--cwd <path>', 'Absolute guest directory (default /home/user/pj)')
+    .option('--command-timeout <seconds>', 'Command timeout, 1–300 seconds (default 60)')
+    .option('--close', 'Discard your working copy; leave the saved case unchanged')
+    .option('--action <id>', 'Read/follow an existing action without submitting another command')
+    .option('--request-id <uuid>', 'Idempotency ID for a new request; reuse only with identical arguments')
+    .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 { 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')
@@ -863,6 +922,8 @@ program
     // keeps retired auto-fix/verification wording out of the CLI surface).
     .description('Run a blind design-by-execution review of a PR')
     .option('--json', 'Machine-readable output')
+    .option('--history', 'Show recent execution reliability for this repository without starting a run')
+    .option('--limit <attempts>', 'Maximum recorded terminal attempts to show with --history (1–100, default 20)')
     .option('--no-wait', 'Return after the run is admitted instead of waiting for its verdict')
     .option('--run <run-id>', 'Resume and wait for an existing exact run id')
     .option('--poll-interval <seconds>', 'Status polling interval', '3')
@@ -883,6 +944,11 @@ outside the registered intent.
 The command waits for a behavioral verdict by default. Use --no-wait to
 return the run id immediately, or --run <run-id> to resume waiting.
 
+Read recent execution reliability across this repository's PRs:
+  haystack design-verify owner/repo#123 --history --limit 20
+History covers recorded terminal attempts, including partial or failed runs;
+it does not measure bug-detection accuracy or whether changes are bug-free.
+
 After a completed run, inspect or replay one retained case universe without
 receiving provider credentials:
   haystack design-verify owner/repo#123 --run RUN --case case-00001 --universe before --replay

package/dist/types/verify-history.d.ts

@@ -0,0 +1,38 @@
+/** Read-only history from the active hosted verifier, scoped to the caller's
+ * stable GitHub user and repository IDs. Counts describe the returned window,
+ * never bug correctness. Missing results remain unknown. */
+export type VerifyHistoryHealth = 'healthy' | 'degraded' | 'infrastructure-error' | 'not-executed' | 'unknown';
+export interface VerifyHistoryRun {
+    runId: string;
+    baseCommit: string;
+    headCommit: string;
+    createdAt: string;
+    completedAt: string;
+    status: 'complete' | 'errored';
+    lifecycle: 'complete' | 'failed' | 'cancelled' | 'budget-stopped' | 'account-action' | null;
+    health: VerifyHistoryHealth;
+    regressionCount: number | null;
+    executedCaseCount: number | null;
+    degradationCodes: string[];
+    supersededBy: string | null;
+}
+export interface VerifyHistoryReport {
+    version: 'dv-verify-history-v1';
+    provider: 'haystack';
+    scope: 'user';
+    repository: {
+        owner: string;
+        name: string;
+        repositoryId: string;
+    };
+    limit: number;
+    hasMore: boolean;
+    runs: VerifyHistoryRun[];
+    summary: {
+        total: number;
+        counts: Record<VerifyHistoryHealth, number>;
+        /** Healthy/degraded runs with executedCaseCount > 0, divided by total;
+         * null for an empty window. */
+        usableRate: number | null;
+    };
+}

package/dist/types/verify-history.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/design-verifier-api.d.ts

@@ -7,6 +7,7 @@
  * the server-side shared secret. This client just POSTs and interprets the
  * response.
  */
+import { type DesignVerifierHistoryReport } from './design-verifier-history.js';
 export type DesignVerifierTriggerResult = {
     status: 'started' | 'queued' | 'duplicate';
     runId: string;
@@ -184,6 +185,13 @@ export declare function waitForDesignVerifierUniverseAction(owner: string, repo:
 }>;
 export declare function triggerDesignVerifier(owner: string, repo: string, prNumber: number, token: string): Promise<DesignVerifierTriggerResult>;
 export declare function getDesignVerifierStatus(owner: string, repo: string, prNumber: number, runId: string, token: string): Promise<DesignVerifierStatusFetchResult>;
+export declare function getDesignVerifierHistory(owner: string, repo: string, token: string, limit?: number): Promise<{
+    status: 'ok';
+    history: DesignVerifierHistoryReport;
+} | {
+    status: 'denied' | 'unavailable' | 'error';
+    message: string;
+}>;
 export declare function waitForDesignVerifier(owner: string, repo: string, prNumber: number, runId: string, token: string, options?: {
     intervalMs?: number;
     timeoutMs?: number;

package/dist/utils/design-verifier-api.js

@@ -8,6 +8,7 @@
  * response.
  */
 import { haystackApiUrl } from './haystack-api.js';
+import { isDesignVerifierHistoryReport } from './design-verifier-history.js';
 function isDuration(value) {
     return value === null || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
 }
@@ -239,6 +240,28 @@ export async function getDesignVerifierStatus(owner, repo, prNumber, runId, toke
         return { status: 'unavailable', message };
     return { status: 'error', message };
 }
+export async function getDesignVerifierHistory(owner, repo, token, limit = 20) {
+    const url = haystackApiUrl(`/api/design-verifier/history/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}?limit=${limit}`);
+    try {
+        const response = await fetch(url, { method: 'GET', headers: apiHeaders(token) });
+        const data = await response.json();
+        if (response.ok) {
+            if (!isDesignVerifierHistoryReport(data, { owner, repo, limit })) {
+                return { status: 'error', message: 'History endpoint returned an invalid or mismatched result.' };
+            }
+            return { status: 'ok', history: data };
+        }
+        const message = data?.message || data?.error || `HTTP ${response.status}`;
+        if (response.status === 401 || response.status === 403)
+            return { status: 'denied', message };
+        if ([404, 502, 503].includes(response.status))
+            return { status: 'unavailable', message };
+        return { status: 'error', message };
+    }
+    catch (error) {
+        return { status: 'error', message: error.message };
+    }
+}
 export async function waitForDesignVerifier(owner, repo, prNumber, runId, token, options = {}) {
     const intervalMs = options.intervalMs ?? 3000;
     const timeoutMs = options.timeoutMs ?? 2 * 60 * 60 * 1000;

package/dist/utils/design-verifier-history.d.ts

@@ -0,0 +1,46 @@
+/** FIXED CONTRACT: historical execution health, never a score for bug-detection accuracy. */
+export type DesignVerifierHistoryOutcome = 'healthy' | 'degraded' | 'invalid' | 'failed' | 'unknown';
+export interface DesignVerifierHistoryRun {
+    runId: string;
+    pr: number;
+    baseSha: string | null;
+    headSha: string | null;
+    createdAt: string;
+    finishedAt: string | null;
+    status: string;
+    outcome: DesignVerifierHistoryOutcome;
+    admitted: number | null;
+    losses: Array<{
+        code: string;
+        owner: string;
+        impact: 'degraded' | 'invalid';
+        count: number;
+    }>;
+}
+export interface DesignVerifierHistoryReport {
+    version: 'dv-cli-history-v1';
+    owner: string;
+    repo: string;
+    retentionDays: number;
+    limit: number;
+    runs: DesignVerifierHistoryRun[];
+    summary: {
+        total: number;
+        healthy: number;
+        degraded: number;
+        invalid: number;
+        failed: number;
+        unknown: number;
+        usableRate: number | null;
+        topBlockers: Array<{
+            code: string;
+            affectedRuns: number;
+        }>;
+    };
+}
+export declare function isDesignVerifierHistoryReport(value: unknown, expected: {
+    owner: string;
+    repo: string;
+    limit: number;
+}): value is DesignVerifierHistoryReport;
+export declare function formatDesignVerifierHistory(report: DesignVerifierHistoryReport): string;