@haystackeditor/cli 0.17.1 → 0.18.0

package/dist/commands/verify.js

@@ -1,64 +1,535 @@
-import { execFileSync } from 'node:child_process';
-import { parseHostedRepository, verifyHostedStartCommand } from './verify-hosted.js';
-function git(args, message) {
+/**
+ * `haystack verify` — the crawl of the current change (CRAWL-V1, amendment 1).
+ *
+ * It captures the checkout (committed and uncommitted) exactly as the stop
+ * hook does, finds the caller's crawl for that exact capture (its code and its
+ * change title, which is part of a crawl's identity and informs the judge), and
+ * submits the capture through the same front-half request `haystack verify
+ * precompute` sends when there is none, or when the one found ended cancelled
+ * or incomplete or is being cancelled (the service runs it again). It follows
+ * the acknowledged run by its id. It then waits (no wall-time cap: Ctrl-C
+ * stops waiting, never the crawl) and prints where the change shows up in the
+ * running app and what the crawl found. The hosted fleet run of pushed
+ * commits is `haystack verify hosted start|status`.
+ */
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { classifyHttpError, HaystackApiError } from '../utils/haystack-api.js';
+import { gatewayFetch } from './case-batch.js';
+import { CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, } from './crawl-contract.js';
+import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
+const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
+const DEFAULT_INTERVAL_SECONDS = 5;
+const MAX_INTERVAL_SECONDS = 300;
+const RUN_ID = /^cv_[0-9a-f]{48}$/;
+const REPOSITORY_COMPONENT = /^[A-Za-z0-9_.-]{1,100}$/;
+const STATUSES = ['queued', 'preparing', 'crawling', 'draining', 'completed', 'incomplete', 'cancelled'];
+const TERMINAL = new Set(['completed', 'incomplete', 'cancelled']);
+const STAGES = ['reconcile', 'source', 'worlds', 'blast', 'knobs', 'prepare', 'crawl', 'publish', 'cleanup'];
+const ERROR_CODES = ['source-mismatch', 'blast-unavailable', 'world-build-failed',
+    'prepare-failed', 'crawl-failed', 'no-capacity', 'stalled', 'lease-lost', 'cancelled'];
+const VERDICTS = ['bug', 'cant-tell', 'being-judged', 'not-a-bug'];
+const SPOT_STAGES = ['resolved', 'loaded', 'exposed', 'activated', 'pressed', 'observed', 'confirmed', 'judged'];
+const REUSE = ['hit', 'miss', null];
+const STATUS_WORDS = {
+    queued: 'waiting for a machine',
+    preparing: 'getting ready',
+    crawling: 'exploring the app',
+    draining: 'finishing the last checks',
+    completed: 'finished',
+    incomplete: 'stopped before finishing',
+    cancelled: 'cancelled',
+};
+const STAGE_WORDS = {
+    reconcile: 'cleaning up after an earlier try',
+    source: 'rebuilding your change',
+    worlds: 'building and starting the app with and without your change',
+    blast: 'waiting for the analysis of what your change touches',
+    knobs: "reading the app's settings",
+    prepare: 'setting up starting points next to your change',
+    crawl: 'exploring the app',
+    publish: 'saving the results',
+    cleanup: 'shutting down the machines it used',
+};
+const ERROR_WORDS = {
+    'source-mismatch': 'your change could not be rebuilt exactly as it was captured',
+    'blast-unavailable': 'the analysis of what your change touches was not available',
+    'world-build-failed': 'the app did not build or start, with or without your change',
+    'prepare-failed': 'setting up starting points next to your change failed',
+    'crawl-failed': 'exploring the app failed',
+    'no-capacity': 'there was no room on the machines for it',
+    stalled: 'it stopped making progress',
+    'lease-lost': 'the machine running it stopped responding',
+    cancelled: 'it was cancelled',
+};
+const SPOT_WORDS = {
+    resolved: 'never reached',
+    loaded: 'loaded but never ran',
+    exposed: 'shown on screen',
+    activated: 'ran',
+    pressed: 'ran when its control was pressed',
+    observed: 'a difference seen',
+    confirmed: 'a difference seen and confirmed',
+    judged: 'judged a bug',
+};
+const VERDICT_WORDS = {
+    bug: 'Bug',
+    'cant-tell': "Can't tell",
+    'being-judged': 'Still being judged',
+    'not-a-bug': 'Not a bug',
+};
+/** A response the CLI will not print: malformed, contradictory, or another revision's. */
+export class CrawlResponseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CrawlResponseError';
+    }
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isCount(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function isTimestamp(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isMember(value, members) {
+    return members.includes(value);
+}
+function isStrings(value, maximum = Infinity) {
+    return Array.isArray(value) && value.length <= maximum && value.every(item => typeof item === 'string');
+}
+function invalid(what) {
+    throw new CrawlResponseError(`The crawl service returned an invalid crawl (${what}); nothing is shown.`);
+}
+function checkError(value, what) {
+    if (!isRecord(value) || !isMember(value.code, ERROR_CODES) || !isMember(value.stage, STAGES)
+        || typeof value.message !== 'string')
+        invalid(what);
+}
+function checkReuse(value, what) {
+    if (!isRecord(value) || !['baseWorld', 'headWorld', 'prepare', 'routes']
+        .every(key => isMember(value[key], REUSE)))
+        invalid(what);
+}
+function checkFinding(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || !isMember(value.verdict, VERDICTS)
+        || (value.why !== null && typeof value.why !== 'string') || typeof value.start !== 'string'
+        || !isStrings(value.steps, CRAWL_MAX_FINDING_STEPS) || !isRecord(value.observed) || !isRecord(value.codeThatRan)
+        || typeof value.confirmedAtSeconds !== 'number' || !Number.isFinite(value.confirmedAtSeconds)
+        || !isRecord(value.images)
+        || (value.images.old !== null && typeof value.images.old !== 'string')
+        || (value.images.new !== null && typeof value.images.new !== 'string'))
+        invalid('a finding');
+}
+function checkSpot(value) {
+    if (!isRecord(value) || typeof value.id !== 'string' || typeof value.file !== 'string'
+        || !Number.isSafeInteger(value.line) || value.line < 1
+        || (value.furthest !== null && !isMember(value.furthest, SPOT_STAGES))
+        || !isStrings(value.shows) || !isStrings(value.findingIds))
+        invalid('a changed spot');
+    const reached = value.reachedBy;
+    if (reached !== null && (!isRecord(reached) || !isMember(reached.stage, SPOT_STAGES)
+        || typeof reached.start !== 'string' || !isStrings(reached.steps)
+        || (reached.page !== null && typeof reached.page !== 'string')))
+        invalid('how a changed spot was reached');
+}
+function checkManifest(value, view) {
+    if (!isRecord(value) || value.schemaVersion !== 1)
+        invalid('its results');
+    // The published results belong to exactly this crawl and this revision.
+    if (value.runId !== view.runId || value.repository !== view.repository || value.baseCommit !== view.baseCommit
+        || value.workCommit !== view.workCommit || value.treeSha !== view.treeSha || value.changeTitle !== view.changeTitle
+        || value.status !== view.status) {
+        invalid('results that belong to a different crawl');
+    }
+    if (typeof value.attemptId !== 'string' || !isCount(value.bugs) || !isCount(value.notFinishedInTime))
+        invalid('its results');
+    if (value.worlds !== null && (!isRecord(value.worlds) || typeof value.worlds.base !== 'string'
+        || typeof value.worlds.head !== 'string'))
+        invalid('its results');
+    checkReuse(value.reuse, 'its results');
+    if (!isRecord(value.timings) || !Object.values(value.timings)
+        .every(ms => typeof ms === 'number' && Number.isFinite(ms) && ms >= 0))
+        invalid('its stage timings');
+    if (!Array.isArray(value.findings) || value.findings.length > CRAWL_MAX_FINDINGS)
+        invalid('its findings');
+    for (const finding of value.findings)
+        checkFinding(finding);
+    const reach = value.reach;
+    if (!isRecord(reach) || !Array.isArray(reach.spots) || !isStrings(reach.unreachedChangedFiles))
+        invalid('its reach');
+    for (const spot of reach.spots)
+        checkSpot(spot);
+    const blast = reach.blast;
+    if (blast !== null && (!isRecord(blast) || !isCount(blast.functions) || !isCount(blast.ran)
+        || !isCount(blast.unreached) || !isStrings(blast.nearestUnreached)))
+        invalid('its affected functions');
+    if (value.error !== null)
+        checkError(value.error, 'its error');
+}
+/** Accepts only a well-formed crawl of exactly this capture's revision. Another
+ * revision's crawl is refused, never shown. The change title is not checked
+ * here: the newest crawl of a revision may carry another title, which the
+ * caller compares (sameChange). */
+export function parseCrawlView(value, expected) {
+    if (!isRecord(value) || typeof value.runId !== 'string' || !RUN_ID.test(value.runId))
+        invalid('its run id');
+    // GitHub repository names are case-insensitive; commits and trees are exact.
+    if (typeof value.repository !== 'string'
+        || value.repository.toLowerCase() !== expected.repository.toLowerCase()
+        || value.baseCommit !== expected.baseCommit || value.workCommit !== expected.workCommit
+        || value.treeSha !== expected.treeSha) {
+        throw new CrawlResponseError('The crawl service returned a crawl of a different revision; it is not shown.');
+    }
+    if (!isMember(value.status, STATUSES) || !isMember(value.stage, STAGES)
+        || typeof value.changeTitle !== 'string' || !isCount(value.observedAt)
+        || !isTimestamp(value.createdAt) || !isTimestamp(value.updatedAt)
+        || (value.supersededBy !== null && (typeof value.supersededBy !== 'string' || !RUN_ID.test(value.supersededBy)))
+        || typeof value.cancelRequested !== 'boolean')
+        invalid('its status');
+    const clocks = value.clocks;
+    if (!isRecord(clocks) || !['startedAt', 'stageStartedAt', 'crawlStartedAt', 'finishedAt']
+        .every(key => clocks[key] === null || isTimestamp(clocks[key])) || !isCount(clocks.crawlBudgetMs))
+        invalid('its clocks');
+    checkReuse(value.reuse, 'what it reused');
+    if (!isRecord(value.worlds) || (value.worlds.base !== null && typeof value.worlds.base !== 'string')
+        || (value.worlds.head !== null && typeof value.worlds.head !== 'string'))
+        invalid('its app builds');
+    const totals = value.totals;
+    if (!isRecord(totals) || !['clicks', 'differing', 'confirmed', 'bugs', 'vmsLaunched', 'cleanupProven', 'cleanupUnproven']
+        .every(key => isCount(totals[key])))
+        invalid('its totals');
+    if (value.error !== undefined)
+        checkError(value.error, 'its error');
+    if (value.manifest !== null) {
+        if (!TERMINAL.has(value.status))
+            invalid('results before it finished');
+        checkManifest(value.manifest, value);
+    }
+    return value;
+}
+/* ------------------------------------------------------------------- read */
+/** The change title is part of a crawl's identity and informs its judge: a
+ * crawl of the same code under another title is not this change's crawl. */
+function sameChange(view, identity) {
+    return view.changeTitle === identity.changeTitle;
+}
+async function responseBody(response) {
     try {
-        return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+        return await response.json();
+    }
+    catch (error) {
+        throw new CrawlResponseError(`The crawl service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** The caller's newest crawl of this capture's revision, or null. Its change
+ * title may differ from the capture's (sameChange). */
+async function readCrawl(identity, token) {
+    const path = `${CRAWLS_PATH}?repository=${encodeURIComponent(identity.repository)}`
+        + `&workCommit=${encodeURIComponent(identity.workCommit)}`;
+    const response = await gatewayFetch(path, token);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}`);
+    const body = await responseBody(response);
+    if (!isRecord(body) || !Object.hasOwn(body, 'crawl'))
+        invalid('no crawl field');
+    return body.crawl === null ? null : parseCrawlView(body.crawl, identity);
+}
+/** One crawl by its run id; it must be exactly this capture, change title included. */
+async function readCrawlRun(runId, identity, token) {
+    if (!RUN_ID.test(runId))
+        invalid('an acknowledged run id');
+    const response = await gatewayFetch(`${CRAWLS_PATH}/${runId}?repository=${encodeURIComponent(identity.repository)}`, token);
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}/${runId}`);
+    const view = parseCrawlView(await responseBody(response), identity);
+    if (view.runId !== runId || !sameChange(view, identity)) {
+        throw new CrawlResponseError(`The crawl service returned another crawl for ${runId}; it is not shown.`);
     }
-    catch {
-        throw new Error(message);
+    return view;
+}
+/* ----------------------------------------------------------------- output */
+function safe(value) {
+    // Server text never moves the cursor or rewrites the terminal.
+    // eslint-disable-next-line no-control-regex -- replacing control characters is the point
+    return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, ' ');
+}
+function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+function errorWords(error) {
+    return error.code === 'stalled'
+        ? `${ERROR_WORDS.stalled} while ${STAGE_WORDS[error.stage]}`
+        : ERROR_WORDS[error.code];
+}
+/** What a running crawl is doing now: its stage, except while it waits for a
+ * machine or finishes its last checks, which its status says better. */
+function currentStep(view) {
+    return view.status === 'queued' || view.status === 'draining' ? STATUS_WORDS[view.status] : STAGE_WORDS[view.stage];
+}
+function headline(view) {
+    const bugs = view.manifest?.bugs ?? view.totals.bugs;
+    const found = bugs > 0 ? ` It found ${plural(bugs, 'bug')} before it stopped.` : '';
+    switch (view.status) {
+        case 'completed':
+            return bugs > 0 ? `Found ${plural(bugs, 'bug')} in your change.` : 'No bugs found in your change.';
+        case 'incomplete': {
+            const error = view.manifest?.error ?? view.error;
+            return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
+        }
+        case 'cancelled':
+            return `The crawl was cancelled${view.supersededBy ? ': a newer stop in this repository replaced it' : ''}.${found}`;
+        default: {
+            const so = bugs > 0 ? ` ${plural(bugs, 'bug')} found so far.` : '';
+            if (view.cancelRequested) {
+                return `Being cancelled${view.supersededBy ? ' (a newer stop in this repository replaced it)' : ''}: `
+                    + `${currentStep(view)}.${so}`;
+            }
+            return `Still running: ${currentStep(view)}.${so}`;
+        }
+    }
+}
+function spotLines(spot) {
+    const how = spot.furthest === null ? 'never reached' : SPOT_WORDS[spot.furthest];
+    const lines = [`  ${chalk.bold(`${safe(spot.file)}:${spot.line}`)}  ${how}`];
+    if (spot.reachedBy) {
+        lines.push(`      reached by: ${[spot.reachedBy.start, ...spot.reachedBy.steps].map(safe).join(' > ')}`);
+        if (spot.reachedBy.page !== null)
+            lines.push(`      page: ${safe(spot.reachedBy.page)}`);
     }
+    return lines;
 }
-function originRepository() {
-    const remote = git(['remote', 'get-url', 'origin'], 'Could not read origin; pass --repo owner/repo.');
-    let path;
+function findingLines(finding, position) {
+    const verdict = VERDICT_WORDS[finding.verdict];
+    const label = finding.verdict === 'bug' ? chalk.red(verdict) : verdict;
+    const lines = [`  ${position}. ${label}: ${finding.why === null ? 'no reason was recorded.' : safe(finding.why)}`,
+        `     Starting from ${safe(finding.start)}:`];
+    finding.steps.forEach((step, index) => lines.push(`       ${index + 1}. ${safe(step)}`));
+    return lines;
+}
+export function formatCrawl(view) {
+    const lines = [chalk.bold(headline(view))];
+    const error = view.manifest?.error ?? view.error;
+    if (error && view.status !== 'completed')
+        lines.push(chalk.dim(`  Details: ${safe(error.message)}`));
+    lines.push(`  Change: ${safe(view.changeTitle)}`, chalk.dim(`  Crawl ${view.runId} of ${safe(view.repository)}: base ${view.baseCommit.slice(0, 12)},`
+        + ` your change ${view.workCommit.slice(0, 12)}.`));
+    const manifest = view.manifest;
+    if (manifest === null) {
+        lines.push('', TERMINAL.has(view.status)
+            ? 'No results were published for this crawl.'
+            : 'Where your change shows up in the app, and what the crawl found, appear when it finishes.');
+        return lines.join('\n');
+    }
+    // A crawl that stopped before exploring measured nothing: its empty reach and findings are not "nothing found".
+    if (view.clocks.crawlStartedAt === null) {
+        lines.push('', 'It stopped before exploring the app, so nothing about your change was measured.');
+        return lines.join('\n');
+    }
+    lines.push('', chalk.bold('Where your change shows up in the app'));
+    if (manifest.reach.spots.length === 0)
+        lines.push('  No changed spots were recorded.');
+    for (const spot of manifest.reach.spots)
+        lines.push(...spotLines(spot));
+    lines.push('', chalk.bold('What the crawl found'));
+    // Bugs first, then the undecided, then what the judge called intended.
+    const findings = VERDICTS.flatMap(verdict => manifest.findings.filter(finding => finding.verdict === verdict));
+    if (findings.length === 0)
+        lines.push('  No confirmed differences between the app with and without your change.');
+    findings.forEach((finding, index) => lines.push(...findingLines(finding, index + 1)));
+    if (manifest.notFinishedInTime > 0) {
+        lines.push(`  ${plural(manifest.notFinishedInTime, 'difference')} ${manifest.notFinishedInTime === 1 ? 'was' : 'were'}`
+            + ' still being checked when its time ran out.');
+    }
+    lines.push('', chalk.bold('What the crawl never ran'));
+    if (manifest.reach.unreachedChangedFiles.length === 0)
+        lines.push('  Every changed file ran at least once.');
+    else {
+        lines.push('  Changed files no path ran:');
+        for (const file of manifest.reach.unreachedChangedFiles)
+            lines.push(`    ${safe(file)}`);
+    }
+    const blast = manifest.reach.blast;
+    if (blast !== null)
+        lines.push(`  ${blast.ran} of ${plural(blast.functions, 'affected function')} ran.`);
+    if (view.totals.cleanupUnproven > 0) {
+        lines.push('', chalk.yellow(`  ${plural(view.totals.cleanupUnproven, 'machine')} it used could not be proven shut down.`));
+    }
+    return lines.join('\n');
+}
+/** Case-batch status conventions: 0 finished, or still running with --no-wait;
+ * 2 ended without finishing (incomplete, cancelled) or cleanup unproven; bugs
+ * found never change it. The command's own failures exit 1 elsewhere. */
+export function crawlExitCode(view) {
+    if (!TERMINAL.has(view.status))
+        return 0;
+    if (view.status !== 'completed' || view.totals.cleanupUnproven > 0)
+        return 2;
+    return 0;
+}
+/* ---------------------------------------------------------------- command */
+function intervalMs(value) {
+    if (value === undefined)
+        return DEFAULT_INTERVAL_SECONDS * 1000;
+    const seconds = Number(value);
+    if (!Number.isFinite(seconds) || seconds <= 0 || seconds > MAX_INTERVAL_SECONDS) {
+        throw new Error(`--interval must be a positive number no greater than ${MAX_INTERVAL_SECONDS}.`);
+    }
+    return seconds * 1000;
+}
+function repositoryOverride(value) {
+    if (value === undefined)
+        return undefined;
+    const parts = value.split('/');
+    if (parts.length !== 2 || !parts.every(part => REPOSITORY_COMPONENT.test(part) && part !== '.' && part !== '..')) {
+        throw new Error(`Invalid repository "${value}". Use an exact GitHub owner/repository name.`);
+    }
+    return { owner: parts[0], repository: parts[1] };
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+function progress(line) {
+    console.error(chalk.dim(`${new Date().toTimeString().slice(0, 8)} ${line}`));
+}
+/** Polls the same capture until its crawl is terminal. No wall-time cap: an
+ * interrupt stops waiting and leaves the crawl running. */
+async function waitForCrawl(first, identity, token, everyMs) {
+    const interrupted = () => {
+        console.error('\nStopped waiting. The crawl keeps running; run `haystack verify` again to see it.');
+        process.exit(130);
+    };
+    process.once('SIGINT', interrupted);
     try {
-        path = remote.includes('://')
-            ? new URL(remote).pathname.replace(/^\//, '')
-            : remote.match(/^[^@/]+@[^:]+:(.+)$/)?.[1] ?? '';
-        return parseHostedRepository(path.replace(/\.git$/, '')).fullName;
-    }
-    catch {
-        throw new Error('Could not determine owner/repo from origin; pass --repo owner/repo.');
-    }
-}
-export function resolveVerifyRepository(options) {
-    const repo = options.repo ?? originRepository();
-    let head = options.head;
-    if (head === undefined) {
-        head = git(['rev-parse', '--verify', 'HEAD^{commit}'], 'Could not read HEAD; run inside a git checkout or pass --head.');
-        // The fleet fetches from the GitHub origin, so only origin's branches
-        // prove the commit is reachable there; another remote does not.
-        const originBranches = git(['for-each-ref', '--format=%(refname)', '--contains', head, 'refs/remotes/origin/'], 'Could not check origin branches for HEAD.');
-        if (!originBranches)
-            throw new Error('Push HEAD to origin before running haystack verify.');
-    }
-    let base = options.base;
-    if (base === undefined) {
-        let defaultBranch = 'origin/main';
+        let view = first;
+        progress(`Waiting for crawl ${view.runId} (Ctrl-C stops waiting; the crawl keeps running).`);
+        progress(currentStep(view));
+        while (!TERMINAL.has(view.status)) {
+            await delay(everyMs);
+            let next = await readCrawl(identity, token);
+            if (next === null)
+                throw new CrawlResponseError(`The crawl service no longer returns crawl ${view.runId} for this change.`);
+            // A newer crawl of the same code under another title is another change's: keep following this one.
+            if (!sameChange(next, identity))
+                next = await readCrawlRun(view.runId, identity, token);
+            if (next.runId !== view.runId)
+                progress(`A newer crawl of this same change took over (${next.runId}).`);
+            if (!TERMINAL.has(next.status) && (next.runId !== view.runId || currentStep(next) !== currentStep(view))) {
+                progress(currentStep(next));
+            }
+            view = next;
+        }
+        return view;
+    }
+    finally {
+        process.removeListener('SIGINT', interrupted);
+    }
+}
+function staleCrawl(found, identity) {
+    if (!sameChange(found, identity))
+        return 'retitled';
+    if (found.status === 'cancelled' || found.status === 'incomplete')
+        return found.status;
+    return !TERMINAL.has(found.status) && found.cancelRequested ? 'cancelling' : null;
+}
+function staleWords(found, stale) {
+    switch (stale) {
+        case 'retitled': return `The last crawl of this code ran under another title, "${safe(found.changeTitle)}" (${found.runId})`;
+        case 'cancelled': return `This change's last crawl was cancelled (${found.runId})`;
+        case 'incomplete': return `This change's last crawl stopped before finishing (${found.runId})`;
+        case 'cancelling': return `This change's crawl is being cancelled (${found.runId})`;
+    }
+}
+/** Submits the capture through the explicit precompute submission when no crawl
+ * of it exists or the one found is stale. Returns the acknowledged run id (null
+ * when no crawl could be started) and the line to report. */
+async function submitCapture(capture, token, found) {
+    let acknowledgment;
+    // A momentary 429/5xx (a server or runner restarting) is asked again, as the stop hook's sender does: admission is
+    // idempotent for one capture, so a repeat can only find what the first created.
+    const pauses = [2_000, 5_000, 10_000];
+    for (let attempt = 0; acknowledgment === undefined; attempt += 1) {
         try {
-            defaultBranch = git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], 'Could not read origin/HEAD.');
+            acknowledgment = await postPrecomputeCapture(capture, token, Date.now() + EXPLICIT_WALL_MS);
         }
-        catch {
-            // Repositories without origin/HEAD use origin/main.
+        catch (error) {
+            const transient = error instanceof HaystackApiError && [429, 502, 503, 504].includes(error.status);
+            if (!transient || attempt >= pauses.length)
+                throw normalModeFailure(error);
+            await new Promise(resolve => setTimeout(resolve, pauses[attempt]));
         }
-        // The base belongs to the head being verified, which may be an explicit
-        // --head rather than the working tree.
-        base = git(['merge-base', head, defaultBranch], `Could not find the merge base of ${head} with ${defaultBranch}; fetch origin or pass --base.`);
     }
-    return { repo, base, head };
+    const crawl = acknowledgment.crawl;
+    const before = found === null ? 'No crawl existed for this change' : staleWords(found.view, found.stale);
+    if (crawl === undefined) {
+        return { runId: null, line: `${before}, and the service did not say whether it started ${found === null ? 'one' : 'another'}.` };
+    }
+    if (crawl.status === 'unavailable') {
+        return { runId: null, line: `${before}, and ${found === null ? 'none' : 'another'} could not be started: ${crawlUnavailableText(crawl.reason)}.` };
+    }
+    if (found === null) {
+        return { runId: crawl.runId, line: crawl.status === 'queued'
+                ? `No crawl existed for this change yet; started one (${crawl.runId}).`
+                : `The service already had a crawl for this change (${crawl.runId}).` };
+    }
+    if (found.stale !== 'retitled' && crawl.runId === found.view.runId) {
+        return { runId: crawl.runId, line: `${before}; asked the service to run it again.` };
+    }
+    return { runId: crawl.runId, line: crawl.status === 'queued'
+            ? `${before}; started one for this change (${crawl.runId}).`
+            : `${before}; the service already had one for this change (${crawl.runId}).` };
 }
 export async function verifyCommand(options) {
-    const { repo, base, head } = resolveVerifyRepository(options);
-    await verifyHostedStartCommand(repo, {
-        provider: 'haystack',
-        base,
-        head,
-        intentFile: options.intentFile,
-        idempotencyKey: options.idempotencyKey,
-        account: options.account,
-        wait: options.wait,
-        interval: options.interval,
-        timeout: options.timeout,
-        json: options.json,
-    });
+    const everyMs = intervalMs(options.interval);
+    // In --json mode stdout carries the one document; every other line goes to stderr.
+    const note = (line) => { if (options.json)
+        console.error(line);
+    else
+        console.log(line); };
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, repositoryOverride(options.repo));
+    const request = capture.derivation.request;
+    if (!request.crawl) {
+        note(`Nothing to verify: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(withSchema('verify', { crawl: null }), null, 2)}\n`);
+        return;
+    }
+    const identity = {
+        repository: `${request.owner}/${request.repository}`,
+        baseCommit: request.baseCommit,
+        workCommit: request.workCommit,
+        treeSha: request.crawl.treeSha,
+        changeTitle: request.crawl.changeTitle,
+    };
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner: request.owner, repo: request.repository });
+    let view = await readCrawl(identity, auth.token);
+    const stale = view === null ? null : staleCrawl(view, identity);
+    if (view === null || stale !== null) {
+        const found = view === null || stale === null ? null : { view, stale };
+        const submitted = await submitCapture(capture, auth.token, found);
+        note(submitted.line);
+        if (submitted.runId === null) {
+            if (options.json)
+                process.stdout.write(`${JSON.stringify(withSchema('verify', { crawl: null }), null, 2)}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        view = await readCrawlRun(submitted.runId, identity, auth.token);
+        if (found !== null && found.stale !== 'retitled' && view.runId === found.view.runId && TERMINAL.has(view.status)) {
+            note('The service did not run it again; its last result follows.');
+        }
+    }
+    if (options.wait !== false && !TERMINAL.has(view.status)) {
+        view = await waitForCrawl(view, identity, auth.token, everyMs);
+    }
+    if (options.json)
+        process.stdout.write(`${JSON.stringify(withSchema('verify', { crawl: view }), null, 2)}\n`);
+    else
+        console.log(formatCrawl(view));
+    const exitCode = crawlExitCode(view);
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
 }