@haystackeditor/cli 0.15.28 → 0.15.30

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,22 +141,22 @@ 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;
 }
 function slimInputHash() {
-    // Mirrors printf '%s\0%s\0%s\0%s\0' slim codex-harness none none.
+    // Mirrors printf '%s\0%s\0%s\0%s\0' slim agent-deferred none none.
     return createHash('sha256')
-        .update(Buffer.from('slim\0codex-harness\0none\0none\0'))
+        .update(Buffer.from('slim\0agent-deferred\0none\0none\0'))
         .digest('hex');
 }
 async function buildCompressedPatch(gitRoot, baseSha, workCommit, deadline) {
@@ -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,25 +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 hosted start owner/repo --base <sha> --head <sha>
+  haystack verify --repo owner/repo --base main --head feature --json
+  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)
@@ -235,6 +245,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')
+    .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')
@@ -250,9 +261,9 @@ fresh production execution of the same commit pair.
 a schema-9 terminal receipt with replay provenance.
 
 Examples:
-  haystack verify hosted start owner/repo --base <sha> --head <sha>
-  haystack verify hosted start owner/repo --base <sha> --head <sha> --replay-plan-from cv_<48 lowercase hex characters>
-  haystack verify hosted start owner/repo --base <sha> --head <sha> --no-wait --json
+  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() };
@@ -283,6 +294,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')
+    .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')
@@ -302,8 +314,8 @@ provenance, and no inconclusive cells. Use this mode to detect planner drift;
 use the default mode to isolate executor or assessment drift.
 
 Example:
-  haystack verify hosted reproducibility owner/repo --base <sha> --head <sha> --runs 3
-  haystack verify hosted reproducibility owner/repo --base <sha> --head <sha> --runs 3 --fresh-plans
+  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
 `)
     .action(async (repository, _options, cmd) => {
     const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
@@ -363,6 +375,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')

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

@@ -30,6 +30,22 @@ export interface DesignVerifierAgentCase {
         errors: string[];
     } | null;
 }
+export interface DesignVerifierRunHealthLoss {
+    code: string;
+    owner: 'harness' | 'case';
+    impact: 'degraded' | 'invalid';
+    count: number;
+    caseIds: string[];
+    obligationIds: string[];
+    slotIds: string[];
+    sides: string[];
+}
+export interface DesignVerifierRunHealth {
+    version: 'dv-run-health-v1';
+    status: 'healthy' | 'degraded' | 'invalid';
+    admitted: number;
+    losses: DesignVerifierRunHealthLoss[];
+}
 export interface DesignVerifierAgentReport {
     ok: boolean;
     status: 'complete' | 'failed';
@@ -47,6 +63,7 @@ export interface DesignVerifierAgentReport {
     timings: DesignVerifierTimingSummary | null;
     changedFiles: string[];
     cases: DesignVerifierAgentCase[];
+    runHealth: DesignVerifierRunHealth | null;
     inspectCommand: string;
     replay: Record<string, unknown> | null;
     error: string | null;

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

@@ -30,6 +30,54 @@ function universeSummaries(value, caseId) {
         ['control-before', 'before', 'after'].includes(universe.role) &&
         universe.lease && typeof universe.lease.available === 'boolean');
 }
+function runHealthOf(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const health = value;
+    if (health.version !== 'dv-run-health-v1' ||
+        !['healthy', 'degraded', 'invalid'].includes(health.status) ||
+        !Number.isInteger(health.admitted) || health.admitted < 0 ||
+        !Array.isArray(health.losses))
+        return null;
+    const losses = health.losses.filter((loss) => loss && typeof loss === 'object' &&
+        typeof loss.code === 'string' && loss.code.length > 0 &&
+        ['harness', 'case'].includes(loss.owner) &&
+        ['degraded', 'invalid'].includes(loss.impact) &&
+        Number.isInteger(loss.count) && loss.count > 0 &&
+        [loss.caseIds, loss.obligationIds, loss.slotIds, loss.sides]
+            .every(items => Array.isArray(items) && items.every(item => typeof item === 'string')));
+    if (losses.length !== health.losses.length)
+        return null;
+    const invalidHarnessLoss = losses.some(loss => loss.owner === 'harness' && loss.impact === 'invalid');
+    const expectedStatus = health.admitted === 0 || invalidHarnessLoss
+        ? 'invalid'
+        : losses.length > 0 ? 'degraded' : 'healthy';
+    if (health.status !== expectedStatus)
+        return null;
+    return {
+        version: health.version,
+        status: health.status,
+        admitted: health.admitted,
+        losses,
+    };
+}
+function missingRunHealth() {
+    return {
+        version: 'dv-run-health-v1',
+        status: 'invalid',
+        admitted: 0,
+        losses: [{
+                code: 'run-health-missing',
+                owner: 'harness',
+                impact: 'invalid',
+                count: 1,
+                caseIds: [],
+                obligationIds: [],
+                slotIds: [],
+                sides: [],
+            }],
+    };
+}
 export function buildDesignVerifierAgentReport(run) {
     const repository = `${run.owner}/${run.repo}`;
     if (run.status !== 'succeeded' || !run.result) {
@@ -47,6 +95,7 @@ export function buildDesignVerifierAgentReport(run) {
             timings: null,
             changedFiles: [],
             cases: [],
+            runHealth: null,
             inspectCommand: `haystack design-verify ${repository}#${run.pr} --run ${run.runId}`,
             replay: null,
             error: run.error,
@@ -55,6 +104,7 @@ export function buildDesignVerifierAgentReport(run) {
     }
     const verdict = run.result.verdict || {};
     const summary = verdict.summary || {};
+    const runHealth = runHealthOf(verdict.runHealth) || missingRunHealth();
     const findings = Array.isArray(verdict.findings) ? verdict.findings : [];
     const confirmations = Array.isArray(verdict.confirmations) ? verdict.confirmations : [];
     const findingsByCase = new Map();
@@ -133,7 +183,19 @@ export function buildDesignVerifierAgentReport(run) {
     let headline;
     let explanation;
     let exitCode;
-    if (findings.length > 0) {
+    if (runHealth.status === 'invalid') {
+        agentVerdict = 'inconclusive';
+        headline = 'VERIFICATION INCONCLUSIVE';
+        explanation = 'No admissible evidence — this is not a pass.';
+        exitCode = 2;
+    }
+    else if (runHealth.status === 'degraded') {
+        agentVerdict = 'inconclusive';
+        headline = 'VERIFICATION INCONCLUSIVE';
+        explanation = 'Evidence losses degraded this run; inspect the loss table before drawing a conclusion.';
+        exitCode = 2;
+    }
+    else if (findings.length > 0) {
         agentVerdict = 'anomaly_candidate';
         headline = 'ANOMALY CANDIDATE';
         explanation = findingExplanation(String(findings[0]?.kind || ''));
@@ -171,6 +233,7 @@ export function buildDesignVerifierAgentReport(run) {
         timings: run.result.timings || null,
         changedFiles: run.result.changedFiles,
         cases,
+        runHealth,
         inspectCommand: `haystack design-verify ${repository}#${run.pr} --run ${run.runId}`,
         replay: run.result.replay,
         error: null,
@@ -243,6 +306,22 @@ export function formatDesignVerifierAgentReport(report) {
             lines.push(`  orchestration/finalization not recorded in a phase: ${preciseDurationLabel(report.timings.unattributedMs)}`);
         }
     }
+    if (report.runHealth && report.runHealth.status !== 'healthy') {
+        lines.push('', `Run health: ${report.runHealth.status}; admitted evidence: ${report.runHealth.admitted}`);
+        if (report.runHealth.losses.length > 0) {
+            lines.push('Evidence loss table:', '  owner   impact    count  loss / stable identifiers');
+            for (const loss of report.runHealth.losses) {
+                const identifiers = [
+                    ...loss.caseIds,
+                    ...loss.obligationIds,
+                    ...loss.slotIds,
+                    ...loss.sides,
+                ];
+                lines.push(`  ${loss.owner.padEnd(7)} ${loss.impact.padEnd(9)} ${String(loss.count).padStart(5)}  ` +
+                    `${loss.code}${identifiers.length ? `: ${identifiers.join(', ')}` : ''}`);
+            }
+        }
+    }
     for (const testCase of report.cases) {
         lines.push('', `Test: ${testCase.title}`);
         if (testCase.story)

package/dist/utils/git.js

@@ -386,7 +386,11 @@ function gitCommandOptions(options) {
 /** True if `ref` resolves to a commit in the current repo. */
 function gitRefResolves(ref, options = {}) {
     try {
-        execFileSync('git', ['rev-parse', '--verify', '--quiet', '--', `${ref}^{commit}`], {
+        // `--end-of-options`, not `--`: rev-parse treats everything after `--` as
+        // a pathspec, so `-- refs/remotes/origin/main^{commit}` exits 1 for every
+        // ref and the caller fell back to a bare local `main` (which a fresh clone
+        // does not have). Verified on git 2.39: `--` rc=1, `--end-of-options` rc=0.
+        execFileSync('git', ['rev-parse', '--verify', '--quiet', '--end-of-options', `${ref}^{commit}`], {
             ...gitCommandOptions(options),
         });
         return true;

package/dist/utils/telemetry.js

@@ -103,7 +103,10 @@ export function trackError(errorType, metadata) {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(event),
-        }).catch(() => { });
+        }).catch(() => {
+            // Documented fire-and-forget product telemetry: delivery cannot affect
+            // the CLI command being measured.
+        });
     }
     catch {
         // Telemetry must never crash the CLI
@@ -135,7 +138,10 @@ export function trackSetupEvent(step, metadata) {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify(event),
-        }).catch(() => { });
+        }).catch(() => {
+            // Documented fire-and-forget product telemetry: delivery cannot affect
+            // the CLI command being measured.
+        });
     }
     catch {
         // Telemetry must never crash the CLI