@haystackeditor/cli 0.27.0 → 0.27.2

package/README.md

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

package/dist/capture/app-config.js

@@ -62,7 +62,8 @@ export function recordedApps(gitRoot, candidates) {
             return readCaptureConfig(join(gitRoot, dir))?.app === dir;
         }
         catch (error) {
-            throw new Error(`${posix.join(dir, CAPTURE_CONFIG_PATH)}: ${error instanceof Error ? error.message : String(error)}`);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(dir === '.' ? message : message.replace(CAPTURE_CONFIG_PATH, posix.join(dir, CAPTURE_CONFIG_PATH)));
         }
     });
 }

package/dist/commands/init-telemetry.js

@@ -21,9 +21,9 @@
  *     stores or reads one), production's environment, the start command, the deploy and the off switches (13c).
  */
 import { execFileSync, spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
+import { accessSync, constants, existsSync, lstatSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { delimiter, dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { classifyHttpError, repoApiPath } from '../utils/haystack-api.js';
@@ -103,7 +103,8 @@ function section(json, name) {
 }
 const LOCKFILES = [['pnpm-lock.yaml', 'pnpm'], ['package-lock.json', 'npm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun']];
 /** The package manager that owns the app's lockfile: the nearest `packageManager` field, else the nearest lockfile, from
- * the app up to the repository root. null: no lockfile, so the dependency is written into package.json itself. */
+ * the app up to the repository root (`from` says which). null: no lockfile, so the dependency is written into package.json
+ * itself. */
 function packageManager(gitRoot, appDir) {
     for (let directory = appDir;; directory = dirname(directory)) {
         const manifest = join(directory, 'package.json');
@@ -111,16 +112,32 @@ function packageManager(gitRoot, appDir) {
             const declared = readPackage(manifest).json.packageManager;
             const name = typeof declared === 'string' ? /^(pnpm|npm|yarn|bun)@/.exec(declared)?.[1] : undefined;
             if (name)
-                return { name: name, root: directory };
+                return { name: name, root: directory, from: `${inside(gitRoot, manifest)}'s packageManager field` };
         }
         for (const [lockfile, name] of LOCKFILES) {
             if (isFile(join(directory, lockfile)))
-                return { name, root: directory };
+                return { name, root: directory, from: inside(gitRoot, join(directory, lockfile)) };
         }
         if (directory === gitRoot || dirname(directory) === directory)
             return null;
     }
 }
+/** Whether `command` is an executable on PATH (a package manager init would run, checked before it plans to). */
+function onPath(command) {
+    const extensions = process.platform === 'win32' ? (process.env.PATHEXT ?? '.EXE;.CMD;.BAT').split(';') : [''];
+    for (const directory of (process.env.PATH ?? '').split(delimiter)) {
+        if (directory === '')
+            continue;
+        for (const extension of extensions) {
+            try {
+                accessSync(join(directory, `${command}${extension}`), constants.X_OK);
+                return true;
+            }
+            catch { /* not in this directory */ }
+        }
+    }
+    return false;
+}
 /** The first release whose sites record repository-relative paths (what a registered tenant's src_prefix '' relies on)
  * and that ships the `./next` entry: earlier releases are not compatible with either integration. */
 const CLI_COMPATIBLE_SINCE = [0, 24, 0];
@@ -216,14 +233,29 @@ function planDependency(gitRoot, appDir, pkg, after, need) {
     const spec = `${CLI_PACKAGE}@${version}`;
     const dev = field === 'devDependencies';
     const workspaceRoot = isFile(join(appDir, 'pnpm-workspace.yaml')) ? ['--workspace-root'] : [];
-    // Each package manager's add, as it changes no lockfile entry but the CLI's own (lockfile-pin.ts): npm with its tree
-    // nested under the CLI (hoisting would replace packages the app already locks), pnpm through the merge.
+    // Each package manager's add, as it changes no lockfile entry but the CLI's own (lockfile-pin.ts; pnpm through the merge).
     const argv = manager === null ? null : {
         pnpm: ['pnpm', 'add', '--save-exact', dev ? '--save-dev' : '--save-prod', ...workspaceRoot, spec],
-        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', '--install-strategy=nested', spec],
+        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', spec],
         yarn: ['yarn', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
         bun: ['bun', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
     }[manager.name];
+    const appPath = inside(gitRoot, appDir) || '.';
+    // npm re-resolves entries the CLI does not own whatever the flags (39 in fosrl/pangolin, with --install-strategy=nested
+    // too), so init never rewrites an npm lockfile: the person adds the CLI with npm and sees the lockfile's diff.
+    if (manager?.name === 'npm' && argv) {
+        return { kind: 'manual', why: `${appPath} uses npm (${manager.from}), whose install also re-resolves lockfile entries the CLI does not own, so init`
+                + ` does not run it. Run \`${argv.join(' ')}\` in ${appPath}, check package-lock.json's diff, then run \`haystack init\` again` };
+    }
+    // A package manager that is not installed is never run (rule 13: telemetry never fails init).
+    if (manager && argv && !onPath(manager.name)) {
+        const provide = (manager.name === 'pnpm' || manager.name === 'yarn') && onPath('corepack')
+            ? `run \`corepack enable ${manager.name}\` (corepack is installed here)`
+            : `install it (${manager.name === 'bun' ? 'https://bun.sh' : manager.name === 'yarn' ? 'https://yarnpkg.com/getting-started/install' : 'https://pnpm.io/installation'})`;
+        return { kind: 'manual', why: `${appPath} uses ${manager.name} (${manager.from}), which is not installed here, so init did not run it. Either`
+                + ` ${provide} and run \`haystack init\` again, or run \`${argv.join(' ')}\` in ${appPath} wherever ${manager.name} is installed and then`
+                + ' run `haystack init` again' };
+    }
     const action = promoting ? `Moved from devDependencies to dependencies at ${version}` : `Pinned to ${version}`;
     const lockfileNote = manager?.name === 'pnpm'
         ? `, keeping every other entry of pnpm's lockfile as it was (pnpm's own add re-resolves packages the CLI shares with the app; init adds only the CLI's entries, then \`pnpm install --frozen-lockfile\`)`
@@ -247,12 +279,14 @@ function planDependency(gitRoot, appDir, pkg, after, need) {
 }
 /** The lockfile a package manager writes, in a format lockfile-pin.ts reads (bun's binary lockb aside). */
 function textLockfile(manager) {
-    const name = { pnpm: 'pnpm-lock.yaml', npm: 'package-lock.json', yarn: 'yarn.lock', bun: 'bun.lock' }[manager.name];
+    if (manager.name === 'npm')
+        throw new Error('init never runs npm to pin the CLI');
+    const name = { pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock', bun: 'bun.lock' }[manager.name];
     const path = join(manager.root, name);
     return isFile(path) ? { path, format: manager.name } : null;
 }
 /** Runs the add, so that the lockfile gains the CLI's entries and nothing else moves (rule 13); throws (init then restores
- * every file) when the package manager moved anything else. */
+ * telemetry's files and leaves telemetry manual) when the package manager moved anything else. */
 function pin(manager, appDir, argv) {
     const run = (command) => { execFileSync(command[0], command.slice(1), { cwd: appDir, stdio: ['ignore', 2, 2] }); };
     const lockfile = textLockfile(manager);
@@ -272,8 +306,8 @@ function pin(manager, appDir, argv) {
     const moved = lockfileDrift(lockfile.format, before, readFileSync(lockfile.path, 'utf8'), importer, CLI_PACKAGE);
     if (moved.length > 0) {
         throw new Error(`\`${argv.join(' ')}\` also changed ${moved.length} lockfile ${moved.length === 1 ? 'entry' : 'entries'} the CLI does not own`
-            + ` (${moved.slice(0, 5).join(', ')}${moved.length > 5 ? ', …' : ''}), so init put every file back. Add ${CLI_PACKAGE} at its exact version`
-            + ` to ${inside(manager.root, appDir) || '.'} yourself, keeping the lockfile's other entries, then run \`haystack init\` again`);
+            + ` (${moved.slice(0, 5).join(', ')}${moved.length > 5 ? ', …' : ''}). Add ${CLI_PACKAGE} at its exact version to`
+            + ` ${inside(manager.root, appDir) || '.'} yourself, keeping the lockfile's other entries, then run \`haystack init\` again`);
     }
 }
 function isNode(value) {
@@ -1006,6 +1040,22 @@ export function previewTelemetry(plan, repository, notes) {
     const profile = dbProfile(repository, null, notes);
     return { telemetry: { capture: plan.capture, server: serverPartOf(plan), dbProfileCommand: profile?.command ?? null }, steps };
 }
+/** A telemetry plan with nothing planned, for a run whose telemetry could not be planned at all (failedTelemetry says why). */
+export function emptyTelemetryPlan() {
+    return { app: null, changes: [], notices: [], server: { status: 'manual', kind: null, steps: [] }, settings: null,
+        capture: { status: 'manual', steps: [], received: null }, captureRegistration: null };
+}
+/** Telemetry that could not be set up (a package manager failed, a file init could not read, Haystack not answering): each
+ * part it would have set up is manual with what happened, every file telemetry changed is back, and the rest of init stands
+ * (telemetry never fails init). */
+export function failedTelemetry(plan, failure) {
+    const step = `init could not set up telemetry: ${failure.replace(/\.?\s*$/, '')}. It put back every file telemetry changed; the rest of init is`
+        + ' done. Fix that, then run `haystack init` again.';
+    // A part that was already waiting for answers keeps its questions after what happened.
+    const part = (value) => (value.status === 'unsupported' ? value
+        : { status: 'manual', steps: [step, ...(value.status === 'manual' ? value.steps : [])], received: null });
+    return { telemetry: { capture: part(plan.capture), server: part(serverPartOf(plan)), dbProfileCommand: null }, steps: [step] };
+}
 /** Rule 8(e): the report, and what the person does for telemetry to arrive (the token, production's environment, the start,
  * the deploy) with the off switches (rule 13c). `onboarding` and `notes` feed the data profile. */
 export async function telemetryReport(plan, context) {

package/dist/commands/init.js

@@ -45,16 +45,21 @@ export const AGENT_NOTE = [
     NOTE_BEGIN,
     '## Haystack',
     '',
-    'After you change this app\'s code, or when the user asks you to check a change, run `haystack verify` before you',
-    'call the work done. It runs the app with and without the change, explores it, and reports where the change shows up',
-    'and what broke. It changes nothing, so run it without asking.',
+    'After you change this app\'s code, or when the user asks you to check a change, check it with Haystack before you call',
+    'the work done. It runs the app with and without the change, explores it, and reports what broke. It changes nothing,',
+    'so run it without asking.',
     '',
-    '- It often takes 10 to 15 minutes: give it your longest timeout or run it in the background, and do not pipe it',
+    '1. `haystack pre-verify`: what your change touches, what production and real users do there, and Haystack\'s ideas',
+    '   of what could break.',
+    '2. `haystack verify --intent "<what you were asked to do, in the user\'s words>" --idea "<something to try>"`: keep the',
+    '   ideas worth trying, add your own (repeat --idea); yours are explored first.',
+    '',
+    '- `verify` often takes 10 to 15 minutes: give it your longest timeout or run it in the background, and do not pipe it',
     '  through `tail` or `head`, which hide its progress. If your command times out, run it again: it picks up the same crawl.',
     '- Fix each bug it reports that your change caused, then run `haystack verify` again.',
     '- If it says onboarding needs an answer, ask the user that question and file their choice with',
     '  `haystack verify answer <question-id> <choice>`.',
-    '- Read its short report. `--json` prints the same report as data; `--raw` prints the crawl\'s whole record (large), for scripts;',
+    '- Read verify\'s short report. `--json` prints the same report as data; `--raw` prints the crawl\'s whole record (large), for scripts;',
     '  `haystack verify --help` explains the output and exit codes.',
     '- If `haystack` is not installed, run each command as `npx -y -p @haystackeditor/cli@latest haystack <command>`.',
     '- If Haystack fails, confuses you or gets in your way, say so in a sentence with',
@@ -299,6 +304,33 @@ export function planInit(gitRoot) {
     const notices = [];
     return { changes: [...planStopHook(gitRoot, notices), ...planAgentNotes(gitRoot, notices)], notices };
 }
+/** Makes `changes` all or nothing: one that fails (an install that does not end as planned) restores every file they
+ * touched (bytes, not text: a lockfile can be binary), so no edit is left referencing what was never installed. */
+function applyAll(gitRoot, changes, say) {
+    const before = new Map();
+    for (const planned of changes) {
+        for (const path of [planned.target, ...(planned.run?.touches ?? [])]) {
+            if (!before.has(path))
+                before.set(path, existsSync(path) ? readFileSync(path) : null);
+        }
+    }
+    try {
+        for (const planned of changes) {
+            applyChange(gitRoot, planned);
+            say(chalk.green(`✓ ${planned.action === 'create' ? 'Created' : planned.action === 'delete' ? 'Deleted' : 'Updated'} ${planned.path}`));
+        }
+    }
+    catch (error) {
+        for (const [path, content] of before) {
+            if (content !== null)
+                writeFileSync(path, content);
+            else if (existsSync(path))
+                unlinkSync(path);
+        }
+        throw error;
+    }
+}
+const errorText = (error) => (error instanceof Error ? error.message : String(error));
 function applyChange(gitRoot, planned) {
     const inside = relative(gitRoot, planned.target);
     if (!inside.startsWith('..') && !isAbsolute(inside))
@@ -362,19 +394,35 @@ export async function initCommand(options) {
     // Read before anything else, so notes that cannot be used stop init with nothing done.
     const notes = options.notes === undefined ? null : readNotes(options.notes);
     const plan = planInit(gitRoot);
-    // Telemetry is part of onboarding (CAPTURE-V1 rule 8): planned on every run; a missing answer stops only it.
+    // Telemetry is part of onboarding (CAPTURE-V1 rule 8): planned on every run; a missing answer stops only it. It never fails
+    // init: whatever goes wrong with it (a file it cannot read, a package manager that fails, Haystack not answering) puts its
+    // own files back and leaves it manual with what happened, and the rest of init goes on.
     const telemetryModule = await import('./init-telemetry.js');
     const telemetryOptions = { app: options.app, origins: options.origin ?? [], consent: options.consent, urlRewrites: options.urlRewrites };
-    let telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, telemetryOptions);
+    let telemetryFailure = null;
+    let telemetryPlan = telemetryModule.emptyTelemetryPlan();
+    try {
+        telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, telemetryOptions);
+    }
+    catch (error) {
+        telemetryFailure = errorText(error);
+    }
     const telemetryFrom = plan.changes.length;
     plan.changes.push(...telemetryPlan.changes);
     plan.notices.push(...telemetryPlan.notices);
     let notesWritten = null;
     let telemetry = null;
+    /** Telemetry did not happen: its changes leave the plan (none of them was made), and the report says why. */
+    const telemetryFailed = (error) => {
+        telemetryFailure = errorText(error);
+        plan.changes.splice(telemetryFrom);
+        say(chalk.yellow(`Telemetry was not set up: ${telemetryFailure} The rest of init goes on; the telemetry report says what to do.`));
+    };
     // Before the apply (a preview, or no login), the report is the preview: what telemetry will do, `received` unchecked (null).
-    const report = () => telemetry ?? telemetryModule.previewTelemetry(telemetryPlan, repository, notes);
+    const report = () => (telemetryFailure !== null ? telemetryModule.failedTelemetry(telemetryPlan, telemetryFailure)
+        : telemetry ?? telemetryModule.previewTelemetry(telemetryPlan, repository, notes));
     const showPreview = () => {
-        const preview = telemetryModule.previewTelemetry(telemetryPlan, repository, notes);
+        const preview = report();
         for (const line of telemetryModule.formatTelemetry(preview.telemetry, preview.steps))
             say(line);
         say('');
@@ -424,47 +472,52 @@ export async function initCommand(options) {
             return;
         }
     }
-    // Browser capture's registration (rule 8b), which the preview announced: checked with Haystack now, and when the files
-    // need a new key the telemetry changes are planned again with it (or without capture's, when it is refused).
+    // Init's own changes (the agent instructions, the Stop hook) first, all or nothing: a failure there is init's.
+    try {
+        applyAll(gitRoot, plan.changes.slice(0, telemetryFrom), say);
+    }
+    catch (error) {
+        throw new Error(`${errorText(error)} Every file init changed was restored; nothing was changed.`);
+    }
+    // Then telemetry, all or nothing on its own. Browser capture's registration (rule 8b), which the preview announced, is
+    // checked with Haystack first, and when the files need a new key the telemetry changes are planned again with it (or
+    // without capture's, when it is refused).
     const approved = options.yes === true || plan.changes.length > 0;
-    const capture = telemetryPlan.captureRegistration
-        ? await telemetryModule.prepareCapture(telemetryPlan.captureRegistration, token, say, approved) : null;
-    if (capture?.replan) {
-        telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, { ...telemetryOptions, registration: capture.replan });
-        plan.changes.splice(telemetryFrom, plan.changes.length - telemetryFrom, ...telemetryPlan.changes);
-    }
-    // All or nothing: a change that fails (an install that does not end as planned) restores every file the changes
-    // touched, so no edit is left referencing what was never installed.
-    // Bytes, not text: a lockfile can be binary (bun.lockb).
-    const before = new Map();
-    for (const planned of plan.changes) {
-        for (const path of [planned.target, ...(planned.run?.touches ?? [])]) {
-            if (!before.has(path))
-                before.set(path, existsSync(path) ? readFileSync(path) : null);
+    let capture = null;
+    if (telemetryFailure === null) {
+        try {
+            capture = telemetryPlan.captureRegistration
+                ? await telemetryModule.prepareCapture(telemetryPlan.captureRegistration, token, say, approved) : null;
+            if (capture?.replan) {
+                telemetryPlan = await telemetryModule.planTelemetry(gitRoot, repository, { ...telemetryOptions, registration: capture.replan });
+                plan.changes.splice(telemetryFrom, plan.changes.length - telemetryFrom, ...telemetryPlan.changes);
+            }
+            applyAll(gitRoot, plan.changes.slice(telemetryFrom), say);
         }
-    }
-    try {
-        for (const planned of plan.changes) {
-            applyChange(gitRoot, planned);
-            say(chalk.green(`✓ ${planned.action === 'create' ? 'Created' : planned.action === 'delete' ? 'Deleted' : 'Updated'} ${planned.path}`));
+        catch (error) {
+            try {
+                await capture?.rollback(say);
+            }
+            catch (rollbackError) {
+                say(chalk.yellow(`Capture's registration could not be put back: ${errorText(rollbackError)}`));
+            }
+            telemetryFailed(error);
         }
     }
-    catch (error) {
-        for (const [path, content] of before) {
-            if (content !== null)
-                writeFileSync(path, content);
-            else if (existsSync(path))
-                unlinkSync(path);
+    if (telemetryFailure === null && capture) {
+        try {
+            const captureFollowUp = await capture.finish(say);
+            if (captureFollowUp)
+                telemetryPlan.capture = telemetryModule.withCaptureStep(telemetryPlan.capture, captureFollowUp);
+        }
+        catch (error) {
+            telemetryPlan.capture = telemetryModule.withCaptureStep(telemetryPlan.capture, `Run \`haystack init\` again: Haystack did not take the app's origins (${errorText(error)}).`);
         }
-        await capture?.rollback(say);
-        throw new Error(`${error instanceof Error ? error.message : String(error)} Every file init changed was restored; nothing was changed.`);
     }
-    const captureFollowUp = await capture?.finish(say);
-    if (captureFollowUp)
-        telemetryPlan.capture = telemetryModule.withCaptureStep(telemetryPlan.capture, captureFollowUp);
     let onboarding;
     try {
-        // The notes first: onboarding plans from the facts it starts with, and new notes are new facts (a new onboarding).
+        // The notes first: onboarding plans from the facts it starts with (rule 2, amendment 34: new notes onboard again only while
+        // the repository has no setup, after a run that ended without one).
         if (notes) {
             notesWritten = await writeOnboardingNotes(repository, notes, token);
             say(notesWritten === 'written' ? chalk.green('✓ Wrote the onboarding notes') : chalk.dim('The onboarding notes are already these.'));
@@ -485,8 +538,18 @@ export async function initCommand(options) {
     reportOnboardingState(onboarding);
     say(formatOnboarding(onboarding));
     say('');
-    telemetry = await telemetryModule.telemetryReport(telemetryPlan, { repository, token, onboarding, notes });
-    for (const line of telemetryModule.formatTelemetry(telemetry.telemetry, telemetry.steps))
+    if (telemetryFailure === null) {
+        try {
+            telemetry = await telemetryModule.telemetryReport(telemetryPlan, { repository, token, onboarding, notes });
+        }
+        catch (error) {
+            // What Haystack holds could not be read: the report as previewed (`received` unchecked), and why.
+            const preview = telemetryModule.previewTelemetry(telemetryPlan, repository, notes);
+            telemetry = { telemetry: preview.telemetry, steps: [...preview.steps, `Run \`haystack init --json\` again to read what telemetry Haystack has received (it could not: ${errorText(error)}).`] };
+        }
+    }
+    const shown = report();
+    for (const line of telemetryModule.formatTelemetry(shown.telemetry, shown.steps))
         say(line);
     say('');
     if (onboarding.state === 'ready')

package/dist/commands/lockfile-pin.js

@@ -4,13 +4,14 @@
  * locks older versions of packages the CLI also uses):
  *   - yarn 1, yarn 4 and bun add only the new descriptors and entries; nothing else moves.
  *   - npm hoists the new tree and replaces hoisted packages the app already locks (ws, yaml, zod moved to the CLI's
- *     versions); with `--install-strategy=nested` it places the new tree under the dependency and moves nothing.
+ *     versions), and re-resolves other entries even with `--install-strategy=nested` (39 in fosrl/pangolin): init never
+ *     runs it (init-telemetry.ts leaves the npm install to the person, who sees the lockfile's diff).
  *   - pnpm re-resolves the dependencies of every package the new tree shares with the old one to the newest version in the
  *     graph (47 entries in Rallly, from @smithy/* to express), and no flag stops it. So init lets pnpm resolve the new
  *     dependency (`--lockfile-only`), keeps every entry the lockfile had, adds the entries only the new dependency
  *     reaches (mergePnpmLockfile), and installs exactly that (`pnpm install --frozen-lockfile`, which also proves it).
- * lockfileDrift checks the result for every format init can read, so a package manager that moves anything else fails the
- * change (and init restores every file).
+ * lockfileDrift checks the result for every format init runs, so a package manager that moves anything else fails the
+ * change (and init restores telemetry's files, leaving telemetry manual).
  */
 function unquote(text) {
     if (text.startsWith('\'') && text.endsWith('\''))
@@ -271,11 +272,6 @@ function entriesOf(format, text, importer) {
             }
         }
     }
-    else if (format === 'npm') {
-        const packages = JSON.parse(text).packages ?? {};
-        for (const [key, value] of Object.entries(packages))
-            out.set(key === (importer === '.' ? '' : importer) ? IMPORTER : key, JSON.stringify(value));
-    }
     else if (format === 'yarn') {
         for (const block of text.split(/\n\s*\n/)) {
             const lines = block.split('\n').filter(line => line.trim() !== '' && !line.startsWith('#'));

package/dist/commands/verify-onboarding.js

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

package/dist/commands/verify-precompute.js

@@ -486,7 +486,7 @@ function printResult(result) {
     else if (crawl?.status === 'unavailable')
         console.log(`Crawl unavailable: ${crawlUnavailableText(crawl.reason)}.`);
     else if (crawl?.status === 'onboarding') {
-        console.log(`The app is being onboarded for this base (${crawl.onboardRunId}); this change is built and frozen when it is ready.`
+        console.log(`The app is being onboarded (${crawl.onboardRunId}); this change is built and frozen when it is ready.`
             + ' Run `haystack verify` to check it.');
     }
     else if (crawl?.status === 'onboarding-blocked')

package/dist/commands/verify.js

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

package/dist/index.js

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

package/package.json

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