@haystackeditor/cli 0.18.0 → 0.19.0

package/README.md

@@ -106,8 +106,11 @@ acknowledged; it never shows a crawl of another revision or another title.
 A crawl builds the app with and without your change, starts from the changed
 code, reaches it in the running app, explores outward with both builds side by
 side, and double-checks and judges every difference. `haystack verify` waits
-until the crawl finishes, printing each step as it happens; there is no time
-limit, and Ctrl-C stops waiting, never the crawl. It then prints:
+for the crawl, printing each step as it happens and each bug the moment the
+crawl finds it (each read is held by the service until the crawl changes, so
+nothing waits on a polling interval). It finishes when the crawl answers, as
+soon as its time is up, without waiting for its machines to shut down; there
+is no time limit, and Ctrl-C stops waiting, never the crawl. It then prints:
 
 - a headline: how many bugs it found, none, or why the crawl could not finish;
 - **Where your change shows up in the app**: every changed spot as
@@ -120,14 +123,15 @@ limit, and Ctrl-C stops waiting, never the crawl. It then prints:
 - **What the crawl never ran**: changed files no path ran, and how many of the
   functions your change affects ran.
 
-`--no-wait` prints the crawl's current state and returns. `--interval
-<seconds>` sets the polling interval (default 5), `--account <login>` picks a
-saved account, and `--repo owner/repo` names the repository when `origin` does
-not. `--json` prints one document, `{ "schema_version", "crawl" }`, where
-`crawl` is the crawl as the service returns it (or `null` when no crawl of the
-capture could be started); `haystack schema verify` prints its schema. Exit codes
-follow `haystack case-batch status`: 0 when the crawl finished (the bugs it
-found are in the output) or is still running under `--no-wait`; 2 when it ended
+`--no-wait` prints the crawl's current state and returns. `--account <login>`
+picks a saved account, and `--repo owner/repo` names the repository when
+`origin` does not. `--json` prints one document, `{ "schema_version", "crawl" }`,
+where `crawl` is the crawl as the service returns it, with its `answer` (what it
+found so far, or its answer once its time is up) while no sealed `manifest`
+exists (or `null` when no crawl of the capture could be started);
+`haystack schema verify` prints its schema. Exit codes follow
+`haystack case-batch status`: 0 when the crawl answered or finished (the bugs
+it found are in the output) or is still running under `--no-wait`; 2 when it ended
 without finishing (stopped early, or cancelled because a newer stop in the
 repository replaced it) or the machines it used could not be proven shut down;
 1 when the command failed or no crawl could be started.

package/dist/commands/case-batch.js

@@ -90,6 +90,8 @@ function requireRunId(runId) {
     }
     return runId;
 }
+/** How long any gateway request may take unless its caller says otherwise. */
+export const GATEWAY_TIMEOUT_MS = 120_000;
 /** Every outbound request. The header set is built here and nowhere else, so
  * the credential surface of this command is one line: the login bearer.
  * `haystack verify` reads crawls through this same client. */
@@ -104,7 +106,7 @@ export async function gatewayFetch(path, token, init = { method: 'GET' }) {
         method: init.method,
         headers,
         ...(init.body === undefined ? {} : { body: init.body }),
-        signal: AbortSignal.timeout(120_000),
+        signal: AbortSignal.timeout(init.timeoutMs ?? GATEWAY_TIMEOUT_MS),
     });
 }
 async function gatewayJson(path, token, init = { method: 'GET' }) {

package/dist/commands/crawl-contract.js

@@ -1,3 +1,9 @@
 export const CRAWL_TITLE_MAX_CHARS = 200;
+/** Amendment 8: the time a crawl may be asked to take, whole seconds from 1 to 30 minutes. */
+export const CRAWL_BUDGET_MIN_MS = 60_000;
+export const CRAWL_BUDGET_MAX_MS = 30 * 60_000;
 export const CRAWL_MAX_FINDINGS = 50;
 export const CRAWL_MAX_FINDING_STEPS = 64;
+/** Amendment 9: what a crawl has found so far (`exploring`) or its answer at the budget (`answered`), before the sealed manifest;
+ * findings carry no images. A read may pass `waitAfter=<updatedAt>` to be held until the crawl changes (at most CRAWL_WAIT_MAX_MS). */
+export const CRAWL_WAIT_MAX_MS = 25_000;

package/dist/commands/precompute-delivery.js

@@ -3,7 +3,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
+import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
 const requestFile = 'request.json';
 const receiptFile = 'receipt.json';
 const deliverySchema = 'precompute-delivery-v1';
@@ -150,10 +150,13 @@ function validateRequest(value) {
             throw new Error('Invalid captured crawl submission.');
         return;
     }
-    if (!object(crawl) || !onlyKeys(crawl, ['treeSha', 'changeTitle'])
+    // Amendment 8: budgetMs only when the capture asked for a time, whole seconds from 1 to 30 minutes.
+    if (!object(crawl) || !onlyKeys(crawl, 'budgetMs' in crawl ? ['treeSha', 'changeTitle', 'budgetMs'] : ['treeSha', 'changeTitle'])
         || !characters(crawl.treeSha, '0123456789abcdef', 40)
         || request.cacheKey.split('-')[2] !== crawl.treeSha.slice(0, 16)
-        || typeof crawl.changeTitle !== 'string' || crawl.changeTitle.length > CRAWL_TITLE_MAX_CHARS) {
+        || typeof crawl.changeTitle !== 'string' || crawl.changeTitle.length > CRAWL_TITLE_MAX_CHARS
+        || ('budgetMs' in crawl && (typeof crawl.budgetMs !== 'number' || !Number.isInteger(crawl.budgetMs) || crawl.budgetMs % 1000 !== 0
+            || crawl.budgetMs < CRAWL_BUDGET_MIN_MS || crawl.budgetMs > CRAWL_BUDGET_MAX_MS))) {
         throw new Error('Invalid captured crawl submission.');
     }
 }

package/dist/commands/verify-precompute.js

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { closeSync, constants, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { closeSync, constants, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { createGzip } from 'node:zlib';
 import { isAbsolute, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -12,7 +12,7 @@ import { HaystackApiError, haystackJson, REPO_NOT_ENTITLED_CODE, SUBSCRIPTION_RE
 import { trackPrecomputeEvent } from '../utils/telemetry.js';
 import { findSecretsInPatch, isSecretBearingPath } from '../utils/secret-paths.js';
 import { startPrecomputeDelivery } from './precompute-delivery.js';
-import { CRAWL_TITLE_MAX_CHARS } from './crawl-contract.js';
+import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_TITLE_MAX_CHARS } from './crawl-contract.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.
@@ -259,7 +259,9 @@ async function buildCompressedPatch(gitRoot, baseSha, workCommit, deadline) {
         child.stdout.pipe(gzip);
     });
 }
-export async function derivePrecomputeRequest(gitRoot, owner, repository, deadline = Date.now() + HOOK_WALL_MS) {
+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) {
     // 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();
@@ -287,7 +289,7 @@ export async function derivePrecomputeRequest(gitRoot, owner, repository, deadli
             cacheKey,
             patchGzBase64: patchGzip.toString('base64'),
             patchSha256: createHash('sha256').update(patchGzip).digest('hex'),
-            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle } }),
+            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle, ...(budgetMs === undefined ? {} : { budgetMs }) } }),
         },
     };
 }
@@ -452,14 +454,31 @@ function printResult(result) {
 }
 /** The hook, an explicit precompute and `haystack verify` all capture here.
  * The repository defaults to origin's, as the hook's does. */
-export async function captureCheckout(deadline, repository) {
+/** The repository's crawl time: .haystack.json crawl.minutes at the git root, whole minutes from 1 to 30 (CRAWL-V1 amendment 8),
+ * or undefined when the file or the field is absent. A value out of range fails the capture, never silently becomes the default. */
+function configuredCrawlMinutes(gitRoot) {
+    const path = join(gitRoot, '.haystack.json');
+    if (!existsSync(path))
+        return undefined;
+    const minutes = JSON.parse(readFileSync(path, 'utf8')).crawl?.minutes;
+    if (minutes === undefined)
+        return undefined;
+    if (typeof minutes !== 'number' || !Number.isInteger(minutes) || minutes * 60_000 < CRAWL_BUDGET_MIN_MS || minutes * 60_000 > CRAWL_BUDGET_MAX_MS) {
+        throw new PrecomputeFailure(`.haystack.json crawl.minutes must be a whole number from ${CRAWL_BUDGET_MIN_MS / 60_000} to ${CRAWL_BUDGET_MAX_MS / 60_000}.`);
+    }
+    return minutes;
+}
+export async function captureCheckout(deadline, repository, 
+/** `haystack verify --minutes`; undefined: the repository's .haystack.json crawl.minutes, else the service's default. */
+minutes) {
     const gitRoot = findGitRoot();
     if (!gitRoot) {
         throw new PrecomputeFailure('Run this command from a git repository.');
     }
     const metadataDirectory = walkerMetadataDirectory(gitRoot, deadline);
     const target = repository ?? resolveOriginRepository(gitRoot);
-    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline);
+    const chosen = minutes ?? configuredCrawlMinutes(gitRoot);
+    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline, chosen === undefined ? undefined : chosen * 60_000);
     return { metadataDirectory, derivation };
 }
 /** The explicit (non-hook) submission of a capture: one synchronous

package/dist/commands/verify.js

@@ -8,20 +8,22 @@
  * 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`.
  */
 import chalk from 'chalk';
 import { withSchema } from '../schema.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError, HaystackApiError } from '../utils/haystack-api.js';
-import { gatewayFetch } from './case-batch.js';
-import { CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, } from './crawl-contract.js';
+import { 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';
 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'];
@@ -136,21 +138,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 +172,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 +223,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 +251,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 +272,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 +303,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':
@@ -311,15 +353,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 +374,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 +438,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 +478,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 +507,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 +522,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})`;
@@ -475,7 +560,7 @@ async function submitCapture(capture, token, found) {
                 ? `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) {
+    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, line: crawl.status === 'queued'
@@ -483,13 +568,12 @@ async function submitCapture(capture, token, found) {
             : `${before}; the service already had one for this change (${crawl.runId}).` };
 }
 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;
     if (!request.crawl) {
         note(`Nothing to verify: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
@@ -503,6 +587,7 @@ export async function verifyCommand(options) {
         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);
@@ -518,12 +603,12 @@ export async function verifyCommand(options) {
             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`);

package/dist/index.js

@@ -208,7 +208,7 @@ const verify = program
     .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
     .option('--account <login>', 'Use a specific saved Haystack account')
     .option('--no-wait', 'Print the crawl\'s current state and return without waiting')
-    .option('--interval <seconds>', 'Polling interval while waiting (default 5)')
+    .option('--minutes <n>', 'How long the crawl may take, 1-30 (default: .haystack.json crawl.minutes, else 3)')
     .option('--json', 'The crawl as one JSON document on stdout (see `haystack schema verify`)')
     .addHelpText('after', `
 Run inside a git checkout; nothing needs to be committed or pushed. It captures
@@ -222,15 +222,20 @@ again), says so, and follows that crawl.
 
 A crawl builds the app with and without your change, starts from the changed
 code, explores outward with both side by side, and double-checks and judges
-every difference. The command waits until the crawl finishes, printing each
-step; Ctrl-C stops waiting, never the crawl. It then prints where your change
-shows up in the app (each 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.
+every difference it can within its time: 3 minutes unless the repository's
+.haystack.json sets crawl.minutes or --minutes says otherwise (1 to 30).
+Differences it had no time to check are listed as not finished in time. The
+command waits for the crawl, printing each step and each bug the moment the
+crawl finds it; it finishes when the crawl answers, as soon as its time is up,
+without waiting for the crawl's machines to shut down. Ctrl-C stops waiting,
+never the crawl. It then prints where your change shows up in the app (each
+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.
 
 Exit codes:
-  0  the crawl finished (the bugs it found are in the output), or it is
-     still running and --no-wait was given
+  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
@@ -241,6 +246,7 @@ The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
 Examples:
   haystack verify
   haystack verify --no-wait
+  haystack verify --minutes 10
   haystack verify --json
   haystack verify history owner/repo --limit 20
   haystack verify hosted status cv_<48 lowercase hex characters> --wait

package/dist/types.js

@@ -294,6 +294,9 @@ const PreferencesSchema = z.object({
 export const HaystackConfigSchema = z.object({
     /** Config version (must be "1") */
     version: z.literal('1'),
+    /** Hosted crawls of this repository (`haystack verify`, the stop hook): how long one may take, whole minutes from 1 to 30.
+     * Absent: the service's default (3 minutes). `haystack verify --minutes` overrides it for one run. */
+    crawl: z.object({ minutes: z.number().int().min(1).max(30).optional() }).strict().optional(),
     /** Project name (for display) */
     name: z.string().optional(),
     /** Repository-level Haystack behavior */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Set up Haystack for your project — automated PR review, triage, and merge queue",
   "type": "module",
   "bin": {

package/schemas/verify.v1.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://docs.haystackeditor.com/cli/schemas/verify.v1.json",
   "title": "Haystack verify: the crawl of the current change (CRAWL-V1)",
-  "description": "Machine-readable output of `haystack verify --json`: the caller's crawl of the exact captured checkout (its code and its change title), as GET /api/agent/cloud-verifier/crawls?repository=&workCommit= or, for a crawl the command just submitted, GET /api/agent/cloud-verifier/crawls/:runId?repository= returns it, or null when no crawl of the capture could be started. The crawl shapes mirror infra/lambda/haystack-design-verifier-shared/crawl_contracts.ts (with amendment 1); that file wins where they differ.",
+  "description": "Machine-readable output of `haystack verify --json`: the caller's crawl of the exact captured checkout (its code and its change title), as GET /api/agent/cloud-verifier/crawls?repository=&workCommit= or, for a crawl the command just submitted, GET /api/agent/cloud-verifier/crawls/:runId?repository= returns it, or null when no crawl of the capture could be started. The crawl shapes mirror infra/lambda/haystack-design-verifier-shared/crawl_contracts.ts (with amendments 1, 8 and 9); that file wins where they differ.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "crawl"],
@@ -97,8 +97,8 @@
         "findingIds": { "$ref": "#/$defs/strings" }
       }
     },
-    "manifest": {
-      "description": "Present once the crawl is terminal and published.",
+    "results": {
+      "description": "The published results' shape, shared by the sealed manifest and an answer; each sets its own status.",
       "type": "object",
       "required": ["schemaVersion", "runId", "attemptId", "repository", "baseCommit", "workCommit", "treeSha",
         "changeTitle", "status", "worlds", "reuse", "timings", "bugs", "findings", "reach", "notFinishedInTime", "error"],
@@ -111,7 +111,6 @@
         "workCommit": { "$ref": "#/$defs/commit" },
         "treeSha": { "$ref": "#/$defs/commit" },
         "changeTitle": { "type": "string", "maxLength": 200 },
-        "status": { "enum": ["completed", "incomplete", "cancelled"] },
         "worlds": {
           "oneOf": [
             { "type": "null" },
@@ -157,10 +156,27 @@
         "error": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/error" }] }
       }
     },
+    "manifest": {
+      "description": "Present once the crawl is terminal and published.",
+      "allOf": [{ "$ref": "#/$defs/results" }],
+      "properties": {
+        "status": { "enum": ["completed", "incomplete", "cancelled"] }
+      }
+    },
+    "answer": {
+      "description": "CRAWL-V1 amendment 9: the current attempt's latest answer while no sealed manifest exists: what the crawl found so far (exploring), or its answer once its time is up (answered), with the same findings and reach the sealed manifest will carry. Its findings carry no images.",
+      "allOf": [{ "$ref": "#/$defs/results" }],
+      "required": ["n", "atSeconds"],
+      "properties": {
+        "status": { "enum": ["exploring", "answered"] },
+        "n": { "type": "integer", "minimum": 1, "description": "The attempt's answers are numbered from 1." },
+        "atSeconds": { "type": "integer", "minimum": 0, "description": "How far into the crawl stage it was written." }
+      }
+    },
     "crawlView": {
       "type": "object",
-      "required": ["runId", "repository", "baseCommit", "workCommit", "treeSha", "changeTitle", "observedAt",
-        "createdAt", "updatedAt", "supersededBy", "cancelRequested", "manifest", "status", "stage", "clocks",
+      "required": ["runId", "repository", "baseCommit", "workCommit", "treeSha", "changeTitle", "budgetMs", "observedAt",
+        "createdAt", "updatedAt", "supersededBy", "cancelRequested", "manifest", "answer", "status", "stage", "clocks",
         "reuse", "worlds", "totals"],
       "properties": {
         "runId": { "$ref": "#/$defs/runId" },
@@ -169,6 +185,8 @@
         "workCommit": { "$ref": "#/$defs/commit" },
         "treeSha": { "$ref": "#/$defs/commit" },
         "changeTitle": { "type": "string", "maxLength": 200 },
+        "budgetMs": { "description": "The time the crawl was asked for (ms), or null for the service's default.",
+          "oneOf": [{ "type": "null" }, { "type": "integer", "minimum": 60000, "maximum": 1800000 }] },
         "observedAt": { "$ref": "#/$defs/count" },
         "createdAt": { "type": "string", "format": "date-time" },
         "updatedAt": { "type": "string", "format": "date-time" },
@@ -210,7 +228,9 @@
           }
         },
         "error": { "$ref": "#/$defs/error" },
-        "manifest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/manifest" }] }
+        "manifest": { "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/manifest" }] },
+        "answer": { "description": "Null once the sealed manifest exists, and before the crawl's first answer.",
+          "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/answer" }] }
       }
     }
   }