@haystackeditor/cli 0.20.0 → 0.21.0

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

@@ -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']
@@ -333,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}`;
         }
@@ -499,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;
@@ -530,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) {
@@ -539,6 +545,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
@@ -584,7 +593,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 +629,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) {

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/package.json

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