@haystackeditor/cli 0.20.0 → 0.22.0

package/dist/commands/verify-onboarding.js

@@ -10,7 +10,7 @@
 import chalk from 'chalk';
 import { withSchema } from '../schema.js';
 import { resolveAuthContext } from '../utils/auth.js';
-import { classifyHttpError, HaystackApiError } from '../utils/haystack-api.js';
+import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, } from '../utils/haystack-api.js';
 import { trackOnboardingEvent } from '../utils/telemetry.js';
 import { gatewayFetch } from './case-batch.js';
 import { ONBOARDING_STAGES, ONBOARDING_VERSION, } from './onboarding-contract.js';
@@ -93,6 +93,8 @@ export function parseOnboardingStatus(value, expected) {
         invalid('its data absences');
     if (!isStrings(value.versionChoices))
         invalid('its version choices');
+    if (!isStrings(value.standIns) || !isStrings(value.unsetProviders))
+        invalid('its stand-ins');
     if (value.block !== null)
         parseOnboardingBlock(value.block);
     const checkpoint = value.checkpoint;
@@ -128,6 +130,9 @@ async function body(response, what) {
         return await response.json();
     }
     catch (error) {
+        // A connection that dropped mid-body is not a bad body: a wait reads again.
+        if (transientReadFailure(error) !== null)
+            throw error;
         throw new OnboardingResponseError(`The onboarding service returned ${what} that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
@@ -159,8 +164,11 @@ const ONBOARDING_READ_EVERY_MS = 15_000;
 const delay = (ms) => new Promise(resolve => setTimeout(resolve, ms));
 /** Polls the base's onboarding until it is no longer running. No wall-time cap:
  * an interrupt stops waiting and leaves the onboarding running (`resume` is the
- * command that follows it again). A momentary 429/5xx (a server or runner
- * restarting) is read again at the next poll. */
+ * command that follows it again). A read that may work if asked again (a 429/5xx
+ * while a server or runner restarts, or no answer at all: a dropped connection
+ * ended a 1 h wait on 2026-10-02 with "fetch failed") is read again at the next
+ * poll, said once per run of failures, until the service has given no answer for
+ * SERVICE_SILENCE_LIMIT_MS (stall detection). */
 export async function waitForOnboarding(first, token, progress, resume) {
     const interrupted = () => {
         console.error(`\nStopped waiting. The onboarding keeps running; run \`${resume}\` again to follow it.`);
@@ -171,6 +179,8 @@ export async function waitForOnboarding(first, token, progress, resume) {
         let status = first;
         progress(`Waiting for onboarding ${status.onboardRunId ?? ''} (Ctrl-C stops waiting; the onboarding keeps running).`);
         progress(onboardingStep(status));
+        let failing = false;
+        let answeredAt = Date.now();
         while (status.state === 'onboarding') {
             await delay(ONBOARDING_READ_EVERY_MS);
             let next;
@@ -178,11 +188,18 @@ export async function waitForOnboarding(first, token, progress, resume) {
                 next = await readOnboardingStatus(status.repository, status.baseCommit, token);
             }
             catch (error) {
-                if (!(error instanceof HaystackApiError && [429, 502, 503, 504].includes(error.status)))
+                const why = transientReadFailure(error);
+                if (why === null)
                     throw error;
-                progress(`The onboarding status is unavailable for now (${error.status}); reading it again.`);
+                if (Date.now() - answeredAt >= SERVICE_SILENCE_LIMIT_MS)
+                    throw new ServiceSilentError('onboarding', resume);
+                if (!failing)
+                    progress(`The onboarding status is unavailable for now (${why}); reading it again.`);
+                failing = true;
                 continue;
             }
+            failing = false;
+            answeredAt = Date.now();
             if (onboardingStep(next) !== onboardingStep(status))
                 progress(onboardingStep(next));
             status = next;
@@ -273,6 +290,9 @@ export function formatOnboarding(status) {
         lines.push('', ...status.dataAbsences.map(absence => chalk.yellow(`Note: ${safe(absence)}`)));
     if (status.versionChoices.length)
         lines.push('', ...status.versionChoices.map(choice => chalk.yellow(`Note: ${safe(choice)}`)));
+    const outside = [...status.standIns, ...status.unsetProviders];
+    if (outside.length)
+        lines.push('', ...outside.map(note => chalk.yellow(`Note: ${safe(note)}`)));
     return lines.join('\n');
 }
 /** Telemetry: onboarding started, blocked or ready, once per state a command sees. */
@@ -351,7 +371,8 @@ export async function verifyOnboardingCommand(options) {
     const origin = resolveOriginRepository(gitRoot);
     const repository = `${origin.owner}/${origin.repository}`;
     const auth = await resolveAuthContext({ preferredLogin: options.account, owner: origin.owner, repo: origin.repository });
-    let status = await readOnboardingStatus(repository, deriveBaseSha(gitRoot, Date.now() + EXPLICIT_WALL_MS), auth.token);
+    const baseCommit = deriveBaseSha(gitRoot, Date.now() + EXPLICIT_WALL_MS);
+    let status = await readWithRetries(() => readOnboardingStatus(repository, baseCommit, auth.token));
     reportOnboardingState(status);
     if (options.wait && status.state === 'onboarding') {
         status = await waitForOnboarding(status, auth.token, line => console.error(chalk.dim(`${clock()} ${line}`)), 'haystack verify onboarding --wait');

package/dist/commands/verify-precompute.js

@@ -262,7 +262,9 @@ async function buildCompressedPatch(gitRoot, baseSha, workCommit, deadline) {
 }
 export async function derivePrecomputeRequest(gitRoot, owner, repository, deadline = Date.now() + HOOK_WALL_MS, 
 /** How long the crawl may take (CRAWL-V1 amendment 8); undefined: the service's default. */
-budgetMs) {
+budgetMs, 
+/** Amendment 12: 'prepare' builds and freezes only (the turn-end hook); 'crawl' is `haystack verify`. */
+mode = 'crawl') {
     // 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();
@@ -290,7 +292,7 @@ budgetMs) {
             cacheKey,
             patchGzBase64: patchGzip.toString('base64'),
             patchSha256: createHash('sha256').update(patchGzip).digest('hex'),
-            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle, ...(budgetMs === undefined ? {} : { budgetMs }) } }),
+            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle, ...(budgetMs === undefined ? {} : { budgetMs }), mode } }),
         },
     };
 }
@@ -333,7 +335,7 @@ function readWalkerStatus(value) {
     }
     throw new PrecomputeFailure('The precompute service returned an invalid walker status.');
 }
-const CRAWL_UNAVAILABLE_REASONS = ['runner-unavailable', 'superseded', 'enqueue-failed'];
+const CRAWL_UNAVAILABLE_REASONS = ['runner-unavailable', 'enqueue-failed'];
 const isOnboardRunId = (value) => typeof value === 'string' && /^ob_[0-9a-f]{48}$/.test(value);
 function readCrawlHookStatus(value) {
     if (value && typeof value === 'object' && !Array.isArray(value)) {
@@ -365,7 +367,6 @@ function readCrawlHookStatus(value) {
 export function crawlUnavailableText(reason) {
     switch (reason) {
         case 'runner-unavailable': return 'no machine that can crawl this repository is available right now';
-        case 'superseded': return 'a newer stop in this repository came first';
         case 'enqueue-failed': return 'the service could not queue it';
     }
 }
@@ -455,14 +456,16 @@ function printResult(result) {
             : 'Walker unavailable: the enqueue request failed.');
     else
         console.log('Walker status was not reported by the service.');
+    // Amendment 12: this capture builds and freezes the app only; `haystack verify` crawls it.
     if (crawl?.status === 'queued')
-        console.log(`Crawl queued (${crawl.runId}).`);
+        console.log(`Building and freezing the app for this change (${crawl.runId}); run \`haystack verify\` to check it.`);
     else if (crawl?.status === 'existing')
-        console.log(`A matching crawl already exists (${crawl.runId}).`);
+        console.log(`This change is already built or being built (${crawl.runId}); run \`haystack verify\` to check it.`);
     else if (crawl?.status === 'unavailable')
         console.log(`Crawl unavailable: ${crawlUnavailableText(crawl.reason)}.`);
     else if (crawl?.status === 'onboarding') {
-        console.log(`The app is being onboarded for this base (${crawl.onboardRunId}); the crawl runs when it is ready. Run \`haystack verify\` to follow it.`);
+        console.log(`The app is being onboarded for this base (${crawl.onboardRunId}); this change is built and frozen when it is ready.`
+            + ' Run `haystack verify` to check it.');
     }
     else if (crawl?.status === 'onboarding-blocked')
         console.log(blockLines(crawl.block).join('\n'));
@@ -485,7 +488,9 @@ function configuredCrawlMinutes(gitRoot) {
     }
     return minutes;
 }
-export async function captureCheckout(deadline, repository, 
+export async function captureCheckout(deadline, 
+/** Amendment 12: the turn-end hook and `verify precompute` ask to prepare (build and freeze); `haystack verify` to crawl. */
+mode, repository, 
 /** `haystack verify --minutes`; undefined: the repository's .haystack.json crawl.minutes, else the service's default. */
 minutes) {
     const gitRoot = findGitRoot();
@@ -495,7 +500,7 @@ minutes) {
     const metadataDirectory = walkerMetadataDirectory(gitRoot, deadline);
     const target = repository ?? resolveOriginRepository(gitRoot);
     const chosen = minutes ?? configuredCrawlMinutes(gitRoot);
-    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline, chosen === undefined ? undefined : chosen * 60_000);
+    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline, chosen === undefined ? undefined : chosen * 60_000, mode);
     return { metadataDirectory, derivation };
 }
 /** The explicit (non-hook) submission of a capture: one synchronous
@@ -533,7 +538,8 @@ export async function verifyPrecomputeCommand(options) {
     const deadline = startedAt + totalWallMs;
     let outcome = 'error';
     try {
-        const capture = await captureCheckout(deadline);
+        // The hook and an explicit precompute build and freeze the change ahead of `haystack verify`; they never crawl it.
+        const capture = await captureCheckout(deadline, 'prepare');
         if (options.hook) {
             remainingMs(deadline);
             await startPrecomputeDelivery(capture.metadataDirectory, capture.derivation.request);

package/dist/commands/verify.js

@@ -26,7 +26,7 @@ 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 { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, } from '../utils/haystack-api.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';
@@ -36,8 +36,8 @@ const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
 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'];
-const TERMINAL = new Set(['completed', 'incomplete', 'cancelled']);
+const STATUSES = ['queued', 'preparing', 'crawling', 'draining', 'completed', 'prepared', 'incomplete', 'cancelled'];
+const TERMINAL = new Set(['completed', 'prepared', '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'];
@@ -50,6 +50,7 @@ const STATUS_WORDS = {
     crawling: 'exploring the app',
     draining: 'finishing the last checks',
     completed: 'finished',
+    prepared: 'built and ready to check',
     incomplete: 'stopped before finishing',
     cancelled: 'cancelled',
 };
@@ -213,7 +214,7 @@ export function parseCrawlView(value, expected) {
         || 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')
+        || typeof value.cancelRequested !== 'boolean' || (value.mode !== 'prepare' && value.mode !== 'crawl'))
         invalid('its status');
     const clocks = value.clocks;
     if (!isRecord(clocks) || !['startedAt', 'stageStartedAt', 'crawlStartedAt', 'finishedAt']
@@ -259,6 +260,9 @@ async function responseBody(response) {
         return await response.json();
     }
     catch (error) {
+        // A connection that dropped mid-body is not a bad body: a wait reads again.
+        if (transientReadFailure(error) !== null)
+            throw error;
         throw new CrawlResponseError(`The crawl service returned a body that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
@@ -333,13 +337,15 @@ function headline(view) {
             const error = results(view)?.error ?? view.error;
             return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
         }
+        case 'prepared':
+            // Amendment 12: the turn-end hook built and froze this change; `haystack verify` asks for the crawl itself.
+            return 'Your change is built and ready to check, but was not crawled yet. Run `haystack verify` to check it.';
         case 'cancelled':
-            return `The crawl was cancelled${view.supersededBy ? ': a newer stop in this repository replaced it' : ''}.${found}`;
+            return `The crawl was cancelled.${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 `Being cancelled: ${currentStep(view)}.${so}`;
             }
             return `Still running: ${currentStep(view)}.${so}`;
         }
@@ -482,7 +488,11 @@ function printNewBugs(view, printed) {
 }
 /** 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. */
+ * and leaves the crawl running. A read that may work if asked again (transientReadFailure) is asked again after
+ * TRANSIENT_READ_PAUSE_MS, said once per run of failures: one dropped connection used to end the command. Only a
+ * service that has given no answer for SERVICE_SILENCE_LIMIT_MS stops the wait (stall detection). */
+/** The pause before a followed crawl is read again after a read that may work if asked again. */
+const TRANSIENT_READ_PAUSE_MS = 5_000;
 async function waitForCrawl(first, identity, token) {
     const interrupted = () => {
         console.error('\nStopped waiting. The crawl keeps running; run `haystack verify` again to see it.');
@@ -495,17 +505,36 @@ async function waitForCrawl(first, identity, token) {
         progress(`Waiting for crawl ${view.runId} (Ctrl-C stops waiting; the crawl keeps running).`);
         progress(currentStep(view));
         printNewBugs(view, printed);
+        let failing = false;
+        let answeredAt = Date.now();
         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;
+            let next;
+            try {
+                // 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).
+                next = await readCrawlRun(view.runId, identity, token, view.updatedAt);
+                // Once this crawl is being cancelled, the capture's newest crawl is read at once (not held) and followed if it is this
+                // same change (amendment 12: no crawl replaces another, but one can be cancelled and asked for again).
+                if (next.cancelRequested) {
+                    const newest = await readCrawl(identity, token);
+                    if (newest !== null && sameChange(newest, identity) && newest.runId !== view.runId)
+                        next = newest;
+                }
             }
+            catch (error) {
+                const why = transientReadFailure(error);
+                if (why === null)
+                    throw error;
+                if (Date.now() - answeredAt >= SERVICE_SILENCE_LIMIT_MS)
+                    throw new ServiceSilentError('crawl', 'haystack verify');
+                if (!failing)
+                    progress(`The crawl's status is unavailable for now (${why}); reading it again.`);
+                failing = true;
+                await new Promise(resolve => setTimeout(resolve, TRANSIENT_READ_PAUSE_MS));
+                continue;
+            }
+            failing = false;
+            answeredAt = Date.now();
             if (next.runId !== view.runId)
                 progress(`A newer crawl of this same change took over (${next.runId}).`);
             if (!TERMINAL.has(reportedStatus(next)) && (next.runId !== view.runId || currentStep(next) !== currentStep(view))) {
@@ -530,7 +559,10 @@ function staleCrawl(found, identity) {
         return 'other-time';
     if (found.status === 'cancelled' || found.status === 'incomplete')
         return found.status;
-    return !TERMINAL.has(found.status) && found.cancelRequested ? 'cancelling' : null;
+    if (!TERMINAL.has(found.status) && found.cancelRequested)
+        return 'cancelling';
+    // A `prepared` run is asked for its crawl whatever its mode (a cancel can leave a widened one prepared).
+    return found.mode === 'prepare' || found.status === 'prepared' ? 'prepare-only' : null;
 }
 function staleWords(found, stale) {
     switch (stale) {
@@ -539,6 +571,9 @@ function staleWords(found, stale) {
         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})`;
+        case 'prepare-only': return found.status === 'prepared'
+            ? `Your change was built and frozen ahead of time (${found.runId})`
+            : `Your change is being built and frozen ahead of time (${found.runId})`;
     }
 }
 /** Submits the capture through the explicit precompute submission when no crawl
@@ -546,21 +581,9 @@ function staleWords(found, stale) {
  * 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
-    // 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 {
-            acknowledgment = await postPrecomputeCapture(capture, token, Date.now() + EXPLICIT_WALL_MS);
-        }
-        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]));
-        }
-    }
+    // A momentary 429/5xx or a dropped connection (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 acknowledgment = await readWithRetries(() => postPrecomputeCapture(capture, token, Date.now() + EXPLICIT_WALL_MS)).catch((error) => { throw normalModeFailure(error); });
     const crawl = acknowledgment.crawl;
     const before = found === null ? 'No crawl existed for this change' : staleWords(found.view, found.stale);
     if (crawl === undefined) {
@@ -584,7 +607,8 @@ async function submitCapture(capture, token, found) {
                 : `The service already had a crawl for this change (${crawl.runId}).` };
     }
     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, onboarding: null, line: found.stale === 'prepare-only'
+                ? `${before}; checking it now, reusing what was built.` : `${before}; asked the service to run it again.` };
     }
     return { runId: crawl.runId, onboarding: null, line: crawl.status === 'queued'
             ? `${before}; started one for this change (${crawl.runId}).`
@@ -619,7 +643,7 @@ export async function verifyCommand(options) {
         console.error(line);
     else
         console.log(line); };
-    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, repositoryOverride(options.repo), minutesOption(options.minutes));
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'crawl', repositoryOverride(options.repo), minutesOption(options.minutes));
     const request = capture.derivation.request;
     const change = checkedChange(request.baseCommit, request.workCommit);
     if (!request.crawl) {
@@ -641,7 +665,8 @@ export async function verifyCommand(options) {
         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);
+    // One-shot reads ask again after a failure that may work if asked again, as the waits do.
+    let view = await readWithRetries(() => readCrawl(identity, auth.token));
     let onboarding = null;
     const stale = view === null ? null : staleCrawl(view, identity);
     if (view === null || stale !== null) {
@@ -649,7 +674,7 @@ export async function verifyCommand(options) {
         let submitted = await submitCapture(capture, auth.token, found);
         note(submitted.line);
         if (submitted.onboarding !== null) {
-            onboarding = await readOnboardingStatus(identity.repository, identity.baseCommit, auth.token);
+            onboarding = await readWithRetries(() => 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');
@@ -671,7 +696,8 @@ export async function verifyCommand(options) {
             process.exitCode = 1;
             return;
         }
-        view = await readCrawlRun(submitted.runId, identity, auth.token);
+        const runId = submitted.runId;
+        view = await readWithRetries(() => readCrawlRun(runId, identity, auth.token));
         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.');
         }
@@ -683,7 +709,8 @@ export async function verifyCommand(options) {
         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 ?? [])];
+        const notes = [...(onboarding?.dataAbsences ?? []), ...(onboarding?.versionChoices ?? []), ...(onboarding?.standIns ?? []),
+            ...(onboarding?.unsetProviders ?? [])];
         if (notes.length)
             console.log(['', ...notes.map(note => `Note: ${safe(note)}`)].join('\n'));
     }

package/dist/index.js

@@ -153,7 +153,8 @@ repository already keeps working. init shows each change as a diff, then makes
 it with --yes (or a yes at the prompt):
   • Claude Code's Stop hook (\`haystack verify precompute --hook\`) in the
     per-developer .claude/settings.local.json, kept out of commits, when
-    Claude Code is in use here
+    Claude Code is in use here: it builds and freezes the changed app ahead
+    of time, so \`haystack verify\` starts from there
   • a short note in AGENTS.md (and CLAUDE.md when the repository keeps one)
     telling coding agents to run \`haystack verify\` after a change
 Then it starts onboarding the app, so it is usually ready by the first
@@ -264,10 +265,9 @@ Exit codes:
   0  the crawl answered or finished (the bugs it found are in the output), or
      it is still running and --no-wait was given
   1  the command failed, or no crawl could be started for this change
-  2  the crawl ended without finishing: it stopped early or was cancelled
-     (a newer stop in the repository replaces an older crawl), or the
-     machines it used could not be proven shut down; or onboarding stopped
-     before finishing
+  2  the crawl ended without finishing: it stopped early or was cancelled,
+     or the machines it used could not be proven shut down; or onboarding
+     stopped before finishing
   3  onboarding is blocked: the output says what would unblock it
 
 The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
@@ -367,7 +367,7 @@ Examples:
 });
 verify
     .command('precompute')
-    .description('Precompute reusable verification inputs for the current working tree')
+    .description('Build and freeze the current working tree\'s app ahead of `haystack verify` (no crawl)')
     .option('--hook', 'Run silently as a best-effort repository hook')
     .action(async (options) => {
     await runPublicCommand(async () => {
@@ -1359,7 +1359,8 @@ hooks
 Configures your coding CLI to run \`haystack triage --hook\` on session start.
 This shows pending PR analysis results when you open a new terminal session.
 Claude Code also runs \`haystack verify precompute --hook\` when a session stops,
-which starts a crawl of the change in the background (see \`haystack verify\`).
+which builds and freezes the changed app in the background so that
+\`haystack verify\` starts from there. It never crawls; \`haystack verify\` does.
 
   Claude Code:  Native SessionStart and Stop hooks (.claude/settings.local.json;
                 --shared writes the committed .claude/settings.json)

package/dist/utils/haystack-api.js

@@ -25,6 +25,70 @@ export class HaystackApiError extends Error {
         return this.status === 401 || this.status === 403;
     }
 }
+/** The network failures fetch (undici) reports as its TypeError's `cause.code`: the connection refused, reset, dropped,
+ * unreachable or timed out, or the name not resolved for now. A request it could not even build (ERR_INVALID_URL) is not one. */
+const TRANSPORT_FAILURE_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'ECONNABORTED', 'EPIPE', 'ETIMEDOUT', 'ENETUNREACH',
+    'ENETDOWN', 'EHOSTUNREACH', 'EHOSTDOWN', 'EAI_AGAIN', 'ENOTFOUND', 'UND_ERR_SOCKET', 'UND_ERR_CLOSED',
+    'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT']);
+/**
+ * Why a read failed in a way that asking again may fix, or null when it did not: the service or a runner restarting
+ * (429, 502, 503, 504), no answer at all (fetch's TypeError whose cause is one of TRANSPORT_FAILURE_CODES), or a request
+ * past its own deadline (TimeoutError). A wait loop reads again on these; anything else (sign-in, a bad request, a request
+ * that could not be built, a bug) is the caller's to report.
+ */
+export function transientReadFailure(error) {
+    if (error instanceof HaystackApiError)
+        return [429, 502, 503, 504].includes(error.status) ? `HTTP ${error.status}` : null;
+    if (error instanceof Error && error.name === 'TimeoutError')
+        return 'no answer in time';
+    return error instanceof TypeError ? transportCause(error.cause, 0) : null;
+}
+/** The transport failure somewhere in a fetch TypeError's cause chain. A connection dropped while the body is read fails as
+ * TypeError "terminated", whose cause may be the socket error or the request's TimeoutError (Bugbot, #3760); several
+ * addresses tried at once (IPv4 and IPv6) fail as one AggregateError. */
+function transportCause(cause, depth) {
+    if (!(cause instanceof Error) || depth > 4)
+        return null;
+    if (cause.name === 'TimeoutError')
+        return 'no answer in time';
+    const code = cause.code;
+    if (typeof code === 'string' && TRANSPORT_FAILURE_CODES.has(code))
+        return `no answer: ${code}`;
+    if (cause instanceof AggregateError) {
+        for (const inner of cause.errors) {
+            const found = transportCause(inner, depth + 1);
+            if (found !== null)
+                return found;
+        }
+    }
+    return transportCause(cause.cause, depth + 1);
+}
+/** How long a wait keeps asking while the service gives no answer, counted from its last answer. Stall detection, not a
+ * cap on the work: a service that answers is followed for as long as the work runs. */
+export const SERVICE_SILENCE_LIMIT_MS = 10 * 60_000;
+/** A wait stopped because the service gave no answer for SERVICE_SILENCE_LIMIT_MS (a dead network, a wrong
+ * HAYSTACK_API_BASE, a long outage); the work it was following keeps running on the service. */
+export class ServiceSilentError extends Error {
+    constructor(work, resume) {
+        super(`Haystack has not answered for ${SERVICE_SILENCE_LIMIT_MS / 60_000} minutes; the ${work} keeps running on the service. `
+            + `Run \`${resume}\` again to follow it.`);
+        this.name = 'ServiceSilentError';
+    }
+}
+/** A one-shot read, asked again after a failure that may work if asked again (transientReadFailure), at most three more times. */
+export async function readWithRetries(read) {
+    const pauses = [2_000, 5_000, 10_000];
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            return await read();
+        }
+        catch (error) {
+            if (transientReadFailure(error) === null || attempt >= pauses.length)
+                throw error;
+            await new Promise(resolve => setTimeout(resolve, pauses[attempt]));
+        }
+    }
+}
 function headers(token, extra) {
     const result = new Headers(extra);
     result.set('Authorization', `Bearer ${token}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {