@haystackeditor/cli 0.28.1 → 0.30.1

package/dist/commands/verify.js

@@ -29,11 +29,12 @@ import { findGitRoot } from '../utils/hooks.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, repoApiPath, } from '../utils/haystack-api.js';
 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 { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_FLOW_NAME_CHARS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_HEALTH_MAX_DIFFERENCES, CRAWL_HEALTH_MAX_LINES, 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 { BROKEN_COPY_STEPS, SPOT_WORDS, TERMINAL, VERDICT_WORDS, VERDICTS, brokenCopy, brokenCopyEvidence, currentStep, errorWords, headline, plural, reportedStatus, results, verifyReport, } from './crawl-report.js';
 import { formatOnboarding, onboardingExitCode, readOnboardingStatus, readyLine, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
-import { formatCapture, readPreVerifyCapture } from './capture-brief.js';
+import { formatCapture, preVerifyCapture, readCaptureWindows } from './capture-brief.js';
+import { flowDetail, flowSummaries } from './verify-flows.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;
 const RUN_ID = /^cv_[0-9a-f]{48}$/;
@@ -182,9 +183,30 @@ function checkResults(value, view, what) {
         invalid('its ideas');
     if (value.brief !== undefined)
         checkBrief(value.brief);
+    if (value.health !== undefined)
+        checkHealth(value.health);
     if (value.error !== null)
         checkError(value.error, 'its error');
 }
+/** Amendment 22: the health of the app copy, as the worker bounds it: `not-judged` with its reason, or a judgment. */
+function checkHealth(value) {
+    const lines = (item) => isStrings(item, CRAWL_HEALTH_MAX_LINES);
+    if (!isRecord(value) || typeof value.reason !== 'string' || value.reason.length === 0)
+        invalid('its app health');
+    if (value.status === 'not-judged')
+        return;
+    const evidence = value.evidence;
+    const images = value.images;
+    if ((value.status !== 'ok' && value.status !== 'app-broken') || typeof value.working !== 'number' || !(value.working >= 0 && value.working <= 1)
+        || !isMember(value.tested, ['tested', 'app_broken', 'not_reached', 'unclear'])
+        || !isRecord(evidence) || !lines(evidence.texts) || !lines(evidence.messages) || !lines(evidence.overlays)
+        || !isRecord(evidence.background) || !lines(evidence.background.old) || !lines(evidence.background.new)
+        || !Array.isArray(evidence.commonDifferences) || evidence.commonDifferences.length > CRAWL_HEALTH_MAX_DIFFERENCES
+        || !evidence.commonDifferences.every(row => isRecord(row) && typeof row.line === 'string' && isCount(row.count))
+        || !isRecord(images) || (images.old !== null && typeof images.old !== 'string')
+        || (images.new !== null && typeof images.new !== 'string'))
+        invalid('its app health');
+}
 /** Amendment 18: a brief's shape and bounds, as the worker checks them. */
 function checkBrief(value) {
     const text = (item, empty = false) => typeof item === 'string' && (empty || item.length > 0) && [...item].length <= CRAWL_MAX_TEXT_CHARS;
@@ -224,6 +246,18 @@ function checkBrief(value) {
             && records(observed.shapes, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, shape => text(shape.shape) && isCount(shape.count)))
         && estimates(fn))))
         invalid('its brief');
+    // Amendment 21: each flow is a planning group, named, with distinct function indexes the brief holds.
+    const flows = value.flows;
+    if (flows !== undefined) {
+        const groupIds = new Set(isRecord(planning) && Array.isArray(planning.groups) ? planning.groups.map(group => group.id) : []);
+        const count = value.functions.length;
+        if (planning === null || !records(flows, CRAWL_BRIEF_MAX_GROUPS, flow => text(flow.id) && groupIds.has(flow.id)
+            && typeof flow.name === 'string' && flow.name.length > 0 && [...flow.name].length <= CRAWL_BRIEF_MAX_FLOW_NAME_CHARS
+            && texts(flow.changeKeys, CRAWL_BRIEF_MAX_FUNCTIONS) && Array.isArray(flow.functions) && flow.functions.length <= count
+            && flow.functions.every(index => isCount(index) && index < count) && new Set(flow.functions).size === flow.functions.length)
+            || new Set(flows.map(flow => flow.id)).size !== flows.length)
+            invalid('its brief');
+    }
 }
 function checkManifest(value, view) {
     checkResults(value, view, 'its results');
@@ -375,6 +409,15 @@ function findingLines(finding, position) {
 export function formatCrawl(view) {
     const status = reportedStatus(view);
     const lines = [chalk.bold(headline(view))];
+    // Amendment 22: a broken copy tested nothing: said first (the headline), then why, what both builds showed, and what to do. Its
+    // findings still follow, marked as the broken copy's.
+    // Amendment 22: whatever became of the run after it answered; the exit code keeps the run's own status (crawlExitCode).
+    const broken = brokenCopy(view);
+    if (broken !== null) {
+        const { shows, failedRequests, consoleErrors } = brokenCopyEvidence(broken);
+        const listed = (title, items) => (items.length ? [`  ${title}`, ...items.map(item => `    ${safe(item)}`)] : []);
+        lines.push(`  ${safe(broken.reason)}`, ...listed('The start screen shows:', shows), ...listed('Requests that failed with nobody clicking:', failedRequests), ...listed('Console errors with nobody clicking:', consoleErrors), chalk.bold('  What to do:'), ...BROKEN_COPY_STEPS.map((step, index) => `    ${index + 1}. ${step}`), '');
+    }
     const published = results(view);
     const error = published?.error ?? view.error;
     if (error && status !== 'completed')
@@ -398,7 +441,9 @@ export function formatCrawl(view) {
         lines.push('  No changed spots were recorded.');
     for (const spot of published.reach.spots)
         lines.push(...spotLines(spot));
-    lines.push('', chalk.bold('What the crawl found'));
+    lines.push('', chalk.bold(broken === null ? 'What the crawl found' : 'What the crawl found in the broken copy'));
+    if (broken !== null)
+        lines.push(chalk.yellow('  The copy was broken, so these differences are the environment\'s, not evidence about your change.'));
     // Bugs first, then the undecided, then what the judge called intended.
     const findings = VERDICTS.flatMap(verdict => published.findings.filter(finding => finding.verdict === verdict));
     if (findings.length === 0)
@@ -462,12 +507,16 @@ export function formatCrawl(view) {
  * 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. */
+ * found never change it. 5 (amendment 22): it finished, but the copy of the app was
+ * broken, so the change was not tested; it wins over unproven cleanup, since what the
+ * agent does next is fix how the app runs. The command's own failures exit 1 elsewhere. */
 export { verifyReport };
 export function crawlExitCode(view) {
     const status = reportedStatus(view);
     if (!TERMINAL.has(status))
         return 0;
+    if (status === 'completed' && brokenCopy(view) !== null)
+        return 5;
     if (status !== 'completed' || (TERMINAL.has(view.status) && view.totals.cleanupUnproven > 0))
         return 2;
     return 0;
@@ -658,6 +707,8 @@ async function submitCapture(capture, token, found) {
     // sender does: admission is idempotent for one capture, so a repeat can only find what the first created.
     const acknowledgment = await readWithRetries(() => postPrecomputeCapture(capture, token, Date.now() + EXPLICIT_WALL_MS)).catch((error) => { throw normalModeFailure(error); });
     const crawl = acknowledgment.crawl;
+    // Amendment 12: the handshake submits mode 'prepare', which builds and prepares the change and never starts a crawl.
+    const preparing = capture.derivation.request.crawl?.mode === 'prepare';
     const before = found === null ? 'No crawl existed for this change' : staleWords(found.view, found.stale);
     if (crawl === undefined) {
         return { runId: null, onboarding: null,
@@ -669,14 +720,14 @@ async function submitCapture(capture, token, found) {
     }
     if (crawl.status === 'onboarding') {
         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.` };
+                + `the service is preparing it (${crawl.onboardRunId}) and continues with this change when it is ready.` };
     }
     if (crawl.status === 'onboarding-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'
-                ? `No crawl existed for this change yet; started one (${crawl.runId}).`
+                ? `No crawl existed for this change yet; ${preparing ? 'started preparing it' : 'started one'} (${crawl.runId}).`
                 : `The service already had a crawl for this change (${crawl.runId}).` };
     }
     if (!anotherCrawl(found.stale) && crawl.runId === found.view.runId) {
@@ -684,7 +735,7 @@ async function submitCapture(capture, token, found) {
                 ? `${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}).`
+            ? `${before}; ${preparing ? 'started preparing the change again' : 'started one for this change'} (${crawl.runId}).`
             : `${before}; the service already had one for this change (${crawl.runId}).` };
 }
 function checkedChange(baseCommit, workCommit) {
@@ -782,6 +833,129 @@ function describeEstimate(estimate) {
     }
     return lines;
 }
+/** A flow's captured share in one line: per app with routes for it; "no captured route" where its files serve none. */
+function flowShare(flow) {
+    if (flow.capture === null)
+        return '';
+    const parts = flow.capture.map(app => {
+        const where = app.app === '.' ? '' : `${safe(app.app)}: `;
+        if (app.state === 'unavailable')
+            return `${where}captured sessions unreadable`;
+        if (app.state === 'no-data')
+            return `${where}no captured sessions yet`;
+        if (app.routes.routes.length === 0)
+            return `${where}no captured route`;
+        return `${where}${app.routes.union.share === null ? 'n/a' : percent(app.routes.union.share)} of captured sessions (${app.routes.union.sessions})`
+            + `${app.routes.stale ? ', stale' : ''}`;
+    });
+    return parts.join('; ');
+}
+/** Amendment 21: the flows a change touches, first in the handshake, with how to see one. */
+export function formatFlows(flows) {
+    const lines = [chalk.bold(`Your change touches ${plural(flows.length, 'flow')}:`)];
+    for (const flow of flows) {
+        const share = flowShare(flow);
+        lines.push(`  ${flow.number}. ${safe(flow.name)}: ${plural(flow.files.length, 'file')}, ${plural(flow.functions, 'function')}`
+            + `${share ? `; ${share}` : ''}`);
+    }
+    lines.push(`See one in detail: haystack verify flow <n> (for example \`haystack verify flow 1\`).`);
+    return lines.join('\n');
+}
+const SHOWN_FLOW_FUNCTIONS = 40;
+const SHOWN_FLOW_DEVICES = 5;
+const SHOWN_FLOW_JOURNEYS = 5;
+function journeyStep(step) {
+    if (step.kind === 'view')
+        return `view ${safe(step.route)}`;
+    if (step.kind === 'input')
+        return `input (${safe(step.control)}) on ${safe(step.route)}`;
+    const control = step.kind === 'press' ? `${safe(step.control)} ` : '';
+    return `${step.kind} ${control}${step.ambiguous ? '(a control that repeats on the page)' : `"${safe(step.key)}"`} on ${safe(step.route)}`;
+}
+/** Amendment 21: `haystack verify flow <n>`: one flow's code, the pages it shows on with real use, what its code saw in production,
+ * and Haystack's ideas for it. */
+export function formatFlowDetail(detail) {
+    const lines = [chalk.bold(`Flow ${detail.number}: ${safe(detail.name)}`), '', chalk.bold('Code (changed first, then what it calls or what calls it)')];
+    for (const fn of detail.functions.slice(0, SHOWN_FLOW_FUNCTIONS)) {
+        lines.push(`  ${safe(fn.file)}:${fn.lines[0]}-${fn.lines[1]} ${safe(fn.name)}: `
+            + `${fn.direction === 'changed' ? 'changed' : `${fn.direction}, ${plural(fn.distance, 'step')} away`}`);
+    }
+    if (detail.functions.length > SHOWN_FLOW_FUNCTIONS)
+        lines.push(`  and ${plural(detail.functions.length - SHOWN_FLOW_FUNCTIONS, 'more function')} (all in --json)`);
+    lines.push('', chalk.bold('Pages it shows on (real use)'));
+    if (detail.capture === null)
+        lines.push('  Capture is not set up for this repository: run `haystack init` to see how real users reach these pages.');
+    else
+        for (const app of detail.capture) {
+            const where = app.app === '.' ? 'the app' : safe(app.app);
+            if ('state' in app && app.state === 'unavailable') {
+                lines.push(`  ${where}: captured sessions could not be read: ${safe(app.reason)}`);
+                continue;
+            }
+            if ('state' in app && app.state === 'no-data') {
+                lines.push(`  ${where}: no captured sessions yet.`);
+                continue;
+            }
+            const shown = app;
+            const window = shown.window;
+            const days = window.days.length ? `${window.days[0]} to ${window.days.at(-1)}` : 'the window';
+            lines.push(`  ${where}: ${window.sessions} captured session(s), ${days}; newest data ${window.newestHour === null ? 'none' : `${window.newestHour}:00 UTC`}`
+                + `${window.stale ? ` (stale: ${window.ageHours === null ? 'no data' : `${Math.round(window.ageHours)} hours old`})` : ''}.`);
+            const dropped = Object.entries(window.dropped).filter(([, count]) => count > 0);
+            const drops = dropped.length ? [`    Events dropped at ingest: ${dropped.map(([reason, count]) => `${safe(reason)} ${count}`).join(', ')}.`] : [];
+            if (shown.routes.length === 0) {
+                lines.push('    No captured route: none of this flow\'s files defines a route captured sessions reached.', ...drops);
+                continue;
+            }
+            for (const route of shown.routes) {
+                lines.push(`    ${safe(route.match)} (${safe(route.source)}): ${route.share === null ? 'n/a' : percent(route.share)} of captured sessions (${route.sessions})`);
+                if (route.devices.length) {
+                    lines.push(`      Devices: ${route.devices.slice(0, SHOWN_FLOW_DEVICES).map(device => `${safe(device.device)}/${safe(device.engine)}/${safe(device.viewport)} `
+                        + `(${device.sessions})`).join(', ')}${route.devices.length > SHOWN_FLOW_DEVICES ? `, ${route.devices.length - SHOWN_FLOW_DEVICES} more (in --json)` : ''}`);
+                }
+                for (const journey of route.journeys.slice(0, SHOWN_FLOW_JOURNEYS)) {
+                    lines.push(`      Journey (${journey.sessions} sessions, release ${safe(journey.release)}): ${journey.steps.map(journeyStep).join(' > ')}`);
+                }
+                if (route.journeys.length > SHOWN_FLOW_JOURNEYS)
+                    lines.push(`      and ${plural(route.journeys.length - SHOWN_FLOW_JOURNEYS, 'more journey')} (in --json)`);
+            }
+            if (shown.routes.length > 1) {
+                lines.push(`    Together: ${window.union.share === null ? 'n/a' : percent(window.union.share)} of captured sessions (${window.union.sessions}) visited at least one of them.`);
+            }
+            lines.push(...drops);
+        }
+    if (detail.capture !== null)
+        lines.push('  Shares are of captured (consenting) sessions only, never of users. Journey keys are hints scoped to their release.');
+    lines.push('', chalk.bold('What its code saw in production'));
+    if (detail.production === null)
+        lines.push('  No production telemetry for this repository: set it up to see how this code runs for real users.');
+    else if (detail.production.functions.length === 0)
+        lines.push(`  None of these functions was seen running in the last ${detail.production.windowDays} days.`);
+    else {
+        const byIndex = new Map(detail.functions.map(fn => [fn.index, fn]));
+        for (const row of detail.production.functions) {
+            const fn = byIndex.get(row.index);
+            lines.push(`  ${safe(fn.name)} (${safe(fn.file)}):`);
+            for (const branch of row.branches)
+                lines.push(`      in production: line ${branch.line} was true ${branch.whenTrue}${branch.capped ? '+' : ''} times,`
+                    + ` false ${branch.whenFalse}${branch.capped ? '+' : ''} times`);
+            for (const observed of row.values)
+                lines.push(`      in production: line ${observed.line} ${safe(observed.what)} was `
+                    + observed.shapes.map(shape => `${safe(shape.shape)} (${shape.count})`).join(', '));
+            for (const estimate of row.estimates ?? [])
+                lines.push(...describeEstimate(estimate));
+        }
+        lines.push(`  The last ${detail.production.windowDays} days, newest ${safe(detail.production.newestAt)}; shares are of observed calls, never of users`
+            + `${detail.production.partial ? '; the read stopped at its budget, so every count is a lower bound' : ''}.`);
+    }
+    lines.push('', chalk.bold('What could break here'));
+    if (detail.ideas.length === 0)
+        lines.push('  No idea of ours was selected for this flow.');
+    for (const idea of detail.ideas) {
+        lines.push(`  - Try: ${safe(idea.exercise)}`, ...(idea.setup.length ? [`    Set up first: ${idea.setup.map(safe).join('; ')}`] : []), `    Watch: ${safe(idea.watch)}`, `    It would show as: ${safe(idea.failure)}`);
+    }
+    return lines.join('\n');
+}
 /** The brief as a coding agent reads it: what the change touches, then Haystack's own ideas, then how to hand back intent and
  * ideas. Every function is in --json; the text shows the changed ones and those one step away, and says how many more. */
 export function formatBrief(brief) {
@@ -844,16 +1018,24 @@ export function formatBrief(brief) {
     }
     return lines.join('\n');
 }
-/** The handshake's question, asked after everything it shows. */
 /** The command to steer with; it keeps the options the handshake was given that choose the crawl (where, and for how long). */
 export function steerCommand(options) {
     const kept = [options.repo ? ` --repo ${options.repo}` : '', options.account ? ` --account ${options.account}` : '',
         options.minutes ? ` --minutes ${options.minutes}` : ''].join('');
     return `haystack verify${kept} --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]`;
 }
-const steerLines = (command) => ['',
-    '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):',
-    `  ${command}`, 'Your ideas are explored first; the ideas above are explored in every crawl too.'];
+/** The handshake's question, asked after everything it shows; it speaks of "the ideas above" only when it showed some. */
+export function steerLines(command, shownIdeas) {
+    return shownIdeas
+        ? ['', '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):',
+            `  ${command}`, 'Your ideas are explored first; the ideas above are explored in every crawl too.']
+        : ['', 'Next: say what you were asked to do (the task in the user\'s words, not what your code does) and what to try:',
+            `  ${command}`, 'Your ideas are explored first.'];
+}
+/** Why a run stopped, as its report says it: the published error, else the run's own. */
+function stoppedBecause(view) {
+    return results(view)?.error ?? view.error ?? null;
+}
 /** The handshake (Akshay, 10/7): a plain `haystack verify` on a change no crawl has started for shows what the change touches,
  * how production and real users run it, and Haystack's own ideas, then asks the coding agent to run `haystack verify` again
  * with --intent (and any --idea). It submits the capture in mode 'prepare' when no run of it is preparing, prepared or
@@ -862,9 +1044,11 @@ const steerLines = (command) => ['',
 async function handshake(capture, identity, change, found, stale, token, options, note) {
     let view = found;
     let onboarding = null;
-    const finish = (brief, captured) => {
+    const finish = (brief, captured, flows) => {
+        const error = view === null ? null : stoppedBecause(view);
         printVerifyJson(options, change, onboarding, null, {
-            run: view === null ? null : { runId: view.runId, status: view.status }, brief, capture: captured, next: steerCommand(options),
+            run: view === null ? null : { runId: view.runId, status: view.status, error: error ? { code: error.code, message: error.message } : null },
+            brief, capture: captured, flows, next: steerCommand(options),
         });
     };
     if (view === null || (stale !== null && stale !== 'prepare-only')) {
@@ -901,24 +1085,36 @@ async function handshake(capture, identity, change, found, stale, token, options
         view = await waitForBrief(view, identity, token);
     const brief = briefOf(view);
     // CAPTURE-V1 rule 7b: the routes the change touches, with their share of captured sessions, per app; null without capture set up.
-    const captured = await readPreVerifyCapture(findGitRoot(), identity.repository, token, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], new Date());
+    // Amendment 21: each flow's routes from the same windows.
+    const now = new Date();
+    const windows = await readCaptureWindows(findGitRoot(), identity.repository, token);
+    const captured = preVerifyCapture(windows, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], now);
+    const flows = brief === null ? [] : flowSummaries(brief, windows, now);
     process.exitCode = 4;
     if (options.json || options.raw) {
-        finish(brief, captured);
+        finish(brief, captured, flows);
         return;
     }
+    if (flows.length)
+        console.log(`${formatFlows(flows)}\n`);
     if (brief !== null)
         console.log(formatBrief(brief));
     else if (!TERMINAL.has(reportedStatus(view))) {
         console.log(`What your change touches is not worked out yet (${currentStep(view)}); run \`haystack verify\` again to see it, or steer now.`);
     }
     else {
-        console.log(`Run ${view.runId} ended (${view.status}) without a brief${view.error ? `: ${errorWords(view.error)}` : ''}; steer the crawl without one.`);
+        // A failed prepare leaves no brief (amendment 18); the agent sees why, and that a steered crawl runs those steps again.
+        const error = stoppedBecause(view);
+        console.log(`Run ${view.runId} ended (${view.status}) without a brief${error ? `: ${errorWords(error)}` : ''}.`);
+        if (error) {
+            console.log(`  Details: ${safe(error.message)}`);
+            console.log('A steered crawl runs these steps again, so it may stop the same way; if it does, tell us with `haystack feedback`.');
+        }
     }
     if (captured !== null)
         for (const section of captured)
             console.log(`\n${formatCapture(section)}`);
-    console.log(steerLines(steerCommand(options)).join('\n'));
+    console.log(steerLines(steerCommand(options), (brief?.planning?.ideas.length ?? 0) > 0).join('\n'));
 }
 /** verify's one JSON document: the report (`--json`) or the service's whole record (`--raw`). */
 function printVerifyJson(options, change, onboarding, view, handshake) {
@@ -928,6 +1124,40 @@ function printVerifyJson(options, change, onboarding, view, handshake) {
         : withSchema('verify', { change, onboarding, crawl: view === null ? null : verifyReport(view), ...extra });
     process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
 }
+/** Amendment 21: `haystack verify flow <n>`: one flow of this checkout's change, from the brief of the change's run (never starting
+ * one). Exit 0 with the flow; 1 when there is no run, no brief, no flows or no flow with that number, saying which. */
+export async function verifyFlowCommand(number, options) {
+    const wanted = Number(number);
+    if (!Number.isInteger(wanted) || wanted < 1)
+        throw new Error(`A flow's number counts from 1, as \`haystack verify\` lists them (got ${JSON.stringify(number)}).`);
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'prepare', repositoryOverride(options.repo), undefined, undefined, {});
+    const request = capture.derivation.request;
+    if (!request.crawl)
+        throw new Error(`Nothing to show: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
+    const identity = {
+        repository: `${request.owner}/${request.repository}`, baseCommit: request.baseCommit, 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 });
+    const view = await readWithRetries(() => readCrawl(identity, auth.token));
+    if (view === null)
+        throw new Error('This change has no run yet: run `haystack verify` first, which lists its flows.');
+    const brief = briefOf(view);
+    if (brief === null)
+        throw new Error(`Run ${view.runId} has no brief yet (${currentStep(view)}): run \`haystack verify\` to wait for it.`);
+    if (!brief.flows?.length) {
+        throw new Error(`Run ${view.runId}'s brief has no flows${brief.planning === null ? ' (no planning ran for this change)' : ''}; \`haystack verify\` shows what it has.`);
+    }
+    const windows = await readCaptureWindows(findGitRoot(), identity.repository, auth.token);
+    const detail = flowDetail(brief, wanted, windows, new Date());
+    if (detail === null)
+        throw new Error(`This change has ${plural(brief.flows.length, 'flow')}; there is no flow ${wanted}.`);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('verify-flow', { run: { runId: view.runId, status: view.status }, flow: detail }), null, 2)}\n`);
+        return;
+    }
+    console.log(formatFlowDetail(detail));
+}
 export async function verifyCommand(options) {
     const json = options.json || options.raw;
     // In --json mode stdout carries the one document; every other line goes to stderr.

package/dist/index.js

@@ -120,7 +120,8 @@ an hour). The file is JSON with any of three notes, each plain text:
 Leave out what you do not know. Onboarding still proves everything it takes
 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.
+after it, the next check that cannot start the app uses them to update the
+setup in place.
 
 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
@@ -177,10 +178,12 @@ const verify = program
 Two calls, run inside a git checkout (nothing needs to be committed or pushed):
 
   1. haystack verify
-     The handshake. It shows what your change touches, how production and real
-     users run it, and Haystack's own ideas of what could break, then asks what
-     you were asked to do and what to try. It builds and prepares the change if
-     the stop hook has not, and never starts a crawl. Exit 4.
+     The handshake. It shows what your change touches (first the flows: the
+     behaviors it changes, each with its files and its share of real use), how
+     production and real users run it, and Haystack's own ideas of what could
+     break, then asks what you were asked to do and what to try. It builds and
+     prepares the change if the stop hook has not, and never starts a crawl.
+     Exit 4. \`haystack verify flow <n>\` drills into one flow.
   2. haystack verify --intent "<the task, in the user's words>" --idea "<something to try>"
      The crawl, steered: your ideas (--idea, repeat for more, or --ideas-file)
      are explored before anything else, and the judge checks the app against
@@ -207,6 +210,16 @@ 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.
 
+When the copy of the app was itself broken (error popups or messages from its
+own setup, its own requests failing in both builds), the crawl could not test
+your change, and it says so first: "We couldn't test your change: the app copy
+is broken.", why, what the start screen showed, the requests that failed and
+the console errors, and what to do: find what those errors need in the
+repository's own setup (docker compose files, env examples, docs), send that
+with \`haystack feedback\` (a copy that starts but is broken does not update its
+setup yet), and tell your user the change was not tested. What the crawl
+found in the broken copy is listed after it, marked as such.
+
 The first verify on a base the service has not onboarded yet prepares the app
 (reads the repository, plans how to run it, builds its runtime, starts it,
 prepares its data and test accounts, proves a workflow); the command shows each
@@ -223,6 +236,8 @@ Exit codes:
      stopped before finishing
   3  onboarding is blocked: the output says what would unblock it
   4  the handshake: run it again with --intent (and any --idea)
+  5  the crawl finished, but the copy of the app was broken, so your change
+     was not tested: the output says what to do
 
 The hosted fleet run of pushed commits is \`haystack verify hosted start\`.
 
@@ -257,6 +272,32 @@ function verifyCommandOptions(command) {
     }
     return options;
 }
+verify
+    .command('flow')
+    .description('Drill into one flow `haystack verify` listed: its code, the pages it shows on, what its code saw in production')
+    .argument('<n>', 'The flow\'s number, as `haystack verify` lists them (from 1)')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'The flow as one JSON document (see `haystack schema verify-flow`)')
+    .addHelpText('after', `
+Reads the brief of this checkout's run (run \`haystack verify\` first); it never
+starts or changes a run. For one flow it shows:
+  - its functions: file, lines, and whether each changed or is a step away;
+  - the pages it shows on, per app with capture set up: each page's share of
+    captured sessions, the devices they used and the paths they took through it,
+    with how fresh the data is and what was dropped;
+  - what its functions saw in production (Haystack's own telemetry);
+  - Haystack's ideas of what could break in it.
+
+Examples:
+  haystack verify flow 1
+  haystack verify flow 2 --json
+`)
+    .action(async (n, _options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyFlowCommand } = await import('./commands/verify.js');
+    return runPublicCommand(() => verifyFlowCommand(n, options), options.json);
+});
 verify
     .command('answer')
     .description('Answer a question onboarding asked about your app, then run `haystack init` to continue')

package/dist/schema.js

@@ -12,8 +12,9 @@
 export const SCHEMA_VERSIONS = {
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '2.1.0',
-    'verify-raw': '1.1.0',
+    verify: '2.3.0',
+    'verify-flow': '1.0.0',
+    'verify-raw': '1.3.0',
     'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',
     init: '1.0.2',

package/package.json

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