@haystackeditor/cli 0.23.3 → 0.24.1

package/dist/commands/verify.js

@@ -22,13 +22,14 @@
  * A blocked onboarding prints why and exactly what would unblock it.
  */
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import chalk from 'chalk';
 import { withSchema } from '../schema.js';
 import { findGitRoot } from '../utils/hooks.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, } from '../utils/haystack-api.js';
 import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
-import { CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.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 { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, standInGapNotes, waitForOnboarding } from './verify-onboarding.js';
 const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
@@ -219,9 +220,51 @@ function checkResults(value, view, what) {
         invalid('its outside-service coverage');
     if (Object.hasOwn(reach, 'planning'))
         checkPlanningCoverage(reach.planning);
+    // Amendment 17: each idea of the request, in its order, naming only findings these results carry.
+    const ideas = value.ideas;
+    const findingIds = new Set(value.findings.map(finding => finding.id));
+    // Texts as the worker bounds them: nonempty, at most CRAWL_MAX_TEXT_CHARS code points (Astra).
+    const bounded = (value) => typeof value === 'string' && value.length > 0 && [...value].length <= CRAWL_MAX_TEXT_CHARS;
+    if (ideas !== undefined && (!Array.isArray(ideas) || ideas.length === 0 || ideas.length > CRAWL_MAX_IDEAS || !ideas.every((idea, index) => isRecord(idea)
+        && idea.id === `idea-${index + 1}` && bounded(idea.text) && bounded(idea.reason)
+        && (idea.state === 'covered' || idea.state === 'blocked' || idea.state === 'unfinished')
+        && isStrings(idea.findingIds, CRAWL_MAX_FINDINGS) && idea.findingIds.every(id => findingIds.has(id)))))
+        invalid('its ideas');
+    if (value.brief !== undefined)
+        checkBrief(value.brief);
     if (value.error !== null)
         checkError(value.error, 'its error');
 }
+/** 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;
+    const texts = (item, maximum) => Array.isArray(item) && item.length <= maximum && item.every(entry => text(entry));
+    const records = (item, maximum, each) => Array.isArray(item) && item.length <= maximum && item.every(row => isRecord(row) && each(row));
+    if (!isRecord(value) || !records(value.functions, CRAWL_BRIEF_MAX_FUNCTIONS, fn => text(fn.file) && text(fn.name, true)
+        && Array.isArray(fn.lines) && fn.lines.length === 2 && fn.lines.every(isCount) && isCount(fn.distance)
+        && (fn.direction === 'changed' || fn.direction === 'upstream' || fn.direction === 'downstream'))
+        || !records(value.leftOut, CRAWL_BRIEF_MAX_GROUPS, row => text(row.reason) && isCount(row.count)))
+        invalid('its brief');
+    const planning = value.planning;
+    if (planning !== null && (!isRecord(planning)
+        || !records(planning.groups, CRAWL_BRIEF_MAX_GROUPS, group => text(group.id) && texts(group.changeKeys, CRAWL_BRIEF_MAX_FUNCTIONS)
+            && records(group.patterns, CRAWL_BRIEF_MAX_GROUPS, pattern => text(pattern.entryId) && text(pattern.mechanism) && text(pattern.symptom, true)))
+        || !records(planning.unresolved, CRAWL_BRIEF_MAX_GROUPS, change => text(change.changeKey) && text(change.reason))
+        || !records(planning.ideas, CRAWL_MAX_IDEAS, idea => ['id', 'groupId', 'pattern', 'why', 'failure', 'exercise', 'watch', 'start']
+            .every(field => text(idea[field])) && texts(idea.setup, CRAWL_MAX_IDEAS))))
+        invalid('its brief');
+    // Amendment 19: each production row names a function the brief holds.
+    const production = value.production;
+    const line = (item) => isCount(item) && item >= 1;
+    if (production !== undefined && (!isRecord(production) || !isCount(production.windowDays) || !isCount(production.payloads)
+        || !text(production.newestAt, true) || typeof production.partial !== 'boolean' || !records(production.functions, CRAWL_BRIEF_MAX_FUNCTIONS, fn => isCount(fn.index)
+        && fn.index < value.functions.length && isCount(fn.branchesOmitted) && isCount(fn.valuesOmitted)
+        && records(fn.branches, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, branch => line(branch.line) && isCount(branch.whenTrue)
+            && isCount(branch.whenFalse) && typeof branch.capped === 'boolean')
+        && records(fn.values, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, observed => line(observed.line) && text(observed.what)
+            && records(observed.shapes, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, shape => text(shape.shape) && isCount(shape.count))))))
+        invalid('its brief');
+}
 function checkManifest(value, view) {
     checkResults(value, view, 'its results');
     if (value.status !== view.status)
@@ -451,6 +494,15 @@ export function formatCrawl(view) {
         lines.push(`  ${plural(published.notFinishedInTime, 'difference')} ${published.notFinishedInTime === 1 ? 'was' : 'were'}`
             + ' still being checked when its time ran out.');
     }
+    // Amendment 17: what became of each idea the coding agent gave, with the numbers of the findings above that came from it.
+    if (published.ideas !== undefined) {
+        const numbered = new Map(findings.map((finding, index) => [finding.id, index + 1]));
+        lines.push('', chalk.bold('Your ideas'));
+        for (const idea of published.ideas) {
+            const found = idea.findingIds.map(id => numbered.get(id)).filter((n) => n !== undefined);
+            lines.push(`  ${idea.state === 'covered' ? 'tried' : idea.state === 'blocked' ? 'could not try' : 'not finished'}: ${safe(idea.text)}`, `    ${safe(idea.reason)}`, ...(found.length ? [`    Findings from it: ${found.map(n => `#${n}`).join(', ')}`] : []));
+        }
+    }
     lines.push('', chalk.bold('What the crawl never ran'));
     if (published.reach.unreachedChangedFiles.length === 0)
         lines.push('  Every changed file ran at least once.');
@@ -514,6 +566,28 @@ function poolOption(value) {
         throw new Error(`--pool must be one of ${CRAWL_POOLS.join(', ')}.`);
     return value;
 }
+/** --intent, --idea and --ideas-file (CRAWL-V1 amendment 17): each text trimmed, 1 to CRAWL_MAX_TEXT_CHARS characters; at most
+ * CRAWL_MAX_IDEAS ideas, each once. Absent ones stay absent, so a crawl asked without them keeps its identity. */
+export function agentDirection(options) {
+    const text = (value, what) => {
+        const trimmed = value.trim();
+        if (trimmed.length === 0 || [...trimmed].length > CRAWL_MAX_TEXT_CHARS)
+            throw new Error(`${what} must be 1 to ${CRAWL_MAX_TEXT_CHARS} characters.`);
+        return trimmed;
+    };
+    const fromFile = options.ideasFile === undefined ? [] : (() => {
+        const parsed = JSON.parse(readFileSync(options.ideasFile, 'utf8'));
+        if (!Array.isArray(parsed) || !parsed.every(item => typeof item === 'string'))
+            throw new Error('--ideas-file must hold a JSON array of strings.');
+        return parsed;
+    })();
+    const ideas = [...options.idea ?? [], ...fromFile].map(idea => text(idea, 'Each idea'));
+    if (ideas.length > CRAWL_MAX_IDEAS)
+        throw new Error(`A crawl takes at most ${CRAWL_MAX_IDEAS} ideas; ${ideas.length} were given.`);
+    if (new Set(ideas).size !== ideas.length)
+        throw new Error('The same idea was given twice.');
+    return { ...(options.intent === undefined ? {} : { intent: text(options.intent, '--intent') }), ...(ideas.length ? { ideas } : {}) };
+}
 /** --minutes: whole minutes from 1 to 30 (CRAWL-V1 amendment 8). */
 function minutesOption(value) {
     if (value === undefined)
@@ -713,13 +787,198 @@ function finishWithOnboarding(status, json, change) {
         console.log(formatOnboarding(status));
     process.exitCode = onboardingExitCode(status);
 }
+/** The brief a crawl view holds (CRAWL-V1 amendment 18): its sealed manifest's, else its latest answer's. */
+function briefOf(view) {
+    return view.manifest?.brief ?? view.answer?.brief ?? null;
+}
+/** Follows a run until it holds a brief or ends (amendment 18): its own read held until it changes, as waitForCrawl's is. */
+async function waitForBrief(first, identity, token) {
+    const interrupted = () => {
+        console.error('\nStopped waiting. The change keeps being prepared; run `haystack pre-verify` again to see its brief.');
+        process.exit(130);
+    };
+    process.once('SIGINT', interrupted);
+    try {
+        let view = first;
+        progress(`Waiting for the brief of ${view.runId}: the change is built and prepared first (Ctrl-C stops waiting).`);
+        progress(currentStep(view));
+        let failing = false;
+        let answeredAt = Date.now();
+        while (briefOf(view) === null && !TERMINAL.has(reportedStatus(view))) {
+            let next;
+            try {
+                next = await readCrawlRun(view.runId, identity, token, view.updatedAt);
+            }
+            catch (error) {
+                const why = transientReadFailure(error);
+                if (why === null)
+                    throw error;
+                if (Date.now() - answeredAt >= SERVICE_SILENCE_LIMIT_MS)
+                    throw new ServiceSilentError('crawl', 'haystack pre-verify');
+                if (!failing)
+                    progress(`The run's status is unavailable for now (${why}); reading it again.`);
+                failing = true;
+                await new Promise(resolve => setTimeout(resolve, TRANSIENT_READ_PAUSE_MS));
+                continue;
+            }
+            failing = false;
+            answeredAt = Date.now();
+            if (!TERMINAL.has(reportedStatus(next)) && currentStep(next) !== currentStep(view))
+                progress(currentStep(next));
+            view = next;
+        }
+        return view;
+    }
+    finally {
+        process.removeListener('SIGINT', interrupted);
+    }
+}
+/** 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) {
+    const lines = [chalk.bold('What your change touches')];
+    const near = brief.functions.filter(fn => fn.distance <= 1);
+    // Amendment 19: what production saw of each function shown, from the repository's own telemetry.
+    const seen = new Map((brief.production?.functions ?? []).map(row => [row.index, row]));
+    if (brief.functions.length === 0)
+        lines.push('  The blast radius found no affected functions.');
+    brief.functions.forEach((fn, index) => {
+        if (fn.distance > 1)
+            return;
+        lines.push(`  ${fn.direction === 'changed' ? 'changed' : `${fn.direction}, ${plural(fn.distance, 'step')} away`}: `
+            + `${safe(fn.file)}:${fn.lines[0]}-${fn.lines[1]} ${safe(fn.name)}`);
+        const row = seen.get(index);
+        if (row === undefined)
+            return;
+        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`);
+        if (row.branchesOmitted)
+            lines.push(`      and ${plural(row.branchesOmitted, 'more branch site')} (in --json)`);
+        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(', '));
+        if (row.valuesOmitted)
+            lines.push(`      and ${plural(row.valuesOmitted, 'more observed value')} (in --json)`);
+    });
+    if (brief.production) {
+        const shownSeen = brief.production.functions.filter(row => brief.functions[row.index].distance <= 1).length;
+        lines.push(`  Production telemetry: the last ${brief.production.windowDays} days, newest ${safe(brief.production.newestAt)};`
+            + ` ${plural(brief.production.functions.length, 'function')} seen running (${shownSeen} above). Counts marked + are lower bounds`
+            + `${brief.production.partial ? '; the read stopped at its budget, so every count is a lower bound' : ''}.`);
+    }
+    else
+        lines.push('  No production telemetry for this repository: set it up to see how this code runs for real users.');
+    if (brief.functions.length > near.length) {
+        lines.push(`  ${plural(brief.functions.length - near.length, 'more function')} further away (all of them are in --json).`);
+    }
+    for (const item of brief.leftOut)
+        lines.push(`  Left out: ${item.count} (${safe(item.reason)})`);
+    lines.push('', chalk.bold('What could break, from failure patterns that fit this change'));
+    if (brief.planning === null)
+        lines.push('  No planning ran for this change: no ideas of ours to offer.');
+    else {
+        if (brief.planning.ideas.length === 0)
+            lines.push('  No situation was planned for this change.');
+        brief.planning.ideas.forEach((idea, index) => lines.push(`  ${index + 1}. Try: ${safe(idea.exercise)}`, ...(idea.setup.length ? [`     Set up first: ${idea.setup.map(safe).join('; ')}`] : []), `     Watch: ${safe(idea.watch)}`, `     Why: ${safe(idea.why)}`, `     It would show as: ${safe(idea.failure)}`, `     Starts from: ${safe(idea.start)}`));
+        if (brief.planning.unresolved.length) {
+            lines.push('  Changes no behavior group holds (no ideas of ours for these):');
+            for (const change of brief.planning.unresolved)
+                lines.push(`    ${safe(change.changeKey)}: ${safe(change.reason)}`);
+        }
+    }
+    lines.push('', 'Next: pick the ideas worth trying, add your own, and say what the change is for:', '  haystack verify --intent "<what the change is for>" --idea "<something to try>" [--idea ...]', 'Your ideas are explored first; the ideas above are explored in every crawl too.');
+    return lines.join('\n');
+}
+/** `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. */
+export async function preVerifyCommand(options) {
+    const note = (line) => { if (options.json)
+        console.error(line);
+    else
+        console.log(line); };
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'prepare', repositoryOverride(options.repo));
+    const request = capture.derivation.request;
+    const change = checkedChange(request.baseCommit, request.workCommit);
+    const finish = (onboarding, view) => {
+        if (options.json)
+            process.stdout.write(`${JSON.stringify(withSchema('pre-verify', { change, onboarding,
+                run: view === null ? null : { runId: view.runId, status: view.status }, brief: view === null ? null : briefOf(view) }), null, 2)}\n`);
+    };
+    if (!request.crawl) {
+        note(`Nothing to check: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
+        finish(null, null);
+        return;
+    }
+    note(checkedLine(change));
+    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 });
+    let view = await readWithRetries(() => readCrawl(identity, auth.token));
+    let onboarding = null;
+    const stale = view === null ? null : staleCrawl(view, identity);
+    // A run of this capture that is preparing, prepared or crawling holds (or will hold) the brief; any other is asked for again,
+    // in mode 'prepare' (amendment 12: that never narrows a crawl).
+    if (view === null || (stale !== null && stale !== 'prepare-only')) {
+        const found = view === null || stale === null ? null : { view, stale };
+        let submitted = await submitCapture(capture, auth.token, found);
+        note(submitted.line);
+        if (submitted.onboarding !== null) {
+            onboarding = await readWithRetries(() => readOnboardingStatus(identity.repository, identity.baseCommit, auth.token));
+            reportOnboardingState(onboarding);
+            if (options.wait !== false && onboarding.state === 'onboarding') {
+                onboarding = await waitForOnboarding(onboarding, auth.token, progress, 'haystack pre-verify');
+                reportOnboardingState(onboarding);
+            }
+            if (onboarding.state !== 'ready') {
+                if (options.json)
+                    finish(onboarding, null);
+                else
+                    console.log(formatOnboarding(onboarding));
+                process.exitCode = onboardingExitCode(onboarding);
+                return;
+            }
+            note('The app is onboarded for this base.');
+            submitted = await submitCapture(capture, auth.token, found);
+            note(submitted.line);
+        }
+        if (submitted.runId === null) {
+            finish(onboarding, null);
+            process.exitCode = 1;
+            return;
+        }
+        const runId = submitted.runId;
+        view = await readWithRetries(() => readCrawlRun(runId, identity, auth.token));
+    }
+    if (options.wait !== false && briefOf(view) === null && !TERMINAL.has(reportedStatus(view)))
+        view = await waitForBrief(view, identity, auth.token);
+    const brief = briefOf(view);
+    if (options.json)
+        finish(onboarding, view);
+    else if (brief !== null)
+        console.log(formatBrief(brief));
+    else if (!TERMINAL.has(reportedStatus(view)))
+        console.log(`The brief is not ready yet: ${currentStep(view)}. Run \`haystack pre-verify\` again to see it.`);
+    // What gets a brief now depends on how the run ended (Bugbot): a `prepared` one is crawled by `haystack verify`, whose answers
+    // carry it; a completed one is never run again, so only a new capture (any edit) is prepared afresh; an incomplete or cancelled
+    // one is asked for again by the next pre-verify.
+    else
+        console.log(`Run ${view.runId} ended (${view.status}) without a brief${view.error ? `: ${errorWords(view.error)}` : ''}. `
+            + (view.status === 'prepared' ? 'Run `haystack verify` to crawl the change; its results carry the brief.'
+                : view.status === 'completed' ? 'It was checked before briefs existed and is not run again: change anything in the checkout and run `haystack pre-verify` again.'
+                    : 'Run `haystack pre-verify` again to prepare it again.'));
+    if (brief === null && TERMINAL.has(reportedStatus(view)))
+        process.exitCode = 2;
+}
 export async function verifyCommand(options) {
     // In --json mode stdout carries the one document; every other line goes to stderr.
     const note = (line) => { if (options.json)
         console.error(line);
     else
         console.log(line); };
-    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'crawl', repositoryOverride(options.repo), minutesOption(options.minutes), poolOption(options.pool));
+    const agent = agentDirection(options);
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'crawl', repositoryOverride(options.repo), minutesOption(options.minutes), poolOption(options.pool), agent);
     const request = capture.derivation.request;
     const change = checkedChange(request.baseCommit, request.workCommit);
     if (!request.crawl) {
@@ -745,8 +1004,9 @@ export async function verifyCommand(options) {
     let view = await readWithRetries(() => readCrawl(identity, auth.token));
     let onboarding = null;
     const stale = view === null ? null : staleCrawl(view, identity);
-    // A pinned pool is its own crawl (amendment 16), which the capture read cannot tell apart: always submit, and follow that run.
-    if (view === null || stale !== null || options.pool !== undefined) {
+    // A pinned pool (amendment 16), an intent or ideas (amendment 17) make their own crawl, which the capture read cannot tell
+    // apart: always submit, and follow that run (the same ones again are the same run).
+    if (view === null || stale !== null || options.pool !== undefined || agent.intent !== undefined || agent.ideas !== undefined) {
         const found = view === null || stale === null ? null : { view, stale };
         let submitted = await submitCapture(capture, auth.token, found);
         note(submitted.line);

package/dist/index.js

@@ -85,6 +85,7 @@ const editRulesCommand = lazy(() => import('./commands/rules.js'), 'editRulesCom
 const validateRulesCommand = lazy(() => import('./commands/rules.js'), 'validateRulesCommand');
 const systemMapValidateCommand = lazy(() => import('./commands/system-map.js'), 'systemMapValidateCommand');
 const verifyCommand = lazy(() => import('./commands/verify.js'), 'verifyCommand');
+const preVerifyCommand = lazy(() => import('./commands/verify.js'), 'preVerifyCommand');
 const headlessLoginCommand = lazy(() => import('./commands/tokens.js'), 'headlessLoginCommand');
 const headlessLogoutCommand = lazy(() => import('./commands/tokens.js'), 'headlessLogoutCommand');
 const listTokensCommand = lazy(() => import('./commands/tokens.js'), 'listTokensCommand');
@@ -146,6 +147,7 @@ program
     .command('init')
     .description('Set this repository up for `haystack verify` and start onboarding the app')
     .option('-y, --yes', 'Make the changes without asking')
+    .option('--notes <file>', 'A JSON file (- for stdin) of what you know about running the app; see below')
     .option('--json', 'The result as one JSON document on stdout (see `haystack schema init`)')
     .addHelpText('after', `
 There is no setup file: Haystack works out how to run the app from what the
@@ -161,6 +163,18 @@ Then it starts onboarding the app, so it is usually ready by the first
 \`haystack verify\`. Running it again changes only what is missing and shows
 where onboarding is (\`haystack verify onboarding\` shows that too).
 
+--notes tells onboarding what a coding agent working here already knows, so it
+does not have to work it out (a wrong guess at the start command can cost half
+an hour). The file is JSON with any of three notes, each plain text:
+  run       how production installs, builds and starts the app: the commands
+            and their directory, the port, the databases and services and their
+            versions, migrations, the environment variables it needs (names and
+            what they are for, never secret values)
+  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.
+
 Exit codes:
   0  set up: onboarding is running or the app is ready
   1  the command failed
@@ -174,7 +188,7 @@ Exit codes:
 Examples:
   haystack init
   haystack init --yes
-  haystack init --yes --json
+  haystack init --yes --json --notes haystack-notes.json
 `)
     .action(options => runPublicCommand(() => initCommand(options), options.json));
 program
@@ -231,6 +245,9 @@ const verify = program
     .option('--no-wait', 'Print the crawl\'s current state and return without waiting')
     .option('--minutes <n>', 'How long the crawl may take, 1-30 (default: .haystack.json crawl.minutes, else 3)')
     .addOption(new Option('--pool <pool>', 'Where the crawl\'s clones are created: fleet, freestyle or auto (default auto)').hideHelp())
+    .option('--intent <sentence>', 'What your change is for, in a sentence: the judge reads it so a difference you meant is not called a bug')
+    .option('--idea <text>', 'Something to try in the app, said as you would to a tester (repeat for more); each is explored first', (value, previous = []) => [...previous, value])
+    .option('--ideas-file <path>', 'A JSON array of more ideas')
     .option('--json', 'The crawl as one JSON document on stdout (see `haystack schema verify`)')
     .addHelpText('after', `
 Run inside a git checkout; nothing needs to be committed or pushed. It captures
@@ -242,6 +259,12 @@ 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.
 
+The coding agent that made the change can say what it is for (--intent) and
+what to try (--idea, as many as it likes, or --ideas-file). Each idea is
+explored before anything else, and the answer says what became of it: tried,
+could not try (and why), or not finished in time. Other ideas make another
+crawl of the same code; the same ones again follow the same crawl.
+
 A crawl builds the app with and without your change, starts from the changed
 code, explores outward with both side by side, and double-checks and judges
 every difference it can within its time: 3 minutes unless the repository's
@@ -282,6 +305,28 @@ Examples:
   haystack verify hosted status cv_<48 lowercase hex characters> --wait
 `)
     .action(options => runPublicCommand(() => verifyCommand(options), options.json));
+program
+    .command('pre-verify')
+    .description('Before a check: what your change touches, and what could break in it')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--no-wait', 'Print what is known now and return without waiting for the brief')
+    .option('--json', 'The brief as one JSON document on stdout (see `haystack schema pre-verify`)')
+    .addHelpText('after', `
+Run inside a git checkout, like haystack verify. It captures the checkout the
+same way, builds and prepares the change when nothing has yet (the turn-end
+hook usually has), and prints its brief: the functions the change touches, the
+changed ones and those one step away first (every one is in --json), and
+Haystack's own ideas of what could break, each with what to set up, what to do
+and what to watch. It never starts a crawl.
+
+Then hand back what the change is for and what to try:
+  haystack verify --intent "<what the change is for>" --idea "<something to try>"
+
+Exit codes: 0 with a brief; 2 when the run ended without one; 3 when the app's
+onboarding is blocked; 1 when the command failed.
+`)
+    .action(options => runPublicCommand(() => preVerifyCommand(options), options.json));
 /**
  * Options for a `verify` subcommand: its own values, plus any option the user
  * passed to an ancestor (`haystack verify --no-wait hosted status ...`).
@@ -889,7 +934,17 @@ program
     .option('--json', 'Output the answer and every consulted customer-facing source as JSON')
     .option('--session <id>', 'Continue a previous Ask Haystack session')
     .action((ref, question, options) => runPublicCommand(() => askHaystackCommand(ref, question, options), options.json));
-const telemetry = program.command('telemetry').description('Add privacy-safe production telemetry without an application SDK');
+const telemetry = program.command('telemetry').description('Add privacy-safe production telemetry without an application SDK')
+    .addHelpText('after', `
+Next.js bundles its server code, so instead of \`instrument\` add the CLI as a
+dependency and wrap next.config (Next 15.4+, Turbopack or --webpack):
+  import { withHaystackTelemetry } from '@haystackeditor/cli/next';
+  export default withHaystackTelemetry(nextConfig);
+\`next build\` then instruments git-tracked server source and prints the
+NODE_OPTIONS=--require=... preload to start the server with. \`next start\`
+loads next.config, so it needs the CLI as a production dependency; standalone
+output (server.js) does not load next.config, so a dev dependency suffices.
+`);
 telemetry
     .command('instrument <dist>')
     .description('Instrument compiled Node.js output without changing application source')

package/dist/schema.js

@@ -20,10 +20,11 @@ export const SCHEMA_VERSIONS = {
     action: '1.0.0',
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '1.0.2',
-    'verify-answer': '1.0.0',
+    verify: '1.0.4',
+    'pre-verify': '1.0.1',
+    'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',
-    init: '1.0.0',
+    init: '1.0.1',
     login: '1.0.0',
     error: '1.0.0',
 };

package/dist/telemetry/next-loader.cjs

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Bundler loader behind `withHaystackTelemetry` (./next.ts). It speaks the
+ * webpack loader API subset Turbopack also implements (getOptions, async,
+ * resourcePath) and is CommonJS because both bundlers' loader runners can
+ * require() it; the instrumenter itself is ESM and is imported on first use.
+ *
+ * Per module: leave it alone unless it is git-tracked repository source
+ * outside node_modules; otherwise instrument it at its repository path and
+ * record its sites in this build's session directory for the post-compile
+ * step. A module that is not instrumented is returned byte-for-byte.
+ */
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// Must equal the directory names in ./next.ts (an ESM module this CommonJS
+// file cannot import synchronously).
+const MODULES_DIRECTORY = 'modules';
+const UNPARSED_DIRECTORY = 'unparsed';
+let telemetry = null;
+const trackedByRoot = new Map();
+function loadTelemetry() {
+    telemetry ??= import('../commands/telemetry.js').then(async (module) => {
+        await module.preloadBabel();
+        return module;
+    });
+    return telemetry;
+}
+/** Git-tracked files under the repository root, once per loader process. */
+function trackedFiles(sourceRoot) {
+    let tracked = trackedByRoot.get(sourceRoot);
+    if (!tracked) {
+        const listed = (0, node_child_process_1.execFileSync)('git', ['ls-files', '-z'], {
+            cwd: sourceRoot,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            maxBuffer: 256 * 1024 * 1024,
+        });
+        tracked = new Set(listed.split('\0').filter(Boolean));
+        trackedByRoot.set(sourceRoot, tracked);
+    }
+    return tracked;
+}
+async function instrument(context, source, options) {
+    const relativePath = (0, node_path_1.relative)(options.sourceRoot, context.resourcePath);
+    if (!relativePath || relativePath.startsWith('..') || (0, node_path_1.isAbsolute)(relativePath))
+        return null;
+    const sourcePath = relativePath.split(node_path_1.sep).join('/');
+    if (sourcePath.split('/').includes('node_modules') || !trackedFiles(options.sourceRoot).has(sourcePath)) {
+        return null;
+    }
+    const result = (await loadTelemetry()).instrumentBundledModule(source, {
+        sourcePath,
+        controlChannel: options.controlChannel,
+        runtimeIntegrity: options.runtimeIntegrity,
+    });
+    if (result.kind === 'unchanged')
+        return null;
+    if (result.kind === 'unparsed') {
+        // Ship it as written and name it in the build's report: the bundler's
+        // compiler accepted syntax Babel does not, which is no reason to fail.
+        const record = { sourcePath, reason: result.reason };
+        writeSessionRecord(context, options, UNPARSED_DIRECTORY, sourcePath, source, record);
+        return null;
+    }
+    // A module with nothing to probe (only module-scope declarations, types)
+    // ships unchanged and adds nothing to the manifest.
+    if (result.sites.length === 0)
+        return null;
+    const record = { sourcePath, probes: result.probes, sites: result.sites };
+    writeSessionRecord(context, options, MODULES_DIRECTORY, sourcePath, source, record);
+    return result.code;
+}
+function writeSessionRecord(context, options, directoryName, sourcePath, source, record) {
+    // The record must be written by every build that ships this module, so a
+    // persisted webpack cache entry may not stand in for running the loader.
+    context.cacheable?.(false);
+    // One record per (path, text). Next compiles one file once per server layer
+    // (RSC, SSR), possibly concurrently; identical input gives identical bytes,
+    // and the rename keeps a reader from seeing a half-written file.
+    const name = (0, node_crypto_1.createHash)('sha256').update(sourcePath).update('\0').update(source).digest('hex');
+    const directory = (0, node_path_1.join)(options.sessionDirectory, directoryName);
+    (0, node_fs_1.mkdirSync)(directory, { recursive: true });
+    const temporary = (0, node_path_1.join)(directory, `.${name}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+    (0, node_fs_1.writeFileSync)(temporary, JSON.stringify(record));
+    (0, node_fs_1.renameSync)(temporary, (0, node_path_1.join)(directory, `${name}.json`));
+}
+function haystackTelemetryNextLoader(source, sourceMap) {
+    const callback = this.async();
+    instrument(this, source, this.getOptions()).then(code => code === null ? callback(null, source, sourceMap) : callback(null, code), (error) => callback(error instanceof Error ? error : new Error(String(error))));
+}
+module.exports = haystackTelemetryNextLoader;

package/dist/telemetry/next.d.ts

@@ -0,0 +1,33 @@
+import { type FileProbeCounts, type InstrumentedSite } from '../commands/telemetry.js';
+/** Options the config hands every loader invocation; JSON for Turbopack. */
+export interface NextTelemetryLoaderOptions {
+    /** Repository root (git top level); every site path is relative to it. */
+    sourceRoot: string;
+    /** This build's hand-off directory between loaders and the post-compile step. */
+    sessionDirectory: string;
+    controlChannel: string;
+    runtimeIntegrity: string;
+}
+/** One instrumented module, as a loader records it for the post-compile step. */
+export interface NextTelemetryModuleRecord {
+    sourcePath: string;
+    probes: FileProbeCounts;
+    sites: InstrumentedSite[];
+}
+/** A server module shipped uninstrumented because Babel could not parse it. */
+export interface NextTelemetryUnparsedRecord {
+    sourcePath: string;
+    reason: string;
+}
+/**
+ * Wrap a Next config (object or function). Every phase but the production
+ * build returns the application's config unchanged.
+ *
+ * Generic so the application's own types pass through: a typed
+ * `(phase, { defaultConfig }: { defaultConfig: NextConfig }) => NextConfig`
+ * keeps its context type (a fixed `unknown` parameter would reject it under
+ * strictFunctionTypes), and the result is Next's `NextConfig` when that is
+ * what went in, without this package importing `next`.
+ */
+export declare function withHaystackTelemetry<Config extends object, Context>(nextConfig: (phase: string, context: Context) => Config | Promise<Config>): (phase: string, context: Context) => Promise<Config>;
+export declare function withHaystackTelemetry<Config extends object>(nextConfig: Config): (phase: string, context?: unknown) => Promise<Config>;