@haystackeditor/cli 0.19.0 → 0.21.0

package/dist/commands/verify-precompute.js

@@ -13,6 +13,7 @@ import { trackPrecomputeEvent } from '../utils/telemetry.js';
 import { findSecretsInPatch, isSecretBearingPath } from '../utils/secret-paths.js';
 import { startPrecomputeDelivery } from './precompute-delivery.js';
 import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
+import { blockLines, parseOnboardingBlock } from './verify-onboarding.js';
 // --hook has five seconds to capture the exact source and publish local custody.
 // Its detached sender owns the bounded network delivery and acknowledgement.
 // An explicit invocation still waits synchronously for the server response.
@@ -66,7 +67,7 @@ function gitOutput(args, gitRoot, deadline, options = {}) {
         throw new PrecomputeFailure('Could not derive the repository snapshot.');
     }
 }
-function resolveOriginRepository(gitRoot) {
+export function resolveOriginRepository(gitRoot) {
     try {
         const remote = parseRemoteUrl('origin');
         if (!isRepositoryComponent(remote.owner)
@@ -80,8 +81,8 @@ function resolveOriginRepository(gitRoot) {
         throw new PrecomputeFailure('No supported origin repository was found.');
     }
 }
-/** The shared base rule (utils/verify-base.ts), bounded by the hook's deadline. */
-function deriveBaseSha(gitRoot, deadline) {
+/** The shared base rule (utils/verify-base.ts), bounded by the caller's deadline. */
+export function deriveBaseSha(gitRoot, deadline) {
     try {
         return resolveVerifyBaseSha('HEAD', {
             run: (args, options) => gitOutput(args, gitRoot, deadline, options?.remote
@@ -261,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();
@@ -289,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 } }),
         },
     };
 }
@@ -332,7 +335,8 @@ function readWalkerStatus(value) {
     }
     throw new PrecomputeFailure('The precompute service returned an invalid walker status.');
 }
-const CRAWL_UNAVAILABLE_REASONS = ['not-configured', 'runner-unavailable', 'profile-ambiguous', '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)) {
         const record = value;
@@ -343,6 +347,18 @@ function readCrawlHookStatus(value) {
             const reason = CRAWL_UNAVAILABLE_REASONS.find(known => known === record.reason);
             if (record.status === 'unavailable' && reason !== undefined)
                 return { status: record.status, reason };
+            // Crawl amendment 8: the base has no published onboarding record yet.
+            if (record.status === 'onboarding' && isOnboardRunId(record.onboardRunId))
+                return { status: 'onboarding', onboardRunId: record.onboardRunId };
+        }
+        if (Object.keys(record).length === 3 && record.status === 'onboarding-blocked'
+            && (record.onboardRunId === null || isOnboardRunId(record.onboardRunId))) {
+            try {
+                return { status: 'onboarding-blocked', onboardRunId: record.onboardRunId, block: parseOnboardingBlock(record.block) };
+            }
+            catch (error) {
+                throw new PrecomputeFailure(`The precompute service returned an invalid onboarding block (${error instanceof Error ? error.message : String(error)}).`);
+            }
         }
     }
     throw new PrecomputeFailure('The precompute service returned an invalid crawl status.');
@@ -350,10 +366,7 @@ function readCrawlHookStatus(value) {
 /** Why the service could not start a crawl, in plain words. */
 export function crawlUnavailableText(reason) {
     switch (reason) {
-        case 'not-configured': return 'this repository is not set up for crawling yet';
         case 'runner-unavailable': return 'no machine that can crawl this repository is available right now';
-        case 'profile-ambiguous': return 'the machines that crawl this repository disagree about how to run it';
-        case 'superseded': return 'a newer stop in this repository came first';
         case 'enqueue-failed': return 'the service could not queue it';
     }
 }
@@ -443,12 +456,19 @@ 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}); 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'));
     else
         console.log('Crawl status was not reported by the service.');
 }
@@ -468,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();
@@ -478,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
@@ -516,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

@@ -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
@@ -13,21 +14,30 @@
  * 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 { 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';
 /** 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'];
-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'];
@@ -40,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',
 };
@@ -73,7 +84,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',
@@ -202,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']
@@ -322,13 +334,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}`;
         }
@@ -336,7 +350,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)
@@ -486,9 +502,9 @@ async function waitForCrawl(first, identity, token) {
             // 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) {
+            // 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;
@@ -517,7 +533,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) {
@@ -526,11 +545,15 @@ 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
  * 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
@@ -550,37 +573,75 @@ 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 (!anotherCrawl(found.stale) && crawl.runId === found.view.runId) {
-        return { runId: crawl.runId, 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, 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) {
     // 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), 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) {
         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,
@@ -591,14 +652,32 @@ export async function verifyCommand(options) {
     };
     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;
         }
@@ -611,9 +690,13 @@ export async function verifyCommand(options) {
         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;

package/dist/index.js

@@ -6,7 +6,7 @@
  * Automated PR review, triage, and merge queue for AI-assisted development.
  *
  * Usage:
- *   npx @haystackeditor/cli init           # Set up .haystack.json
+ *   npx @haystackeditor/cli init           # Set this repository up for `haystack verify`
  *   npx @haystackeditor/cli setup          # Interactive onboarding wizard
  *   npx @haystackeditor/cli status         # Check configuration
  *   npx @haystackeditor/cli login          # Authenticate with GitHub
@@ -133,7 +133,7 @@ function getVersion() {
 const program = new Command();
 program
     .name('haystack')
-    .description('Haystack CLI — automated PR review, triage, and merge queue')
+    .description('Haystack CLI — haystack verify runs your app with and without a change and shows what it broke')
     .version(getVersion())
     // commander 13 made surplus positional arguments an error; the CLI has always
     // ignored them. Every command created below inherits this setting.
@@ -144,18 +144,39 @@ program
     .action((name) => (name ? schemaCommand(name) : listSchemas()));
 program
     .command('init')
-    .description('Create .haystack.json configuration')
-    .option('-f, --force', 'Overwrite existing .haystack.json')
+    .description('Set this repository up for `haystack verify` and start onboarding the app')
+    .option('-y, --yes', 'Make the changes without asking')
+    .option('--json', 'The result as one JSON document on stdout (see `haystack schema init`)')
     .addHelpText('after', `
-This creates a .haystack.json file with auto-detected settings:
-  • Dev server command and port
-  • Services (for monorepos)
-  • Auth bypass for CI environments
+There is no setup file: Haystack works out how to run the app from what the
+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: 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
+\`haystack verify\`. Running it again changes only what is missing and shows
+where onboarding is (\`haystack verify onboarding\` shows that too).
 
-After running, use \`haystack setup\` to scan your repos for rules,
-CI signals, and review policies.
+Exit codes:
+  0  set up: onboarding is running or the app is ready
+  1  the command failed
+  2  changes were shown but not made: run \`haystack init --yes\`
+  3  onboarding is blocked: the output says what would unblock it
+  4  not logged in: run \`haystack login\`
+  5  the Haystack GitHub App is not installed on the repository's owner:
+     the output links to it
+  6  set up, but onboarding stopped before finishing: run \`haystack init\` again
+
+Examples:
+  haystack init
+  haystack init --yes
+  haystack init --yes --json
 `)
-    .action(initCommand);
+    .action(options => runPublicCommand(() => initCommand(options), options.json));
 program
     .command('setup')
     .description('Onboarding wizard — scan repos for rules/policies and write Haystack config')
@@ -233,13 +254,21 @@ changed spot, how far the crawl got with it, and the steps that reached it),
 what the crawl found (bugs first, with the steps to see each), and the changed
 code it never ran.
 
+The first verify on a base the service has not onboarded yet prepares the app
+(reads the repository, plans how to run it, builds its runtime, starts it,
+prepares its data and test accounts, proves a workflow); the command shows each
+step, and the crawl runs once the app is ready. When onboarding cannot go on it
+says why and what would unblock it, for example a question to answer with
+\`haystack verify answer <question-id> <choice>\`.
+
 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
+  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\`.
 
@@ -273,6 +302,49 @@ function verifyCommandOptions(command) {
     }
     return options;
 }
+verify
+    .command('answer')
+    .description('Answer a question onboarding asked about your app, then run `haystack init` to continue')
+    .argument('<question-id>', 'The question id onboarding printed')
+    .argument('<choice>', 'One of the question\'s choices, exactly as printed')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'The repository\'s onboarding facts after the answer, as one JSON document')
+    .addHelpText('after', `
+An answer is a fact about your app (never setup); onboarding plans from it the
+next time it runs, so \`haystack init\` or a new \`haystack verify\` continues
+from there.
+
+Example:
+  haystack verify answer q_<id> "postgres 15 (terraform/db.tf)"
+`)
+    .action(async (questionId, choice, _options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyAnswerCommand } = await import('./commands/verify-onboarding.js');
+    return runPublicCommand(() => verifyAnswerCommand(questionId, choice, options), options.json);
+});
+verify
+    .command('onboarding')
+    .description('Show where onboarding of this checkout\'s base is, without starting anything')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--wait', 'Follow onboarding until it is ready, blocked or stopped')
+    .option('--json', 'The onboarding as one JSON document (see `haystack schema verify-onboarding`)')
+    .addHelpText('after', `
+Reads the onboarding of the base \`haystack verify\` would use for this
+checkout. \`haystack init\` starts it; so does the first \`haystack verify\`.
+
+Exit codes:
+  0  the app is ready, or onboarding is running
+  1  the command failed
+  2  onboarding has not started, stopped before finishing, or was cancelled:
+     \`haystack init\` starts it again
+  3  onboarding is blocked: the output says what would unblock it
+`)
+    .action(async (_options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyOnboardingCommand } = await import('./commands/verify-onboarding.js');
+    return runPublicCommand(() => verifyOnboardingCommand(options), options.json);
+});
 verify
     .command('history')
     .description('Read your recent finished hosted verification runs without starting a run')
@@ -295,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 () => {
@@ -570,6 +642,15 @@ program
     .option('--label <name>', '(--headless) Label to display in the dashboard for this token')
     .option('--scope <repos>', '(--headless) Comma-separated repos to scope the token to (or "all")', (val) => val.split(',').map((s) => s.trim()).filter(Boolean))
     .option('--token <hsk_live_...>', '(--headless) Skip the browser handshake — paste a token minted in the dashboard')
+    .option('--no-wait', 'Print the sign-in URL and code and return; the next `haystack login` finishes signing in')
+    .option('--json', 'The sign-in (URL and code, or the account signed in) as one JSON document (see `haystack schema login`)')
+    .addHelpText('after', `
+Signing in uses GitHub's device flow: open the URL, enter the code. A coding
+agent runs \`haystack login --no-wait\`, shows the person the URL and code, and
+then runs \`haystack login\`, which waits until the code is entered. A login
+stopped while it waits is finished the same way, with the same code, until
+GitHub expires it.
+`)
     .action(async (opts) => {
     if (opts.headless) {
         try {
@@ -581,7 +662,7 @@ program
         }
         return;
     }
-    return loginCommand();
+    return loginCommand({ wait: opts.wait, json: opts.json });
 });
 program
     .command('logout [login]')
@@ -1278,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)
@@ -1531,15 +1613,6 @@ fleetPolicy
     const { fleetPolicyHistoryCommand } = await import('./commands/fleet-policy.js');
     await runAdminCommand(() => fleetPolicyHistoryCommand(repository, options));
 });
-fleetPolicy
-    .command('import-kv')
-    .description('One time: import the KV policies and tenant overrides into D1')
-    .option('--dry-run', 'Report what would be imported without writing')
-    .option(workerUrlOption, workerUrlHelp)
-    .action(async (options) => {
-    const { fleetPolicyImportKvCommand } = await import('./commands/fleet-policy.js');
-    await runAdminCommand(() => fleetPolicyImportKvCommand(options));
-});
 // ─── rules ───────────────────────────────────────────────────────────────────
 const rules = program.command('rules').description('Manage .haystack/pr-rules.yml');
 rules

package/dist/schema.js

@@ -20,7 +20,11 @@ export const SCHEMA_VERSIONS = {
     action: '1.0.0',
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '1.0.0',
+    verify: '1.0.2',
+    'verify-answer': '1.0.0',
+    'verify-onboarding': '1.0.0',
+    init: '1.0.0',
+    login: '1.0.0',
     error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/utils/config.js

@@ -42,22 +42,6 @@ export async function loadConfig(configPath) {
         throw new Error(`Failed to parse ${resolvedPath}: ${err.message}`);
     }
 }
-/**
- * Save config to file
- */
-export async function saveConfig(config, configPath) {
-    const resolvedPath = configPath || path.join(process.cwd(), CONFIG_FILENAME);
-    const content = JSON.stringify(config, null, 2);
-    await fs.writeFile(resolvedPath, content, 'utf-8');
-    return resolvedPath;
-}
-/**
- * Check if config exists
- */
-export async function configExists(startDir) {
-    const configPath = await findConfigPath(startDir);
-    return configPath !== null;
-}
 /**
  * Get the project root (directory containing .haystack.json or current dir)
  */