@haystackeditor/cli 0.27.1 → 0.27.3

package/README.md

@@ -41,10 +41,13 @@ or `HAYSTACK_TELEMETRY_DISABLED=1` to turn this telemetry off.
 
 Most users of this CLI are coding agents. What to know:
 
-- **After a change, run `haystack verify`** inside the checkout. Nothing needs
-  to be committed or pushed. Say what you were asked to do with
-  `--intent "<the task, in the user's words>"`, and what to try with
-  `--idea "<as you would tell a tester>"` (repeat it for more).
+- **After a change, two steps** inside the checkout (nothing needs to be
+  committed or pushed):
+  1. `haystack pre-verify` shows what the change touches, what production and
+     real users do there, and Haystack's ideas of what could break.
+  2. `haystack verify --intent "<the task, in the user's words>" --idea "<as you
+     would tell a tester>"` explores the app with your steering: keep the ideas
+     worth trying, add your own (repeat `--idea`); yours are explored first.
 - **First time in a repository**, `haystack init --yes` sets it up and starts
   onboarding the app. `haystack verify onboarding` shows where onboarding is.
   When onboarding asks a question, answer it with
@@ -74,10 +77,11 @@ It then finds your crawl of that exact capture: the same code and the same
 change title (HEAD's subject, which tells the crawl's judge what the change is;
 committing or rewording keeps the code but changes the title). When there is
 none, or the one it finds was cancelled, stopped before finishing or is being
-cancelled, it submits the capture through the same request `haystack verify
-precompute` sends (the service starts the crawl, or runs the stopped one again
-once it has shut down), says so in one line, and follows the crawl the service
-acknowledged; it never shows a crawl of another revision or another title.
+cancelled, or the stop hook only built it, it asks the service for the crawl
+(the service starts it, runs the stopped one again once it has shut down, or
+turns the hook's prepared run into a crawl that starts from the app the hook
+already built), says so in one line, and follows that crawl; 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
@@ -108,18 +112,20 @@ up, what became of each idea, and what never ran (`haystack schema verify`).
 it is large (`haystack schema verify-raw`). Exit codes: 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;
+without finishing (stopped early, or cancelled) or the machines it used could
+not be proven shut down;
 1 when the command failed or no crawl could be started.
 
 **The stop hook.** `haystack init` installs a Claude Code Stop hook that runs
 `haystack verify precompute --hook` whenever an agent turn stops. It captures
-the checkout within five seconds and hands the request to a detached sender;
-the service then starts the change's crawl in the background, so
-`haystack verify` usually finds the crawl already running or finished. A newer
-stop in the same repository replaces an older crawl that has not finished.
-`haystack verify precompute` (without `--hook`) submits the same capture in the
-foreground and prints one line for the crawl it started.
+the checkout within five seconds and hands the request to a detached sender.
+The service then builds the app with and without the change, works out what
+the change touches (the brief `haystack pre-verify` prints) and sets up starting
+points next to it, and stops there: it never crawls. `haystack verify` then
+crawls from that prepared app instead of building it again. No run cancels
+another: each runs to its end unless it is cancelled. `haystack verify precompute`
+(without `--hook`) submits the same capture in the foreground and prints one
+line for the run it started.
 
 Retained fleet cases remain available through their exact case IDs:
 

package/dist/commands/init.js

@@ -45,16 +45,21 @@ export const AGENT_NOTE = [
     NOTE_BEGIN,
     '## Haystack',
     '',
-    'After you change this app\'s code, or when the user asks you to check a change, run `haystack verify` before you',
-    'call the work done. It runs the app with and without the change, explores it, and reports where the change shows up',
-    'and what broke. It changes nothing, so run it without asking.',
+    'After you change this app\'s code, or when the user asks you to check a change, check it with Haystack before you call',
+    'the work done. It runs the app with and without the change, explores it, and reports what broke. It changes nothing,',
+    'so run it without asking.',
     '',
-    '- It often takes 10 to 15 minutes: give it your longest timeout or run it in the background, and do not pipe it',
+    '1. `haystack pre-verify`: what your change touches, what production and real users do there, and Haystack\'s ideas',
+    '   of what could break.',
+    '2. `haystack verify --intent "<what you were asked to do, in the user\'s words>" --idea "<something to try>"`: keep the',
+    '   ideas worth trying, add your own (repeat --idea); yours are explored first.',
+    '',
+    '- `verify` often takes 10 to 15 minutes: give it your longest timeout or run it in the background, and do not pipe it',
     '  through `tail` or `head`, which hide its progress. If your command times out, run it again: it picks up the same crawl.',
     '- Fix each bug it reports that your change caused, then run `haystack verify` again.',
     '- If it says onboarding needs an answer, ask the user that question and file their choice with',
     '  `haystack verify answer <question-id> <choice>`.',
-    '- Read its short report. `--json` prints the same report as data; `--raw` prints the crawl\'s whole record (large), for scripts;',
+    '- Read verify\'s short report. `--json` prints the same report as data; `--raw` prints the crawl\'s whole record (large), for scripts;',
     '  `haystack verify --help` explains the output and exit codes.',
     '- If `haystack` is not installed, run each command as `npx -y -p @haystackeditor/cli@latest haystack <command>`.',
     '- If Haystack fails, confuses you or gets in your way, say so in a sentence with',
@@ -511,7 +516,8 @@ export async function initCommand(options) {
     }
     let onboarding;
     try {
-        // The notes first: onboarding plans from the facts it starts with, and new notes are new facts (a new onboarding).
+        // The notes first: onboarding plans from the facts it starts with (rule 2, amendment 34: new notes onboard again only while
+        // the repository has no setup, after a run that ended without one).
         if (notes) {
             notesWritten = await writeOnboardingNotes(repository, notes, token);
             say(notesWritten === 'written' ? chalk.green('✓ Wrote the onboarding notes') : chalk.dim('The onboarding notes are already these.'));
@@ -529,6 +535,14 @@ export async function initCommand(options) {
         const done = plan.changes.length > 0 ? 'The changes above were made, but onboarding' : 'Onboarding';
         throw new Error(`${done} could not start: ${error instanceof Error ? error.message : String(error)} Run \`haystack init\` again to start it.`);
     }
+    // New notes for an app that is already set up change nothing about its setup (rule 2, amendment 34: each app is set up once).
+    // Said in words, and in --json's notices for the coding agent, which otherwise reads "notes: written" as a new onboarding
+    // (Codex on langgenius/dify, 2026-10-07).
+    if (notesWritten === 'written' && onboarding.state === 'ready') {
+        const notice = 'The app is already set up, so these notes do not change its setup: Haystack sets each app up once and keeps the notes.';
+        plan.notices.push(notice);
+        say(chalk.dim(notice));
+    }
     reportOnboardingState(onboarding);
     say(formatOnboarding(onboarding));
     say('');

package/dist/commands/verify-onboarding.js

@@ -106,6 +106,13 @@ export function parseOnboardingStatus(value, expected) {
         invalid('its review');
     if (value.state !== 'ready' && review !== null)
         invalid('its review');
+    // Rule 2 (amendment 34): a ready status names the base its record was made at and when it was published.
+    const ready = value.state === 'ready';
+    if (ready ? !(typeof value.recordBaseCommit === 'string' && COMMIT.test(value.recordBaseCommit)) : value.recordBaseCommit !== null)
+        invalid('its record base');
+    if (ready ? !(typeof value.recordPublishedAt === 'string' && !Number.isNaN(Date.parse(value.recordPublishedAt)))
+        : value.recordPublishedAt !== null)
+        invalid('its record time');
     if (value.block !== null)
         parseOnboardingBlock(value.block);
     const checkpoint = value.checkpoint;
@@ -147,8 +154,8 @@ async function body(response, what) {
         throw new OnboardingResponseError(`The onboarding service returned ${what} that is not JSON: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
-/** The onboarding of `repository` at `baseCommit`, now; with `onboardRunId`, that run's (or the run a derivation change moved
- * it to), whatever derivation is live: what a waiting command follows. */
+/** The onboarding of `repository`, asked at `baseCommit` (rule 2, amendment 34: one setup per repository, the same at every
+ * base); with `onboardRunId`, that run's, or the repository's record once it has one: what a waiting command follows. */
 export async function readOnboardingStatus(repository, baseCommit, token, onboardRunId = null) {
     if (!COMMIT.test(baseCommit))
         throw new Error(`Invalid base commit ${baseCommit}.`);
@@ -159,7 +166,7 @@ export async function readOnboardingStatus(repository, baseCommit, token, onboar
         throw await classifyHttpError(response, `Haystack API ${path}`);
     return parseOnboardingStatus(await body(response, 'a status'), { repository, baseCommit });
 }
-/** Rule 12's start POST: onboard this base now, before any change exists. Idempotent: a
+/** Rule 12's start POST: onboard the repository now, at this base, before any change exists. Idempotent: a
  * ready, blocked or running onboarding is answered as it is. */
 export async function startOnboarding(repository, baseCommit, token) {
     if (!COMMIT.test(baseCommit))
@@ -198,8 +205,7 @@ export async function waitForOnboarding(first, token, progress, resume) {
             await delay(ONBOARDING_READ_EVERY_MS);
             let next;
             try {
-                // The run this wait follows, not the base under whatever derivation is live: a release swap mid-wait otherwise reads
-                // not-started while the run goes on to admit this command's crawl (galaxy's n8n replays, 2026-10-03).
+                // The run this wait follows, until the repository has a record.
                 next = await readOnboardingStatus(status.repository, status.baseCommit, token, status.onboardRunId);
             }
             catch (error) {
@@ -282,16 +288,16 @@ export function blockLines(block) {
     return lines;
 }
 export function formatOnboarding(status) {
-    const lines = [chalk.dim(`  Onboarding ${status.onboardRunId ?? '(none)'} of ${safe(status.repository)} at base ${status.baseCommit.slice(0, 12)}`)];
+    const lines = [chalk.dim(`  Onboarding ${status.onboardRunId ?? '(none)'} of ${safe(status.repository)}, asked at base ${status.baseCommit.slice(0, 12)}`)];
     switch (status.state) {
         case 'ready':
-            lines.push('The app is onboarded for this base.');
+            lines.push(readyLine(status));
             break;
         case 'onboarding':
             lines.push(onboardingStep(status));
             break;
         case 'not-started':
-            lines.push('Onboarding has not started for this base. `haystack init` starts it.');
+            lines.push('Onboarding has not started for this repository. `haystack init` starts it.');
             break;
         case 'incomplete':
             lines.push(`Onboarding stopped before finishing${status.checkpoint?.error ? `: ${safe(status.checkpoint.error.message)}` : ''}.`
@@ -319,6 +325,20 @@ export function formatOnboarding(status) {
         lines.push('', ...unreviewed.map(note => chalk.yellow(`Note: ${safe(note)}`)));
     return lines.join('\n');
 }
+/** Rule 2 (amendment 34): the repository's one setup, which base it was made at and how long ago, in one sentence. */
+export function readyLine(status, now = Date.now()) {
+    if (status.recordBaseCommit === null || status.recordPublishedAt === null)
+        return 'The app is onboarded.';
+    return `The app is onboarded: its setup was made at base ${status.recordBaseCommit.slice(0, 12)} `
+        + `${age(now - Date.parse(status.recordPublishedAt))} and serves every base.`;
+}
+/** "just now", "5 minutes ago", "3 hours ago", "2 days ago". */
+function age(ms) {
+    const minutes = Math.floor(Math.max(0, ms) / 60_000);
+    const [count, unit] = minutes < 1 ? [0, ''] : minutes < 60 ? [minutes, 'minute'] : minutes < 2_880 ? [Math.floor(minutes / 60), 'hour']
+        : [Math.floor(minutes / 1_440), 'day'];
+    return count === 0 ? 'just now' : `${count} ${unit}${count === 1 ? '' : 's'} ago`;
+}
 /** Rule 17 (amendment 32): an onboarding the independent review skipped, as the sentence every result shows; none otherwise. */
 export function reviewNotes(review) {
     if (review?.verdict !== 'skipped')
@@ -397,7 +417,7 @@ export async function verifyAnswerCommand(questionId, choice, options) {
     }
 }
 /** Makes the coding agent's notes the repository's onboarding notes (rule 7, amendment 18), unless they are exactly these
- * already: 'unchanged' then, so running init again with the same notes starts no new onboarding. */
+ * already: 'unchanged' then, so running init again with the same notes changes no facts. */
 export async function writeOnboardingNotes(repository, notes, token) {
     for (let attempt = 1;; attempt += 1) {
         const facts = await readFacts(repository, token);

package/dist/commands/verify-precompute.js

@@ -486,7 +486,7 @@ function printResult(result) {
     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.`
+        console.log(`The app is being onboarded (${crawl.onboardRunId}); this change is built and frozen when it is ready.`
             + ' Run `haystack verify` to check it.');
     }
     else if (crawl?.status === 'onboarding-blocked')

package/dist/commands/verify.js

@@ -32,7 +32,7 @@ import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
 import { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_IDEAS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_MAX_TEXT_CHARS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
 import { SPOT_WORDS, TERMINAL, VERDICT_WORDS, VERDICTS, currentStep, errorWords, headline, plural, reportedStatus, results, verifyReport, } from './crawl-report.js';
-import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
+import { formatOnboarding, onboardingExitCode, readOnboardingStatus, readyLine, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
 import { formatCapture, readPreVerifyCapture } from './capture-brief.js';
 /** 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;
@@ -660,11 +660,11 @@ async function submitCapture(capture, token, found) {
             line: `${before}, and ${found === null ? 'one' : '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: `
+        return { runId: null, onboarding: 'onboarding', line: `${before}. The app is not onboarded 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.` };
+        return { runId: null, onboarding: 'onboarding-blocked', line: `${before}, and the app's onboarding is blocked.` };
     }
     if (found === null) {
         return { runId: crawl.runId, onboarding: null, line: crawl.status === 'queued'
@@ -834,9 +834,12 @@ export function formatBrief(brief) {
                 lines.push(`    ${safe(change.changeKey)}: ${safe(change.reason)}`);
         }
     }
-    lines.push('', 'Next: pick the ideas worth trying, add your own, and say what you were asked to do (the task in the user\'s words, not what your code does):', '  haystack verify --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]', 'Your ideas are explored first; the ideas above are explored in every crawl too.');
     return lines.join('\n');
 }
+/** The handshake's question, asked after everything pre-verify shows. */
+const STEER_LINES = ['', 'Next: pick the ideas worth trying, add your own, and say what you were asked to do (the task in the user\'s words, not what your code does):',
+    '  haystack verify --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]',
+    'Your ideas are explored first; the ideas above are explored in every crawl too.'];
 /** `haystack pre-verify` (CRAWL-V1 amendment 18): the brief of the current change, before any crawl. It captures the checkout as
  * the turn-end hook does, prepares it when no run of that capture is under way or done (it never widens a run to a crawl), and
  * prints the run's brief. Exit codes: 0 with a brief, 2 when the run ended without one, 3 onboarding blocked, 1 otherwise. */
@@ -886,7 +889,7 @@ export async function preVerifyCommand(options) {
                 process.exitCode = onboardingExitCode(onboarding);
                 return;
             }
-            note('The app is onboarded for this base.');
+            note(readyLine(onboarding));
             submitted = await submitCapture(capture, auth.token, found);
             note(submitted.line);
         }
@@ -920,6 +923,8 @@ export async function preVerifyCommand(options) {
     if (!options.json && captured !== null)
         for (const section of captured)
             console.log(`\n${formatCapture(section)}`);
+    if (!options.json && brief !== null)
+        console.log(STEER_LINES.join('\n'));
     if (brief === null && TERMINAL.has(reportedStatus(view)))
         process.exitCode = 2;
 }
@@ -981,9 +986,9 @@ export async function verifyCommand(options) {
                 finishWithOnboarding(onboarding, options, 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.');
+            // Ready: the service admitted the waiting crawl when the record published (amendment 12:
+            // every waiting request is admitted); this submission of the same capture finds it.
+            note(readyLine(onboarding));
             submitted = await submitCapture(capture, auth.token, found);
             note(submitted.line);
         }

package/dist/index.js

@@ -119,7 +119,9 @@ an hour). The file is JSON with any of three notes, each plain text:
   signIn    how a person gets an account and signs in, and the kinds of users
   workflow  what a signed-in user mainly does, step by step
 Leave out what you do not know. Onboarding still proves everything it takes
-from the notes. New notes start a new onboarding; the same notes again do not.
+from the notes. The app is onboarded once: notes written before that feed its
+onboarding (an onboarding that stopped on a question starts again with them);
+after it, new notes start no onboarding.
 
 Every run also plans telemetry for the app: --app names it when the repository
 has several (init never picks one), --origin its production origins and
@@ -180,7 +182,8 @@ your crawl of that exact capture: the same code and the same change title (the
 title tells the crawl's judge what the change is). When there is none, or the
 one it finds was cancelled, stopped before finishing or is being cancelled, it
 submits the capture (the service starts the crawl, or runs the stopped one
-again), says so, and follows that crawl.
+again), says so, and follows that crawl. When the stop hook already built and
+froze this change, the crawl starts from that instead of building it again.
 
 The coding agent that made the change can say what it was asked to do (--intent:
 the task in the user's words, not a description of its code) and what to try (--idea, as many as it likes, or --ideas-file). Each idea is

package/package.json

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