@haystackeditor/cli 0.18.0 → 0.20.0

package/dist/commands/verify.js

@@ -1,5 +1,6 @@
 /**
- * `haystack verify` — the crawl of the current change (CRAWL-V1, amendment 1).
+ * `haystack verify` — the crawl of the current change (CRAWL-V1, amendments 1
+ * and 8).
  *
  * 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
@@ -8,20 +9,31 @@
  * 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`.
+ * stops waiting, never the crawl), each read held by the service until the
+ * crawl changes (amendment 9), printing each bug as the crawl's answers bring
+ * it; it stops at the crawl's answer at its budget, or when the crawl ends, 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`.
+ *
+ * A base the service has not onboarded yet answers the submission `onboarding`
+ * (APP-ONBOARDING-V1): the command follows the onboarding's stage list until
+ * it is ready, then submits the capture again, which finds the crawl the
+ * service admitted from the first submission (or starts it), and follows that.
+ * A blocked onboarding prints why and exactly what would unblock it.
  */
+import { execFileSync } from 'node:child_process';
 import chalk from 'chalk';
 import { withSchema } from '../schema.js';
+import { findGitRoot } from '../utils/hooks.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 { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
+import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_WAIT_MAX_MS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
+import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, waitForOnboarding } from './verify-onboarding.js';
 const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
-const DEFAULT_INTERVAL_SECONDS = 5;
-const MAX_INTERVAL_SECONDS = 300;
+/** A held read (waitAfter): the service's hold, then the time any read gets. */
+const HELD_READ_TIMEOUT_MS = CRAWL_WAIT_MAX_MS + GATEWAY_TIMEOUT_MS;
 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'];
@@ -71,7 +83,8 @@ const SPOT_WORDS = {
     pressed: 'ran when its control was pressed',
     observed: 'a difference seen',
     confirmed: 'a difference seen and confirmed',
-    judged: 'judged a bug',
+    // The stage, not the verdict: a judged difference may be judged not a bug. The findings carry the verdicts.
+    judged: 'a difference seen, confirmed and judged',
 };
 const VERDICT_WORDS = {
     bug: 'Bug',
@@ -136,21 +149,21 @@ function checkSpot(value) {
         || (reached.page !== null && typeof reached.page !== 'string')))
         invalid('how a changed spot was reached');
 }
-function checkManifest(value, view) {
+/** The published results' shape, shared by the sealed manifest and (amendment 9) an answer; `what` names which. */
+function checkResults(value, view, what) {
     if (!isRecord(value) || value.schemaVersion !== 1)
-        invalid('its results');
-    // The published results belong to exactly this crawl and this revision.
+        invalid(what);
+    // 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');
+        || value.workCommit !== view.workCommit || value.treeSha !== view.treeSha || value.changeTitle !== view.changeTitle) {
+        invalid(`${what} from a different crawl`);
     }
     if (typeof value.attemptId !== 'string' || !isCount(value.bugs) || !isCount(value.notFinishedInTime))
-        invalid('its results');
+        invalid(what);
     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');
+        invalid(what);
+    checkReuse(value.reuse, what);
     if (!isRecord(value.timings) || !Object.values(value.timings)
         .every(ms => typeof ms === 'number' && Number.isFinite(ms) && ms >= 0))
         invalid('its stage timings');
@@ -170,6 +183,18 @@ function checkManifest(value, view) {
     if (value.error !== null)
         checkError(value.error, 'its error');
 }
+function checkManifest(value, view) {
+    checkResults(value, view, 'its results');
+    if (value.status !== view.status)
+        invalid('its results from a different crawl');
+}
+/** Amendment 9: what the crawl found so far, or its answer at the budget: the manifest's shape, of this same crawl. */
+function checkAnswer(value, view) {
+    checkResults(value, view, 'its answer');
+    if ((value.status !== 'exploring' && value.status !== 'answered') || !Number.isSafeInteger(value.n) || value.n < 1
+        || !isCount(value.atSeconds))
+        invalid('its answer');
+}
 /** 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
@@ -209,7 +234,19 @@ export function parseCrawlView(value, expected) {
             invalid('results before it finished');
         checkManifest(value.manifest, value);
     }
-    return value;
+    // Amendment 8: a service from before it sends no budgetMs, and every crawl it ran was asked for the default (Astra review).
+    if (value.budgetMs !== undefined && value.budgetMs !== null && (typeof value.budgetMs !== 'number' || !Number.isInteger(value.budgetMs)
+        || value.budgetMs < CRAWL_BUDGET_MIN_MS || value.budgetMs > CRAWL_BUDGET_MAX_MS))
+        invalid('its time');
+    // Amendment 9: a service from before it sends no answer. An answer stands in for results not yet sealed, never beside them.
+    let answer = null;
+    if (value.answer !== undefined && value.answer !== null) {
+        if (value.manifest !== null)
+            invalid('an answer beside its sealed results');
+        checkAnswer(value.answer, value);
+        answer = value.answer;
+    }
+    return { ...value, budgetMs: value.budgetMs ?? null, answer };
 }
 /* ------------------------------------------------------------------- read */
 /** The change title is part of a crawl's identity and informs its judge: a
@@ -225,12 +262,19 @@ async function responseBody(response) {
         throw new CrawlResponseError(`The crawl service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/** A read, held by the service when `waitAfter` (the updatedAt the caller holds) is given: until the
+ * crawl's updatedAt changes, or CRAWL_WAIT_MAX_MS passes (amendment 9). */
+function read(path, token, waitAfter) {
+    return waitAfter === undefined
+        ? gatewayFetch(path, token)
+        : gatewayFetch(`${path}&waitAfter=${encodeURIComponent(waitAfter)}`, token, { method: 'GET', timeoutMs: HELD_READ_TIMEOUT_MS });
+}
 /** 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) {
+async function readCrawl(identity, token, waitAfter) {
     const path = `${CRAWLS_PATH}?repository=${encodeURIComponent(identity.repository)}`
         + `&workCommit=${encodeURIComponent(identity.workCommit)}`;
-    const response = await gatewayFetch(path, token);
+    const response = await read(path, token, waitAfter);
     if (!response.ok)
         throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}`);
     const body = await responseBody(response);
@@ -239,10 +283,10 @@ async function readCrawl(identity, token) {
     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) {
+async function readCrawlRun(runId, identity, token, waitAfter) {
     if (!RUN_ID.test(runId))
         invalid('an acknowledged run id');
-    const response = await gatewayFetch(`${CRAWLS_PATH}/${runId}?repository=${encodeURIComponent(identity.repository)}`, token);
+    const response = await read(`${CRAWLS_PATH}/${runId}?repository=${encodeURIComponent(identity.repository)}`, token, waitAfter);
     if (!response.ok)
         throw await classifyHttpError(response, `Haystack API ${CRAWLS_PATH}/${runId}`);
     const view = parseCrawlView(await responseBody(response), identity);
@@ -270,14 +314,23 @@ function errorWords(error) {
 function currentStep(view) {
     return view.status === 'queued' || view.status === 'draining' ? STATUS_WORDS[view.status] : STAGE_WORDS[view.stage];
 }
+/** The crawl's results: its sealed manifest, else (amendment 9) its answer at the budget, which has the same findings and reach. */
+function results(view) {
+    return view.manifest ?? (view.answer?.status === 'answered' ? view.answer : null);
+}
+/** The status the command reports: a running crawl that has answered (amendment 9: its budget is up and its work is
+ * done; only its shutdown remains) reads as completed. */
+function reportedStatus(view) {
+    return !TERMINAL.has(view.status) && view.answer?.status === 'answered' ? 'completed' : view.status;
+}
 function headline(view) {
-    const bugs = view.manifest?.bugs ?? view.totals.bugs;
+    const bugs = results(view)?.bugs ?? view.totals.bugs;
     const found = bugs > 0 ? ` It found ${plural(bugs, 'bug')} before it stopped.` : '';
-    switch (view.status) {
+    switch (reportedStatus(view)) {
         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;
+            const error = results(view)?.error ?? view.error;
             return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
         }
         case 'cancelled':
@@ -294,7 +347,9 @@ function headline(view) {
 }
 function spotLines(spot) {
     const how = spot.furthest === null ? 'never reached' : SPOT_WORDS[spot.furthest];
-    const lines = [`  ${chalk.bold(`${safe(spot.file)}:${spot.line}`)}  ${how}`];
+    const found = spot.findingIds.length === 0 ? ''
+        : ` (${spot.findingIds.length} finding${spot.findingIds.length === 1 ? '' : 's'} below)`;
+    const lines = [`  ${chalk.bold(`${safe(spot.file)}:${spot.line}`)}  ${how}${found}`];
     if (spot.reachedBy) {
         lines.push(`      reached by: ${[spot.reachedBy.start, ...spot.reachedBy.steps].map(safe).join(' > ')}`);
         if (spot.reachedBy.page !== null)
@@ -311,15 +366,17 @@ function findingLines(finding, position) {
     return lines;
 }
 export function formatCrawl(view) {
+    const status = reportedStatus(view);
     const lines = [chalk.bold(headline(view))];
-    const error = view.manifest?.error ?? view.error;
-    if (error && view.status !== 'completed')
+    const published = results(view);
+    const error = published?.error ?? view.error;
+    if (error && 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)},`
+    lines.push(`  Change: ${safe(view.changeTitle)}`, chalk.dim(`  Time: ${view.clocks.crawlBudgetMs > 0 ? `${Math.round(view.clocks.crawlBudgetMs / 1000)} s` : timeWords(view.budgetMs)}`
+        + `${view.budgetMs === null ? ' (the default; set another with --minutes or .haystack.json crawl.minutes)' : ' (asked for)'}.`), 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)
+    if (published === null) {
+        lines.push('', TERMINAL.has(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');
@@ -330,55 +387,60 @@ export function formatCrawl(view) {
         return lines.join('\n');
     }
     lines.push('', chalk.bold('Where your change shows up in the app'));
-    if (manifest.reach.spots.length === 0)
+    if (published.reach.spots.length === 0)
         lines.push('  No changed spots were recorded.');
-    for (const spot of manifest.reach.spots)
+    for (const spot of published.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));
+    const findings = VERDICTS.flatMap(verdict => published.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'}`
+    if (published.notFinishedInTime > 0) {
+        lines.push(`  ${plural(published.notFinishedInTime, 'difference')} ${published.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)
+    if (published.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)
+        for (const file of published.reach.unreachedChangedFiles)
             lines.push(`    ${safe(file)}`);
     }
-    const blast = manifest.reach.blast;
+    const blast = published.reach.blast;
     if (blast !== null)
         lines.push(`  ${blast.ran} of ${plural(blast.functions, 'affected function')} ran.`);
-    if (view.totals.cleanupUnproven > 0) {
+    // Only a finished crawl has proven its cleanup: an answered one is still shutting its machines down (Bugbot).
+    if (TERMINAL.has(view.status) && 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
+/** Case-batch status conventions: 0 finished (or answered: amendment 9, its work
+ * is done and only its shutdown remains), or still running with --no-wait;
+ * 2 ended without finishing (incomplete, cancelled) or finished with cleanup
+ * unproven (an answered crawl has not finished its cleanup, so it is not judged); bugs
  * found never change it. The command's own failures exit 1 elsewhere. */
 export function crawlExitCode(view) {
-    if (!TERMINAL.has(view.status))
+    const status = reportedStatus(view);
+    if (!TERMINAL.has(status))
         return 0;
-    if (view.status !== 'completed' || view.totals.cleanupUnproven > 0)
+    if (status !== 'completed' || (TERMINAL.has(view.status) && view.totals.cleanupUnproven > 0))
         return 2;
     return 0;
 }
 /* ---------------------------------------------------------------- command */
-function intervalMs(value) {
+/** --minutes: whole minutes from 1 to 30 (CRAWL-V1 amendment 8). */
+function minutesOption(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 undefined;
+    const minutes = Number(value);
+    if (!Number.isInteger(minutes) || minutes * 60_000 < CRAWL_BUDGET_MIN_MS || minutes * 60_000 > CRAWL_BUDGET_MAX_MS) {
+        throw new Error(`--minutes must be a whole number from ${CRAWL_BUDGET_MIN_MS / 60_000} to ${CRAWL_BUDGET_MAX_MS / 60_000}.`);
     }
-    return seconds * 1000;
+    return minutes;
 }
 function repositoryOverride(value) {
     if (value === undefined)
@@ -389,15 +451,39 @@ function repositoryOverride(value) {
     }
     return { owner: parts[0], repository: parts[1] };
 }
-function delay(milliseconds) {
-    return new Promise(resolve => setTimeout(resolve, milliseconds));
+function clock() {
+    return new Date().toTimeString().slice(0, 8);
 }
 function progress(line) {
-    console.error(chalk.dim(`${new Date().toTimeString().slice(0, 8)} ${line}`));
+    console.error(chalk.dim(`${clock()} ${line}`));
+}
+function clip(text, maximum = 60) {
+    return text.length <= maximum ? text : `${text.slice(0, maximum - 1)}…`;
+}
+/** A finding's steps in one line: where it starts, then its steps, the middle of a long path elided. */
+function shortSteps(finding) {
+    const steps = finding.steps.map(step => clip(safe(step)));
+    const shown = steps.length <= 4 ? steps : [steps[0], `(${steps.length - 3} more steps)`, ...steps.slice(-2)];
+    return [`from ${clip(safe(finding.start))}`, ...shown].join(' > ');
 }
-/** 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) {
+/** Prints each bug the view's answer brings that was not printed before (by finding id), one line each. */
+function printNewBugs(view, printed) {
+    const answer = view.answer;
+    if (answer === null)
+        return;
+    for (const finding of answer.findings) {
+        // Keyed by run and attempt too: another run or a retried attempt may reuse a finding id (Astra review).
+        const key = `${view.runId}\0${answer.attemptId}\0${finding.id}`;
+        if (finding.verdict !== 'bug' || printed.has(key))
+            continue;
+        printed.add(key);
+        console.error(`${chalk.dim(clock())} ${chalk.red(VERDICT_WORDS.bug)}: ${shortSteps(finding)}`);
+    }
+}
+/** Follows the same capture until its crawl answers at its budget or ends (amendment 9). Each read is held by the
+ * service until the crawl changes, so there is no pause between reads. No wall-time cap: an interrupt stops waiting
+ * and leaves the crawl running. */
+async function waitForCrawl(first, identity, token) {
     const interrupted = () => {
         console.error('\nStopped waiting. The crawl keeps running; run `haystack verify` again to see it.');
         process.exit(130);
@@ -405,21 +491,27 @@ async function waitForCrawl(first, identity, token, everyMs) {
     process.once('SIGINT', interrupted);
     try {
         let view = first;
+        const printed = new Set();
         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);
+        printNewBugs(view, printed);
+        while (!TERMINAL.has(reportedStatus(view))) {
+            // The followed crawl's own read is held, so only a change to it wakes the wait (Astra review: a capture read could sit up to
+            // 25 s on another title's crawl of the same code).
+            let next = await readCrawlRun(view.runId, identity, token, view.updatedAt);
+            // A newer stop of the same change supersedes this crawl: once it is superseded or being cancelled, the capture's newest crawl
+            // is read at once (not held) and followed if it is this same change.
+            if (next.supersededBy !== null || next.cancelRequested) {
+                const newest = await readCrawl(identity, token);
+                if (newest !== null && sameChange(newest, identity) && newest.runId !== view.runId)
+                    next = newest;
+            }
             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))) {
+            if (!TERMINAL.has(reportedStatus(next)) && (next.runId !== view.runId || currentStep(next) !== currentStep(view))) {
                 progress(currentStep(next));
             }
+            printNewBugs(next, printed);
             view = next;
         }
         return view;
@@ -428,9 +520,14 @@ async function waitForCrawl(first, identity, token, everyMs) {
         process.removeListener('SIGINT', interrupted);
     }
 }
+/** A found crawl of the same code that is a different crawl (another title, another time): a new one starts, none is run again. */
+const anotherCrawl = (stale) => stale === 'retitled' || stale === 'other-time';
+const timeWords = (budgetMs) => budgetMs === null ? 'the default time' : `${budgetMs / 60_000} min`;
 function staleCrawl(found, identity) {
     if (!sameChange(found, identity))
         return 'retitled';
+    if (found.budgetMs !== identity.budgetMs)
+        return 'other-time';
     if (found.status === 'cancelled' || found.status === 'incomplete')
         return found.status;
     return !TERMINAL.has(found.status) && found.cancelRequested ? 'cancelling' : null;
@@ -438,6 +535,7 @@ function staleCrawl(found, identity) {
 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 'other-time': return `The last crawl of this code was asked for ${timeWords(found.budgetMs)} (${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})`;
@@ -445,7 +543,8 @@ function staleWords(found, stale) {
 }
 /** 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. */
+ * when no crawl could be started), whether the base is being onboarded or its
+ * onboarding is blocked, 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
@@ -465,70 +564,129 @@ async function submitCapture(capture, token, found) {
     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'}.` };
+        return { runId: null, onboarding: 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)}.` };
+        return { runId: null, onboarding: null,
+            line: `${before}, and ${found === null ? 'none' : 'another'} could not be started: ${crawlUnavailableText(crawl.reason)}.` };
+    }
+    if (crawl.status === 'onboarding') {
+        return { runId: null, onboarding: 'onboarding', line: `${before}. The app is not onboarded for this base yet: `
+                + `the service is preparing it (${crawl.onboardRunId}) and runs the crawl when it is ready.` };
+    }
+    if (crawl.status === 'onboarding-blocked') {
+        return { runId: null, onboarding: 'onboarding-blocked', line: `${before}, and the app's onboarding for this base is blocked.` };
     }
     if (found === null) {
-        return { runId: crawl.runId, line: crawl.status === 'queued'
+        return { runId: crawl.runId, onboarding: null, 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.` };
+    if (!anotherCrawl(found.stale) && crawl.runId === found.view.runId) {
+        return { runId: crawl.runId, onboarding: null, line: `${before}; asked the service to run it again.` };
     }
-    return { runId: crawl.runId, line: crawl.status === 'queued'
+    return { runId: crawl.runId, onboarding: null, line: crawl.status === 'queued'
             ? `${before}; started one for this change (${crawl.runId}).`
             : `${before}; the service already had one for this change (${crawl.runId}).` };
 }
+function checkedChange(baseCommit, workCommit) {
+    const gitRoot = findGitRoot();
+    if (!gitRoot)
+        throw new Error('Run this command from a git repository.');
+    const files = execFileSync('git', ['diff', '--name-only', '-z', '--no-renames', baseCommit, workCommit], { cwd: gitRoot, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 }).split('\0').filter(path => path !== '');
+    return { baseCommit, workCommit, files };
+}
+/** One line naming what the crawl checks, so an agent knows which edits it covers. */
+function checkedLine(change) {
+    const shown = change.files.slice(0, 5).join(', ');
+    const more = change.files.length > 5 ? ` and ${change.files.length - 5} more` : '';
+    return `Checking ${change.files.length} changed file${change.files.length === 1 ? '' : 's'} against ${change.baseCommit.slice(0, 12)}`
+        + ` (where HEAD meets origin's default branch), committed and uncommitted: ${shown}${more}.`;
+}
+/** Prints the onboarding (and nothing else) as the command's answer: `--json`
+ * carries OnboardingStatusV1. A block exits 3: its ask says what to do. */
+function finishWithOnboarding(status, json, change) {
+    if (json)
+        process.stdout.write(`${JSON.stringify(withSchema('verify', { change, onboarding: status, crawl: null }), null, 2)}\n`);
+    else
+        console.log(formatOnboarding(status));
+    process.exitCode = onboardingExitCode(status);
+}
 export async function verifyCommand(options) {
-    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 capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, repositoryOverride(options.repo), minutesOption(options.minutes));
     const request = capture.derivation.request;
+    const change = checkedChange(request.baseCommit, request.workCommit);
     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`);
+            process.stdout.write(`${JSON.stringify(withSchema('verify', { change, onboarding: null, crawl: null }), null, 2)}\n`);
         return;
     }
+    note(checkedLine(change));
+    // Measured: a 3-minute crawl answered 13 minutes after the command started (building and preparing both apps).
+    note('A crawl often takes 10 to 15 minutes. If this command times out or is stopped, the crawl keeps going:'
+        + ' run `haystack verify` again to pick up the same crawl.');
     const identity = {
         repository: `${request.owner}/${request.repository}`,
         baseCommit: request.baseCommit,
         workCommit: request.workCommit,
         treeSha: request.crawl.treeSha,
         changeTitle: request.crawl.changeTitle,
+        budgetMs: request.crawl.budgetMs ?? null,
     };
     const auth = await resolveAuthContext({ preferredLogin: options.account, owner: request.owner, repo: request.repository });
     let view = await readCrawl(identity, auth.token);
+    let onboarding = null;
     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);
+        let submitted = await submitCapture(capture, auth.token, found);
         note(submitted.line);
+        if (submitted.onboarding !== null) {
+            onboarding = await readOnboardingStatus(identity.repository, identity.baseCommit, auth.token);
+            reportOnboardingState(onboarding);
+            if (options.wait !== false && onboarding.state === 'onboarding') {
+                onboarding = await waitForOnboarding(onboarding, auth.token, progress, 'haystack verify');
+                reportOnboardingState(onboarding);
+            }
+            if (onboarding.state !== 'ready') {
+                finishWithOnboarding(onboarding, options.json, change);
+                return;
+            }
+            // Ready: the service admitted the waiting crawl when the record published; this
+            // submission of the same capture finds it (or starts it, when a newer stop replaced it).
+            note('The app is onboarded for this base.');
+            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.stdout.write(`${JSON.stringify(withSchema('verify', { change, onboarding, 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)) {
+        if (found !== null && !anotherCrawl(found.stale) && 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.wait !== false && !TERMINAL.has(reportedStatus(view))) {
+        view = await waitForCrawl(view, identity, auth.token);
     }
     if (options.json)
-        process.stdout.write(`${JSON.stringify(withSchema('verify', { crawl: view }), null, 2)}\n`);
-    else
+        process.stdout.write(`${JSON.stringify(withSchema('verify', { change, onboarding, crawl: view }), null, 2)}\n`);
+    else {
         console.log(formatCrawl(view));
+        const notes = [...(onboarding?.dataAbsences ?? []), ...(onboarding?.versionChoices ?? [])];
+        if (notes.length)
+            console.log(['', ...notes.map(note => `Note: ${safe(note)}`)].join('\n'));
+    }
     const exitCode = crawlExitCode(view);
     if (exitCode !== 0)
         process.exitCode = exitCode;