@haystackeditor/cli 0.25.1 → 0.27.0

package/dist/commands/capture-brief.js

@@ -1,63 +1,73 @@
 /** CAPTURE-V1 rule 7b in `haystack pre-verify`: the routes a change touches (the brief's blast-radius files and the changed
  * files, joined through the route manifest's source entries) with their share of captured sessions over the window, the union
- * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. The application is the
- * one `.haystack/capture.json` names (rule 8b, written by `haystack init`); a checkout without it has no capture and the brief
- * is exactly as before. A capture read that fails is reported in the block and never fails the command. */
-import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+ * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. One section per app
+ * whose `.haystack/capture.json` (rule 8b, written by `haystack init` in the app's directory, apps/web in a monorepo) records it,
+ * found as init finds them (app-config.ts); a checkout without one has no capture and the brief is exactly as before. A capture
+ * read that fails is reported in its section and never fails the command. */
+import { join, posix } from 'node:path';
 import chalk from 'chalk';
-import { classifyHttpError } from '../utils/haystack-api.js';
+import { CAPTURE_CONFIG_PATH, captureConfigDirs, readCaptureConfig } from '../capture/app-config.js';
+import { classifyHttpError, repoApiPath } from '../utils/haystack-api.js';
 import { gatewayFetch } from './case-batch.js';
 import { CAPTURE_APPLICATION_ID, CAPTURE_WINDOW_PATH, captureChangedRoutes, } from './capture-contract.js';
-/** Rule 8b: the application identity init commits (key, repository id, application id, adapter). */
-export const CAPTURE_IDENTITY_FILE = '.haystack/capture.json';
-/** The checkout's application id, null without the identity file, or why the file cannot be read. */
-function captureApplication(gitRoot) {
-    const path = join(gitRoot, CAPTURE_IDENTITY_FILE);
-    if (!existsSync(path))
-        return null;
-    let value;
+/** An app's application id from its record, or why the record cannot give one. */
+function captureApplication(gitRoot, app) {
+    const file = posix.join(app, CAPTURE_CONFIG_PATH);
+    let config;
     try {
-        value = JSON.parse(readFileSync(path, 'utf8'));
+        config = readCaptureConfig(join(gitRoot, app));
     }
     catch (error) {
-        return { unreadable: `${CAPTURE_IDENTITY_FILE} is not JSON (${error instanceof Error ? error.message : String(error)})` };
-    }
-    const applicationId = value?.applicationId;
-    if (typeof applicationId !== 'string' || !CAPTURE_APPLICATION_ID.test(applicationId)) {
-        return { unreadable: `${CAPTURE_IDENTITY_FILE} names no valid applicationId` };
+        return { unreadable: `${file}: ${error instanceof Error ? error.message : String(error)}` };
     }
-    return { applicationId };
+    if (config === null)
+        return { unreadable: `${file} is gone` };
+    if (config.app !== app)
+        return { unreadable: `${file} records the app ${config.app}, not its own directory; run \`haystack init --app ${app}\`` };
+    if (!CAPTURE_APPLICATION_ID.test(config.applicationId))
+        return { unreadable: `${file} names no valid applicationId` };
+    return { applicationId: config.applicationId };
 }
-/** The pre-verify capture block, or null for a checkout with no capture identity. `files`: the brief's function files and the
- * changed files. */
-export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
-    const application = captureApplication(gitRoot);
-    if (application === null)
-        return null;
+async function readApp(gitRoot, app, repository, token, files, now) {
+    const application = captureApplication(gitRoot, app);
     if ('unreadable' in application)
-        return { applicationId: null, state: 'unavailable', reason: application.unreadable };
+        return { app, applicationId: null, state: 'unavailable', reason: application.unreadable };
     const { applicationId } = application;
     try {
-        const response = await gatewayFetch(`${CAPTURE_WINDOW_PATH}?repository=${encodeURIComponent(repository)}&app=${encodeURIComponent(applicationId)}`, token);
+        const path = repoApiPath(repository, `${CAPTURE_WINDOW_PATH}?app=${encodeURIComponent(applicationId)}`);
+        const response = await gatewayFetch(path, token);
         if (!response.ok)
-            throw await classifyHttpError(response, `Haystack API ${CAPTURE_WINDOW_PATH}`);
+            throw await classifyHttpError(response, `Haystack API ${path}`);
         const answer = await response.json();
         if (answer.version !== 'capture-v1' || answer.applicationId !== applicationId)
             throw new Error('the capture window answer names another application');
         if (answer.window === null)
-            return { applicationId, state: 'no-data' };
-        return { applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
+            return { app, applicationId, state: 'no-data' };
+        return { app, applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
     }
     catch (error) {
-        return { applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
+        return { app, applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
     }
 }
+/** The pre-verify capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
+ * files and the changed files. */
+export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+    let apps;
+    try {
+        apps = captureConfigDirs(gitRoot, []);
+    }
+    catch (error) {
+        return [{ app: '.', applicationId: null, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) }];
+    }
+    if (apps.length === 0)
+        return null;
+    return Promise.all(apps.map(app => readApp(gitRoot, app, repository, token, files, now)));
+}
 const percent = (share) => share === null ? 'n/a' : `${(share * 100).toFixed(1)}%`;
 const plain = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' '); // eslint-disable-line no-control-regex
-/** The block as a coding agent reads it, after the brief. */
+/** One app's block as a coding agent reads it, after the brief. */
 export function formatCapture(capture) {
-    const lines = [chalk.bold('What real users do where your change is (captured sessions)')];
+    const lines = [chalk.bold(`What real users do where your change is (captured sessions of ${capture.app === '.' ? 'the app at the repository root' : plain(capture.app)})`)];
     if (capture.state === 'unavailable') {
         lines.push(`  Captured sessions could not be read${capture.applicationId ? ` for ${plain(capture.applicationId)}` : ''}: ${plain(capture.reason)}`);
         return lines.join('\n');

package/dist/commands/capture-contract.js

@@ -10,7 +10,7 @@ export const CAPTURE_SCRIPT_MAX_BYTES = 8 * 1024;
 export const CAPTURE_ROUTE_ID_MAX = 200;
 /** Rule 4 Publishing: the largest route manifest (current.json and <release>.json), in bytes. */
 export const CAPTURE_MANIFEST_MAX_BYTES = 256 * 1024;
-export const CAPTURE_WINDOW_PATH = '/api/agent/cloud-verifier/capture/window';
+export const CAPTURE_WINDOW_PATH = '/capture/window';
 /** Rule 8(e): telemetry older than this is reported stale; rule 7b: a capture window older than this is stale. */
 export const CAPTURE_EVIDENCE_FRESH_HOURS = 24;
 export const CAPTURE_ROUTE_UNKNOWN = 'unknown';
@@ -39,8 +39,8 @@ export function captureChangedRoutes(window, files, now) {
 }
 export const TELEMETRY_TOKEN_VERSION = 'telemetry-token-v1';
 export const TELEMETRY_ENVIRONMENT = 'production';
-export const TELEMETRY_TOKEN_PATH = '/api/agent/cloud-verifier/telemetry/token';
-export const TELEMETRY_SERVER_STATUS_PATH = '/api/agent/cloud-verifier/telemetry/server';
+export const TELEMETRY_TOKEN_PATH = '/telemetry/token';
+export const TELEMETRY_SERVER_STATUS_PATH = '/telemetry/server';
 export const TELEMETRY_TOKEN_SHA256 = /^[0-9a-f]{64}$/;
 /** Lane A's capture status: GET /api/agent/cloud-verifier/capture/status?repository=&app= (rule 8b's key registration). */
-export const CAPTURE_STATUS_PATH = '/api/agent/cloud-verifier/capture/status';
+export const CAPTURE_STATUS_PATH = '/capture/status';

package/dist/commands/crawl-report.js

@@ -0,0 +1,196 @@
+export const TERMINAL = new Set(['completed', 'prepared', 'incomplete', 'cancelled']);
+export const VERDICTS = ['bug', 'cant-tell', 'being-judged', 'not-a-bug'];
+export const STATUS_WORDS = {
+    queued: 'waiting for a machine',
+    preparing: 'getting ready',
+    crawling: 'exploring the app',
+    draining: 'finishing the last checks',
+    completed: 'finished',
+    prepared: 'built and ready to check',
+    incomplete: 'stopped before finishing',
+    cancelled: 'cancelled',
+};
+export const STAGE_WORDS = {
+    reconcile: 'cleaning up after an earlier try',
+    source: 'rebuilding your change',
+    worlds: 'building and starting the app with and without your change',
+    blast: 'waiting for the analysis of what your change touches',
+    knobs: "reading the app's settings",
+    prepare: 'setting up starting points next to your change',
+    crawl: 'exploring the app',
+    publish: 'saving the results',
+    cleanup: 'shutting down the machines it used',
+};
+export const ERROR_WORDS = {
+    'source-mismatch': 'your change could not be rebuilt exactly as it was captured',
+    'blast-unavailable': 'the analysis of what your change touches was not available',
+    'world-build-failed': 'the app did not build or start, with or without your change',
+    'prepare-failed': 'setting up starting points next to your change failed',
+    'crawl-failed': 'exploring the app failed',
+    'no-capacity': 'there was no room on the machines for it',
+    stalled: 'it stopped making progress',
+    'lease-lost': 'the machine running it stopped responding',
+    cancelled: 'it was cancelled',
+};
+export const SPOT_WORDS = {
+    resolved: 'never reached',
+    loaded: 'loaded but never ran',
+    exposed: 'shown on screen',
+    activated: 'ran',
+    pressed: 'ran when its control was pressed',
+    observed: 'a difference seen',
+    confirmed: 'a difference seen and confirmed',
+    // The stage, not the verdict: a judged difference may be judged not a bug. The findings carry the verdicts.
+    judged: 'a difference seen, confirmed and judged',
+};
+export const VERDICT_WORDS = {
+    bug: 'Bug',
+    'cant-tell': "Can't tell",
+    'being-judged': 'Still being judged',
+    'not-a-bug': 'Not a bug',
+};
+export function plural(count, noun) {
+    return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+export function errorWords(error) {
+    return error.code === 'stalled'
+        ? `${ERROR_WORDS.stalled} while ${STAGE_WORDS[error.stage]}`
+        : ERROR_WORDS[error.code];
+}
+/** What a running crawl is doing now: its stage, except while it waits for a
+ * machine or finishes its last checks, which its status says better. */
+export function currentStep(view) {
+    return view.status === 'queued' || view.status === 'draining' ? STATUS_WORDS[view.status] : STAGE_WORDS[view.stage];
+}
+/** The crawl's results: its sealed manifest, else (amendment 9) its answer at the budget, which has the same findings and reach. */
+export function results(view) {
+    return view.manifest ?? (view.answer?.status === 'answered' ? view.answer : null);
+}
+/** The status the command reports: a running crawl that has answered (amendment 9: its budget is up and its work is
+ * done; only its shutdown remains) reads as completed. */
+export function reportedStatus(view) {
+    return !TERMINAL.has(view.status) && view.answer?.status === 'answered' ? 'completed' : view.status;
+}
+export function headline(view) {
+    const bugs = results(view)?.bugs ?? view.totals.bugs;
+    const found = bugs > 0 ? ` It found ${plural(bugs, 'bug')} before it stopped.` : '';
+    switch (reportedStatus(view)) {
+        case 'completed':
+            return bugs > 0 ? `Found ${plural(bugs, 'bug')} in your change.` : 'No bugs found in your change.';
+        case 'incomplete': {
+            const error = results(view)?.error ?? view.error;
+            return `The crawl could not finish: ${error ? errorWords(error) : 'no reason was recorded'}.${found}`;
+        }
+        case 'prepared':
+            // Amendment 12: the turn-end hook built and froze this change; `haystack verify` asks for the crawl itself.
+            return 'Your change is built and ready to check, but was not crawled yet. Run `haystack verify` to check it.';
+        case 'cancelled':
+            return `The crawl was cancelled.${found}`;
+        default: {
+            const so = bugs > 0 ? ` ${plural(bugs, 'bug')} found so far.` : '';
+            if (view.cancelRequested) {
+                return `Being cancelled: ${currentStep(view)}.${so}`;
+            }
+            return `Still running: ${currentStep(view)}.${so}`;
+        }
+    }
+}
+export function verifyReport(view) {
+    const status = reportedStatus(view);
+    const published = results(view);
+    const error = published?.error ?? view.error;
+    const explored = published !== null && view.clocks.crawlStartedAt !== null;
+    const findings = explored ? VERDICTS.flatMap(verdict => published.findings.filter(finding => finding.verdict === verdict)) : [];
+    const ideaWords = { covered: 'tried', blocked: 'could not try', unfinished: 'not finished' };
+    return {
+        runId: view.runId,
+        repository: view.repository,
+        title: view.changeTitle,
+        baseCommit: view.baseCommit,
+        workCommit: view.workCommit,
+        status,
+        headline: headline(view),
+        bugs: published?.bugs ?? view.totals.bugs,
+        findings: findings.map(finding => ({
+            id: finding.id,
+            verdict: finding.verdict,
+            why: finding.why,
+            start: finding.start,
+            steps: finding.steps,
+            outsideServices: finding.standIns && (finding.standIns.old.length > 0 || finding.standIns.new.length > 0)
+                ? { withoutChange: finding.standIns.old, withChange: finding.standIns.new }
+                : null,
+        })),
+        spots: explored ? published.reach.spots.map(spot => ({
+            file: spot.file,
+            line: spot.line,
+            reached: spot.furthest === null ? 'never reached' : SPOT_WORDS[spot.furthest],
+            reachedBy: spot.reachedBy && { start: spot.reachedBy.start, steps: spot.reachedBy.steps, page: spot.reachedBy.page },
+            findingIds: spot.findingIds,
+        })) : [],
+        ideas: explored && published.ideas !== undefined
+            ? published.ideas.map(idea => ({ text: idea.text, result: ideaWords[idea.state], reason: idea.reason, findingIds: idea.findingIds }))
+            : null,
+        neverRan: explored ? {
+            files: published.reach.unreachedChangedFiles,
+            functions: published.reach.blast === null ? null : { ran: published.reach.blast.ran, total: published.reach.blast.functions },
+        } : null,
+        notFinishedInTime: explored ? published.notFinishedInTime : 0,
+        outsideServiceGaps: explored ? published.standIns?.gaps ?? [] : [],
+        error: error ? { code: error.code, message: error.message } : null,
+        machinesNotProvenShutDown: TERMINAL.has(view.status) ? view.totals.cleanupUnproven : 0,
+    };
+}
+/** The report as markdown: headings an agent can navigate, bugs first, each with the steps to see it. */
+export function reportMarkdown(report) {
+    const lines = [`# ${report.headline}`, '',
+        `Change: ${report.title}`, `Check ${report.runId} of ${report.repository}: base ${report.baseCommit.slice(0, 12)}, change ${report.workCommit.slice(0, 12)}.`];
+    if (report.error && report.status !== 'completed')
+        lines.push(`Details: ${report.error.message}`);
+    if (report.neverRan === null) {
+        lines.push('', TERMINAL.has(report.status)
+            ? 'Nothing about the change was measured: the crawl did not explore the app.'
+            : 'Where the change shows up, and what the crawl found, appear when it finishes.');
+        return lines.join('\n') + '\n';
+    }
+    lines.push('', '## Where the change shows up in the app');
+    if (report.spots.length === 0)
+        lines.push('No changed spots were recorded.');
+    for (const spot of report.spots) {
+        lines.push(`- \`${spot.file}:${spot.line}\`: ${spot.reached}${spot.findingIds.length ? ` (${plural(spot.findingIds.length, 'finding')})` : ''}`);
+        if (spot.reachedBy)
+            lines.push(`  - reached by: ${[spot.reachedBy.start, ...spot.reachedBy.steps].join(' > ')}${spot.reachedBy.page ? ` (page ${spot.reachedBy.page})` : ''}`);
+    }
+    lines.push('', '## What the crawl found');
+    if (report.findings.length === 0)
+        lines.push('No confirmed differences between the app with and without the change.');
+    report.findings.forEach((finding, index) => {
+        lines.push(`${index + 1}. **${VERDICT_WORDS[finding.verdict]}** (\`${finding.id}\`): ${finding.why ?? 'no reason was recorded.'}`, `   Starting from ${finding.start}:`, ...finding.steps.map((step, n) => `   ${n + 1}. ${step}`));
+        if (finding.outsideServices) {
+            lines.push(`   Outside services on this path, answered by stand-ins: without the change ${finding.outsideServices.withoutChange.join('; ') || 'none'};`
+                + ` with it ${finding.outsideServices.withChange.join('; ') || 'none'}.`);
+        }
+    });
+    if (report.notFinishedInTime > 0) {
+        lines.push(`${plural(report.notFinishedInTime, 'difference')} ${report.notFinishedInTime === 1 ? 'was' : 'were'} still being checked when its time ran out.`);
+    }
+    if (report.ideas !== null) {
+        lines.push('', '## Your ideas');
+        for (const idea of report.ideas)
+            lines.push(`- ${idea.result}: ${idea.text}. ${idea.reason}`);
+    }
+    lines.push('', '## What the crawl never ran');
+    if (report.neverRan.files.length === 0)
+        lines.push('Every changed file ran at least once.');
+    else
+        lines.push('Changed files no path ran:', ...report.neverRan.files.map(file => `- \`${file}\``));
+    if (report.neverRan.functions)
+        lines.push(`${report.neverRan.functions.ran} of ${plural(report.neverRan.functions.total, 'affected function')} ran.`);
+    if (report.outsideServiceGaps.length > 0) {
+        lines.push('', '## Outside services the copy could not imitate', 'Missing coverage of the environment, not bugs in the change:', ...report.outsideServiceGaps.map(gap => `- ${gap}`));
+    }
+    if (report.machinesNotProvenShutDown > 0) {
+        lines.push('', `${plural(report.machinesNotProvenShutDown, 'machine')} it used could not be proven shut down.`);
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/commands/db-profile-upload.js

@@ -14,8 +14,8 @@ import chalk from 'chalk';
 import { DATABASE_PROFILE_UPLOAD_REQUEST_VERSION, parseDatabaseProfileUpload, } from './db-profile-contract.js';
 import { readDatabaseProfileFile } from './db-profile-show.js';
 import { resolveAuthContext } from '../utils/auth.js';
-import { classifyHttpError, haystackApiUrl, readWithRetries, transientReadFailure } from '../utils/haystack-api.js';
-export const DATABASE_PROFILES_PATH = '/api/agent/cloud-verifier/database-profiles';
+import { classifyHttpError, haystackApiUrl, readWithRetries, transientReadFailure, repoApiPath } from '../utils/haystack-api.js';
+export const DATABASE_PROFILES_PATH = '/database-profiles';
 /** GitHub's owner and repository name alphabets. */
 const REPOSITORY = /^([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))\/([A-Za-z0-9_.-]{1,100})$/u;
 /** Run-map dependency ids are stable kebab-case ids (the same check as
@@ -60,7 +60,7 @@ export async function uploadDatabaseProfile(request, token) {
     }
 }
 async function uploadDatabaseProfileOnce(request, token) {
-    const response = await fetch(haystackApiUrl(DATABASE_PROFILES_PATH), {
+    const response = await fetch(haystackApiUrl(repoApiPath(request.repository, DATABASE_PROFILES_PATH)), {
         method: 'POST',
         headers: {
             Authorization: `Bearer ${token}`,

package/dist/commands/feedback.js

@@ -0,0 +1,66 @@
+/**
+ * haystack feedback <message...>
+ *
+ * Tells the Haystack team something, in a sentence: a verify that went wrong,
+ * an output that confused you, a missing option. Meant for coding agents as
+ * much as for people: when Haystack gets in the way, say so here and keep
+ * going. The message lands in the team's Slack at once, with the CLI version,
+ * the platform and the repository (when run inside a GitHub checkout).
+ *
+ * `-` as the whole message reads it from stdin.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { withSchema } from '../schema.js';
+import { resolveAuthContext } from '../utils/auth.js';
+import { parseRemoteUrl } from '../utils/git.js';
+import { haystackJson } from '../utils/haystack-api.js';
+export const FEEDBACK_MAX_CHARS = 4000;
+function cliVersion() {
+    const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return JSON.parse(readFileSync(pkgPath, 'utf8')).version;
+}
+/** The checkout's GitHub repository, or null outside one (feedback never needs a repository). */
+function currentRepository() {
+    try {
+        const remote = parseRemoteUrl();
+        return `${remote.owner}/${remote.repo}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function buildFeedbackRequest(message, options, repository) {
+    const text = message.trim();
+    if (!text)
+        throw new Error('Say what happened: haystack feedback "<message>" (or - to read it from stdin)');
+    if (text.length > FEEDBACK_MAX_CHARS) {
+        throw new Error(`Feedback is ${text.length} characters; keep it under ${FEEDBACK_MAX_CHARS}`);
+    }
+    return {
+        message: text,
+        context: {
+            cliVersion: cliVersion(),
+            platform: `${process.platform}-${process.arch} node ${process.versions.node}`,
+            repository,
+            runId: options.run ?? null,
+        },
+    };
+}
+export async function feedbackCommand(words, options) {
+    const message = words.length === 1 && words[0] === '-' ? readFileSync(0, 'utf8') : words.join(' ');
+    const request = buildFeedbackRequest(message, options, currentRepository());
+    const { token } = await resolveAuthContext({ preferredLogin: options.account });
+    await haystackJson('/v1/feedback', token, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(request),
+    });
+    if (options.json) {
+        process.stdout.write(JSON.stringify(withSchema('feedback', { status: 'sent' }), null, 2) + '\n');
+        return;
+    }
+    console.log(chalk.green('Sent to the Haystack team.'));
+}

package/dist/commands/init-telemetry.js

@@ -20,19 +20,21 @@
  *   - the report (8e). InitTelemetryReport, plus the person's steps beside it: the ingest token (init never mints, prints,
  *     stores or reads one), production's environment, the start command, the deploy and the off switches (13c).
  */
-import { spawnSync } from 'node:child_process';
-import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { 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 { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
-import { classifyHttpError } from '../utils/haystack-api.js';
+import { classifyHttpError, repoApiPath } from '../utils/haystack-api.js';
 import { gatewayFetch } from './case-batch.js';
 import { CAPTURE_EVIDENCE_FRESH_HOURS, CAPTURE_STATUS_PATH, } from './capture-contract.js';
 import { captureAnswers, planCapture } from './init-capture.js';
 import { discoverApps } from '../capture/adapters/index.js';
+import { CAPTURE_CONFIG_PATH, recordedApps } from '../capture/app-config.js';
 import { loadBabel } from '../capture/js-ast.js';
 import { lineDiff } from './init.js';
+import { lockfileDrift, mergePnpmLockfile } from './lockfile-pin.js';
 import { readTelemetryServerStatus } from './telemetry-token.js';
 import { readFacts } from './verify-onboarding.js';
 /** Lane D1: with the user's yes, init checks browser capture's registration with Haystack around the writes. */
@@ -214,15 +216,20 @@ 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.
     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', spec],
+        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', '--install-strategy=nested', spec],
         yarn: ['yarn', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
         bun: ['bun', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
     }[manager.name];
     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\`)`
+        : `, which adds only the CLI's entries to ${manager?.name}'s lockfile`;
     const reason = argv
-        ? `${why} ${action} with \`${argv.join(' ')}\` in ${inside(gitRoot, appDir)}, which updates ${manager?.name}'s lockfile too.`
+        ? `${why} ${action} with \`${argv.join(' ')}\` in ${inside(gitRoot, appDir)}${lockfileNote}.`
         : `${why} ${action}: a newer release never reaches your build unless you change it.`;
     // The package manager's own word is not taken for it: the manifest must say what the integration needs.
     const check = () => {
@@ -235,7 +242,39 @@ function planDependency(gitRoot, appDir, pkg, after, need) {
         return null;
     };
     const touches = manager === null ? [] : LOCKFILES.map(([lockfile]) => join(manager.root, lockfile));
-    return { kind: 'change', change: change(gitRoot, pkg.path, reason, after, content, argv ? { argv, cwd: appDir, touches, check } : undefined) };
+    const exec = manager === null || argv === null ? undefined : () => pin(manager, appDir, argv);
+    return { kind: 'change', change: change(gitRoot, pkg.path, reason, after, content, argv ? { argv, cwd: appDir, touches, check, exec } : undefined) };
+}
+/** 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];
+    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. */
+function pin(manager, appDir, argv) {
+    const run = (command) => { execFileSync(command[0], command.slice(1), { cwd: appDir, stdio: ['ignore', 2, 2] }); };
+    const lockfile = textLockfile(manager);
+    const before = lockfile ? readFileSync(lockfile.path, 'utf8') : null;
+    const importer = posix.normalize(relative(manager.root, appDir).split(sep).join('/')) || '.';
+    if (manager.name === 'pnpm' && lockfile && before !== null) {
+        // pnpm resolves the CLI, init keeps the rest as it was, and the install takes exactly that lockfile (proving it).
+        run([...argv, '--lockfile-only']);
+        writeFileSync(lockfile.path, mergePnpmLockfile(before, readFileSync(lockfile.path, 'utf8'), importer, CLI_PACKAGE));
+        run(['pnpm', 'install', '--frozen-lockfile']);
+    }
+    else {
+        run(argv);
+    }
+    if (!lockfile || before === null)
+        return;
+    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`);
+    }
 }
 function isNode(value) {
     return !!value && typeof value === 'object' && typeof value.type === 'string' && typeof value.start === 'number';
@@ -819,13 +858,18 @@ export async function planTelemetry(gitRoot, repository, options) {
         // One rule for which directories are apps (capture/adapters/index.ts): a web framework an adapter claims, or a package
         // with a start script.
         await loadBabel();
-        const apps = await discoverApps(gitRoot);
+        // The user's earlier answer first: the one app a .haystack/capture.json records (with its origins and consent, which
+        // captureAnswers reads from it). Several records are as ambiguous as several apps.
+        const discovered = await discoverApps(gitRoot);
+        const recorded = recordedApps(gitRoot, discovered);
+        const apps = recorded.length > 0 ? recorded : discovered;
         if (apps.length !== 1) {
             // Rule 8(a): init never picks among several apps, and never guesses one where it found none.
             const ask = apps.length === 0
                 ? 'init found no app here (no web framework it recognizes and no package with a start script). If the repository has one that serves production, run '
                     + '`haystack init` again with `--app <its directory>`.'
-                : `Ask your user which of these apps serves production: ${apps.join(', ')}; then run \`haystack init\` again with \`--app <that directory>\`.`;
+                : `Ask your user which of these apps serves production: ${apps.join(', ')}${recorded.length > 0 ? ` (each has a ${CAPTURE_CONFIG_PATH})` : ''};`
+                    + ' then run `haystack init` again with `--app <that directory>`.';
             const questions = [ask, ...captureQuestions(options.origins, options.consent)];
             // A notice too, so a preview (which reports no telemetry yet) already says what to ask.
             notices.push(`Telemetry waits for your user's answers: ${questions.join(' ')}`);
@@ -834,6 +878,8 @@ export async function planTelemetry(gitRoot, repository, options) {
                 captureRegistration: null };
         }
         appDir = realpathSync(join(gitRoot, apps[0]));
+        if (recorded.length > 0)
+            notices.push(`Telemetry: the app is ${apps[0]}, as its ${CAPTURE_CONFIG_PATH} records (\`--app\` picks another).`);
     }
     const app = inside(gitRoot, appDir);
     const changes = [];
@@ -915,7 +961,7 @@ async function readJson(path, token) {
 }
 /** Lane A's registration of the application: its newest capture event, or null when it is not registered (404) or has none. */
 async function captureReceived(repository, app, token) {
-    const status = await readJson(`${CAPTURE_STATUS_PATH}?repository=${encodeURIComponent(repository)}&app=${encodeURIComponent(app)}`, token);
+    const status = await readJson(repoApiPath(repository, `${CAPTURE_STATUS_PATH}?app=${encodeURIComponent(app)}`), token);
     return status === null ? null : received(status.lastSeenAt, status.release);
 }
 function withReceived(part, evidence) {

package/dist/commands/init.js

@@ -54,9 +54,11 @@ export const AGENT_NOTE = [
     '- 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 full result, often hundreds of kilobytes, for scripts;',
+    '- Read its 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 @haystackeditor/cli@latest <command>`.',
+    '- 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',
+    '  `haystack feedback "<what happened>"` and keep going: the Haystack team sees it at once.',
     NOTE_END,
 ].join('\n');
 const EXIT_CODES = { planned: 2, 'login-required': 4, 'app-required': 5 };
@@ -310,7 +312,10 @@ function applyChange(gitRoot, planned) {
     if (planned.run) {
         const before = existsSync(planned.target) ? readFileSync(planned.target, 'utf8') : '';
         // Its output goes to stderr: in --json mode stdout carries only the one document.
-        execFileSync(planned.run.argv[0], planned.run.argv.slice(1), { cwd: planned.run.cwd, stdio: ['ignore', 2, 2] });
+        if (planned.run.exec)
+            planned.run.exec();
+        else
+            execFileSync(planned.run.argv[0], planned.run.argv.slice(1), { cwd: planned.run.cwd, stdio: ['ignore', 2, 2] });
         const failed = planned.run.check?.() ?? null;
         if (failed !== null)
             throw new Error(`\`${planned.run.argv.join(' ')}\` ran, but ${failed}.`);