@haystackeditor/cli 0.28.1 → 0.30.1

package/README.md

@@ -43,9 +43,12 @@ Most users of this CLI are coding agents. What to know:
 
 - **After a change, two steps** inside the checkout (nothing needs to be
   committed or pushed):
-  1. `haystack verify` is the handshake: it shows what the change touches, what
-     production and real users do there, and Haystack's ideas of what could
-     break, then asks you to steer (exit 4).
+  1. `haystack verify` is the handshake: it shows what the change touches
+     (first its flows, the behaviors it changes), what production and real
+     users do there, and Haystack's ideas of what could break, then asks you to
+     steer (exit 4). `haystack verify flow <n>` drills into one flow: its code,
+     the pages it shows on with their real use, and what its code saw in
+     production.
   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.
@@ -115,7 +118,9 @@ 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) or the machines it used could
 not be proven shut down;
-1 when the command failed or no crawl could be started.
+1 when the command failed or no crawl could be started; 3 when onboarding is
+blocked; 4 for the handshake (run it again with `--intent`); 5 when the app
+copy is broken and the change could not be tested.
 
 **The stop hook.** `haystack init` installs a Claude Code Stop hook that runs
 `haystack verify precompute --hook` whenever an agent turn stops. It captures

package/dist/commands/capture-brief.js

@@ -28,7 +28,7 @@ function captureApplication(gitRoot, app) {
         return { unreadable: `${file} names no valid applicationId` };
     return { applicationId: config.applicationId };
 }
-async function readApp(gitRoot, app, repository, token, files, now) {
+async function readAppWindow(gitRoot, app, repository, token) {
     const application = captureApplication(gitRoot, app);
     if ('unreadable' in application)
         return { app, applicationId: null, state: 'unavailable', reason: application.unreadable };
@@ -43,15 +43,14 @@ async function readApp(gitRoot, app, repository, token, files, now) {
             throw new Error('the capture window answer names another application');
         if (answer.window === null)
             return { app, applicationId, state: 'no-data' };
-        return { app, applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
+        return { app, applicationId, state: 'ready', window: answer.window };
     }
     catch (error) {
         return { app, applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
     }
 }
-/** The handshake capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
- * files and the changed files. */
-export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+/** Each app's capture window, one per app with a record, or null for a checkout with none. */
+export async function readCaptureWindows(gitRoot, repository, token) {
     let apps;
     try {
         apps = captureConfigDirs(gitRoot, []);
@@ -61,7 +60,18 @@ export async function readPreVerifyCapture(gitRoot, repository, token, files, no
     }
     if (apps.length === 0)
         return null;
-    return Promise.all(apps.map(app => readApp(gitRoot, app, repository, token, files, now)));
+    return Promise.all(apps.map(app => readAppWindow(gitRoot, app, repository, token)));
+}
+/** The handshake capture sections from the apps' windows: the routes `files` serve (the brief's function files and the changed
+ * files), with their share of captured sessions. */
+export function preVerifyCapture(windows, files, now) {
+    return windows === null ? null : windows.map(app => app.state === 'ready'
+        ? { app: app.app, applicationId: app.applicationId, state: 'ready', window: captureChangedRoutes(app.window, files, now) } : app);
+}
+/** The handshake capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
+ * files and the changed files. */
+export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+    return preVerifyCapture(await readCaptureWindows(gitRoot, repository, token), files, now);
 }
 const percent = (share) => share === null ? 'n/a' : `${(share * 100).toFixed(1)}%`;
 const plain = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' '); // eslint-disable-line no-control-regex

package/dist/commands/crawl-contract.js

@@ -15,8 +15,13 @@ export const CRAWL_WAIT_MAX_MS = 25_000;
  * (how many times the copy's calls reached the stand-in across the crawl's preparation and all its replays, not user actions). */
 export const CRAWL_MAX_STAND_IN_ROWS = 200;
 export const CRAWL_MAX_STAND_IN_LINES = 20;
+/** Amendment 22: each health evidence list holds at most this many lines, and the commonest difference lines at most this many. */
+export const CRAWL_HEALTH_MAX_LINES = 40;
+export const CRAWL_HEALTH_MAX_DIFFERENCES = 8;
 /** Amendment 18: the brief's bounds. */
 export const CRAWL_BRIEF_MAX_FUNCTIONS = 2000;
 export const CRAWL_BRIEF_MAX_GROUPS = 2000;
 /** Amendment 19: rows one brief function keeps per kind of production evidence (the rest counted). */
 export const CRAWL_BRIEF_MAX_PRODUCTION_ROWS = 100;
+/** Amendment 21: a flow's name, at most this many characters. */
+export const CRAWL_BRIEF_MAX_FLOW_NAME_CHARS = 120;

package/dist/commands/crawl-report.js

@@ -11,7 +11,7 @@ export const STATUS_WORDS = {
     cancelled: 'cancelled',
 };
 export const STAGE_WORDS = {
-    reconcile: 'cleaning up after an earlier try',
+    reconcile: 'checking for leftovers of an earlier try',
     source: 'rebuilding your change',
     worlds: 'building and starting the app with and without your change',
     blast: 'waiting for the analysis of what your change touches',
@@ -66,6 +66,38 @@ export function currentStep(view) {
 export function results(view) {
     return view.manifest ?? (view.answer?.status === 'answered' ? view.answer : null);
 }
+/** CRAWL-V1 amendment 22: the copy of the app the crawl ran was itself broken, so it tested nothing; null when it was not judged
+ * broken (or the results carry no health). */
+export function brokenCopy(view) {
+    const health = results(view)?.health;
+    return health !== undefined && health.status === 'app-broken' ? health : null;
+}
+/** What `haystack verify` says first of a broken copy. */
+export const BROKEN_COPY_HEADLINE = "We couldn't test your change: the app copy is broken.";
+/** What the coding agent does about a broken copy: the app's own setup says what the errors need; until a broken copy updates its
+ * setup (onboarding amendment 38 updates it only from a check that could not start the app), that is sent to the Haystack team
+ * (`haystack feedback`), and the user is told the change was not tested. */
+export const BROKEN_COPY_STEPS = [
+    "Find what these errors point to in the repository's own setup (docker compose files, env examples, docs): the services, settings and data the app needs to run.",
+    'Send what you found with `haystack feedback "<what the app needs to run>"`: a copy that starts but is broken does not update its setup yet.',
+    'Tell your user this check did not test the change; do not read it as passing.',
+];
+/** Text that reads as an error, for the lines a broken copy's start screen shows (every one is in --raw). */
+const ERROR_LIKE = /\b(?:errors?|fail(?:ed|s|ure)?|unsupported|exception|denied|refused|unavailable|unauthori[sz]ed|forbidden|invalid|cannot|can't|could not|unable|timed out|timeout|not found|internal server)\b/iu;
+/** What a broken copy's evidence says, as lines: what its start screen shows (its messages, then its texts that read as errors),
+ * and the requests that failed and the console errors logged with nobody clicking, each with the builds it was in. */
+export function brokenCopyEvidence(health) {
+    const { evidence } = health;
+    const shows = [...new Set([...evidence.messages, ...evidence.texts.filter(text => ERROR_LIKE.test(text))])];
+    const idle = (kind) => {
+        const of = (lines) => lines.filter(line => line.startsWith(`${kind}:`)).map(line => line.slice(kind.length + 1));
+        const old = of(evidence.background.old);
+        const fresh = of(evidence.background.new);
+        return [...new Set([...old, ...fresh])].map(entry => `${entry} (${old.includes(entry) && fresh.includes(entry) ? 'both builds'
+            : old.includes(entry) ? 'without your change only' : 'with your change only'})`);
+    };
+    return { shows, failedRequests: idle('failed'), consoleErrors: idle('errors') };
+}
 /** 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. */
 export function reportedStatus(view) {
@@ -76,9 +108,21 @@ export function headline(view) {
     const found = bugs > 0 ? ` It found ${plural(bugs, 'bug')} before it stopped.` : '';
     switch (reportedStatus(view)) {
         case 'completed':
+            // Amendment 22: a broken copy tested nothing, whatever it found.
+            if (brokenCopy(view) !== null)
+                return BROKEN_COPY_HEADLINE;
             return bugs > 0 ? `Found ${plural(bugs, 'bug')} in your change.` : 'No bugs found in your change.';
         case 'incomplete': {
             const error = results(view)?.error ?? view.error;
+            // Onboarding rule 18 (amendment 38): which world did not start says whose it is, and what Haystack does about it.
+            if (error?.code === 'world-build-failed' && view.worlds.base === null) {
+                return 'The crawl could not finish: the app did not build or start at the base commit, on its setup. Haystack updates the '
+                    + 'setup for it and runs this check again (`haystack verify onboarding` shows the update).';
+            }
+            if (error?.code === 'world-build-failed' && view.worlds.head === null) {
+                return 'The crawl could not finish: your change did not build or start, though the base did. Haystack checks whether the change '
+                    + 'needs something new in the setup and, if it does, adds it and runs this check again (`haystack verify onboarding` shows it).';
+            }
             return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
         }
         case 'prepared':
@@ -137,6 +181,9 @@ export function verifyReport(view) {
         } : null,
         notFinishedInTime: explored ? published.notFinishedInTime : 0,
         outsideServiceGaps: explored ? published.standIns?.gaps ?? [] : [],
+        health: !explored || published.health === undefined ? null : published.health.status === 'app-broken'
+            ? { status: 'app-broken', reason: published.health.reason, ...brokenCopyEvidence(published.health), whatToDo: [...BROKEN_COPY_STEPS] }
+            : { status: published.health.status, reason: published.health.reason, shows: [], failedRequests: [], consoleErrors: [], whatToDo: null },
         error: error ? { code: error.code, message: error.message } : null,
         machinesNotProvenShutDown: TERMINAL.has(view.status) ? view.totals.cleanupUnproven : 0,
     };
@@ -145,6 +192,12 @@ export function verifyReport(view) {
 export function reportMarkdown(report) {
     const lines = [`# ${report.headline}`, '',
         `Change: ${report.title}`, `Check ${report.runId} of ${report.repository}: base ${report.baseCommit.slice(0, 12)}, change ${report.workCommit.slice(0, 12)}.`];
+    // Amendment 22: a broken copy is said first, with why and what to do, whatever became of the run after it answered (a cancelled
+    // or failed run's published health still says it); its findings follow, marked.
+    const broken = report.health?.status === 'app-broken' ? report.health : null;
+    if (broken !== null) {
+        lines.splice(1, 0, '', broken.reason, ...(broken.shows.length ? ['', 'The start screen shows:', ...broken.shows.map(line => `- ${line}`)] : []), ...(broken.failedRequests.length ? ['', 'Requests that failed with nobody clicking:', ...broken.failedRequests.map(line => `- ${line}`)] : []), ...(broken.consoleErrors.length ? ['', 'Console errors with nobody clicking:', ...broken.consoleErrors.map(line => `- ${line}`)] : []), '', '## What to do', ...(broken.whatToDo ?? []).map((step, index) => `${index + 1}. ${step}`));
+    }
     if (report.error && report.status !== 'completed')
         lines.push(`Details: ${report.error.message}`);
     if (report.neverRan === null) {
@@ -161,7 +214,9 @@ export function reportMarkdown(report) {
         if (spot.reachedBy)
             lines.push(`  - reached by: ${[spot.reachedBy.start, ...spot.reachedBy.steps].join(' > ')}${spot.reachedBy.page ? ` (page ${spot.reachedBy.page})` : ''}`);
     }
-    lines.push('', '## What the crawl found');
+    lines.push('', broken === null ? '## What the crawl found' : '## What the crawl found in the broken copy');
+    if (broken !== null)
+        lines.push('The copy was broken, so these differences are the environment\'s, not evidence about the change.');
     if (report.findings.length === 0)
         lines.push('No confirmed differences between the app with and without the change.');
     report.findings.forEach((finding, index) => {

package/dist/commands/init.js

@@ -49,8 +49,9 @@ export const AGENT_NOTE = [
     '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.',
     '',
-    '1. `haystack verify`: what your change touches, what production and real users do there, and Haystack\'s ideas of',
-    '   what could break. It then asks you to steer (exit 4).',
+    '1. `haystack verify`: what your change touches (first its flows), what production and real users do there, and',
+    '   Haystack\'s ideas of what could break. It then asks you to steer (exit 4). `haystack verify flow <n>` drills into',
+    '   one flow: its code, the pages it shows on with their real use, and what its code saw in production.',
     '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.',
     '',

package/dist/commands/verify-flows.js

@@ -0,0 +1,62 @@
+/**
+ * CRAWL-V1 amendment 21 in the CLI: the brief's flows, as a coding agent reads them. Akshay (2026-10-07): the system says "this
+ * change touches N flows", and the agent drills into a flow: the files and functions it runs through, and what telemetry says
+ * about it. `haystack verify` lists the flows first; `haystack verify flow <n>` shows one.
+ *
+ * Browser data comes from each app's capture window, never from daily rollups (CAPTURE-V1 rule 7a): a flow's pages are the
+ * routes whose source is one of its files, and its share is the union of captured sessions that visited any of them
+ * (captureChangedRoutes). A flow whose files serve no captured route has "no captured route", never 0%. Shares are of captured
+ * sessions, never of users. Journeys are only those the window keeps, with their release; their press and submit keys are
+ * release-scoped hints, and a key the window lists as ambiguous is never shown as a resolved control. Server data is the brief's
+ * production rows for the flow's functions (shares of observed calls, with their sample sizes).
+ */
+import { captureChangedRoutes } from './capture-contract.js';
+/** A flow's files, in the order its functions come (changed ones first). */
+export function flowFiles(brief, flow) {
+    return [...new Set(flow.functions.map(index => brief.functions[index].file))];
+}
+function flowCapture(windows, files, now) {
+    return windows === null ? null : windows.map(app => app.state === 'ready'
+        ? { app: app.app, applicationId: app.applicationId, state: 'ready', routes: captureChangedRoutes(app.window, files, now) } : app);
+}
+/** The handshake's flows, in the brief's order; empty when the brief has none. */
+export function flowSummaries(brief, windows, now) {
+    return (brief.flows ?? []).map((flow, at) => {
+        const files = flowFiles(brief, flow);
+        return { number: at + 1, id: flow.id, name: flow.name, files, functions: flow.functions.length,
+            changedFunctions: flow.functions.filter(index => brief.functions[index].direction === 'changed').length,
+            capture: flowCapture(windows, files, now) };
+    });
+}
+function routesOf(window, changed) {
+    const rows = new Map(window.routes.map(row => [row.route, row]));
+    const ambiguous = new Set((window.ambiguous ?? []).map(entry => JSON.stringify([entry.route, entry.release, entry.key])));
+    const mark = (step, release) => (step.kind === 'press' || step.kind === 'submit') && ambiguous.has(JSON.stringify([step.route, release, step.key])) ? { ...step, ambiguous: true } : step;
+    return changed.routes.map(route => {
+        const row = rows.get(route.route);
+        const journeys = (row?.journeys ?? [])
+            .filter(journey => journey.steps.some(step => step.route === route.route))
+            .map(journey => ({ release: journey.release, sessions: journey.sessions, steps: journey.steps.map(step => mark(step, journey.release)) }));
+        return { route: route.route, match: route.match, source: route.source, sessions: route.sessions, share: route.share,
+            devices: [...(row?.devices ?? [])].sort((a, b) => b.sessions - a.sessions), journeys };
+    });
+}
+/** One flow in detail; null when the brief has no flow with that number (from 1). */
+export function flowDetail(brief, number, windows, now) {
+    const flow = brief.flows?.[number - 1];
+    if (flow === undefined)
+        return null;
+    const files = flowFiles(brief, flow);
+    const indexes = new Set(flow.functions);
+    const production = brief.production === undefined ? null
+        : { ...brief.production, functions: brief.production.functions.filter(row => indexes.has(row.index)) };
+    const capture = windows === null ? null : windows.map(app => {
+        if (app.state !== 'ready')
+            return app;
+        const window = captureChangedRoutes(app.window, files, now);
+        return { app: app.app, applicationId: app.applicationId, window, routes: routesOf(app.window, window) };
+    });
+    return { number, id: flow.id, name: flow.name, changeKeys: flow.changeKeys,
+        functions: flow.functions.map(index => ({ ...brief.functions[index], index })), production, capture,
+        ideas: (brief.planning?.ideas ?? []).filter(idea => idea.groupId === flow.id) };
+}

package/dist/commands/verify-onboarding.js

@@ -113,6 +113,23 @@ export function parseOnboardingStatus(value, expected) {
     if (ready ? !(typeof value.recordPublishedAt === 'string' && !Number.isNaN(Date.parse(value.recordPublishedAt)))
         : value.recordPublishedAt !== null)
         invalid('its record time');
+    // Rule 18 (amendment 38): a ready record says what it updated, and the update of it under way, if any.
+    const recordUpdate = value.recordUpdate;
+    if (!(recordUpdate === null || (ready && isRecord(recordUpdate) && typeof recordUpdate.of === 'string' && SHA256.test(recordUpdate.of)
+        && typeof recordUpdate.crawlRunId === 'string' && (recordUpdate.side === 'base' || recordUpdate.side === 'head')
+        && typeof recordUpdate.workCommit === 'string' && COMMIT.test(recordUpdate.workCommit)
+        && Array.isArray(recordUpdate.changes) && recordUpdate.changes.every(change => isRecord(change) && typeof change.field === 'string'
+        && (change.name === null || typeof change.name === 'string') && (change.kind === 'added' || change.kind === 'changed')
+        && Array.isArray(change.evidence) && change.evidence.every(id => typeof id === 'string')))))
+        invalid('its record update');
+    const update = value.update;
+    if (!(update === null || (ready && isRecord(update) && typeof update.onboardRunId === 'string' && ONBOARD_RUN_ID.test(update.onboardRunId)
+        && (update.side === 'base' || update.side === 'head') && typeof update.crawlRunId === 'string'
+        && (update.state === 'updating' || update.state === 'blocked' || update.state === 'stopped')
+        && (update.state === 'blocked') === (update.block !== null))))
+        invalid('its update');
+    if (isRecord(update) && update.block !== null)
+        parseOnboardingBlock(update.block);
     if (value.block !== null)
         parseOnboardingBlock(value.block);
     const checkpoint = value.checkpoint;
@@ -313,6 +330,9 @@ export function formatOnboarding(status) {
         lines.push('', ...stages);
     if (status.block)
         lines.push('', ...blockLines(status.block));
+    const updates = updateLines(status);
+    if (updates.length)
+        lines.push('', ...updates);
     if (status.dataAbsences.length)
         lines.push('', ...status.dataAbsences.map(absence => chalk.yellow(`Note: ${safe(absence)}`)));
     if (status.versionChoices.length)
@@ -325,6 +345,37 @@ export function formatOnboarding(status) {
         lines.push('', ...unreviewed.map(note => chalk.yellow(`Note: ${safe(note)}`)));
     return lines.join('\n');
 }
+/** Rule 18 (amendment 38): what the ready setup's last update was, and the update of it under way or ended without one: one
+ * line each, and a blocked update's block (what it needs, and what to tell Haystack). */
+export function updateLines(status) {
+    const lines = [];
+    const failed = (side) => side === 'base' ? 'the app did not start at its base commit' : 'the change did not start';
+    if (status.recordUpdate) {
+        const changes = status.recordUpdate.changes.map(change => `${change.kind} ${change.field === 'env' ? 'variable' : change.field}`
+            + `${change.name === null ? '' : ` ${change.name}`}${change.evidence.length ? ` (from ${change.evidence.join(', ')})` : ''}`);
+        lines.push(`Its setup was updated in place after check ${status.recordUpdate.crawlRunId}, where ${failed(status.recordUpdate.side)}`
+            + `${changes.length ? `: ${changes.join('; ')}` : ''}.`);
+    }
+    const update = status.update;
+    if (update === null)
+        return lines;
+    if (update.state === 'updating') {
+        lines.push(`Updating the setup (${update.onboardRunId}): check ${update.crawlRunId} found ${failed(update.side)}. The check runs `
+            + 'again on the updated setup when it is ready.');
+    }
+    else if (update.state === 'stopped') {
+        lines.push(`The update of the setup for check ${update.crawlRunId} (${update.onboardRunId}) stopped before finishing; the next check `
+            + 'that fails the same way starts it again.');
+    }
+    else {
+        lines.push(update.side === 'head'
+            ? chalk.bold(`Finding: check ${update.crawlRunId}'s change does not start, and no change to the setup started it.`)
+            : chalk.bold(`Haystack could not update the setup for check ${update.crawlRunId}, where the app did not start at its base commit.`));
+        if (update.block)
+            lines.push(...blockLines(update.block));
+    }
+    return lines;
+}
 /** 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)