@haystackeditor/cli 0.23.2 → 0.24.0

package/dist/commands/telemetry.js

@@ -18,7 +18,7 @@ function loadBabel() {
 // @babel/core 8 is ESM-only. require() of ESM works from Node 22.12, but 22.12
 // prints an ExperimentalWarning for it, so the command path loads Babel with
 // import() first and loadBabel() then reuses that module.
-async function preloadBabel() {
+export async function preloadBabel() {
     babelModule ??= await import('@babel/core');
 }
 const INSTRUMENTED_MARKER = '__haystack_telemetry_instrumented_v1__';
@@ -250,7 +250,13 @@ function runtimeControlDeclarations(t, controlName, helperName, specifier, modul
     return [
         t.variableDeclaration('const', [t.variableDeclarator(t.identifier(controlName), t.callExpression(t.functionExpression(null, [], t.blockStatement([
                 t.tryStatement(t.blockStatement([
-                    t.variableDeclaration('const', [t.variableDeclarator(t.identifier('processHost'), t.callExpression(t.identifier('require'), [t.stringLiteral('node:process')]))]),
+                    t.variableDeclaration('const', [t.variableDeclarator(t.identifier('processHost'), 
+                        // A bundled module must not name node:process: the bundler
+                        // would resolve it as a module of its own. The global is the
+                        // same object in a Node server.
+                        moduleType === 'bundled'
+                            ? t.memberExpression(t.identifier('globalThis'), t.identifier('process'))
+                            : t.callExpression(t.identifier('require'), [t.stringLiteral('node:process')]))]),
                     t.ifStatement(t.binaryExpression('in', t.stringLiteral(runtimeBlockedChannel), t.identifier('processHost')), t.returnStatement(fallbackModule('processHost'))),
                     t.variableDeclaration('const', [t.variableDeclarator(t.identifier('loaded'), t.memberExpression(t.identifier('processHost'), t.stringLiteral(runtimeGuardChannel), true))]),
                     t.returnStatement(t.conditionalExpression(t.logicalExpression('&&', t.identifier('loaded'), t.binaryExpression('===', t.unaryExpression('typeof', t.memberExpression(t.identifier('loaded'), t.identifier('safeSelectProbe'))), t.stringLiteral('function'))), t.identifier('loaded'), fallbackModule('processHost'))),
@@ -266,9 +272,10 @@ function passthroughHelper(t, helperName) {
 function sitePassthroughHelper(t, helperName) {
     return t.functionDeclaration(t.identifier(helperName), [t.identifier('value')], t.blockStatement([t.returnStatement(t.identifier('value'))]));
 }
-function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, controlChannel, runtimeIntegrity, includedQualifiedNames) {
+function instrumentSource(code, { sourcePath, runtimeSpecifier, moduleType, controlChannel, runtimeIntegrity, includedQualifiedNames, parserPlugins, recordSourcePositions, skipDirective, moduleScopeProbes, }) {
     if (hasGeneratedInstrumentation(code))
         return null;
+    let skippedByDirective = false;
     const probes = { branches: 0, parameters: 0, bindings: 0, returns: 0, throws: 0 };
     const ordinals = new WeakMap();
     const functionIdentities = new WeakMap();
@@ -297,13 +304,24 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
         const fn = path.isFunction?.() ? path : path.getFunctionParent();
         return fn ? functionIdentities.get(fn.node) ?? `${functionName(fn)}:unmapped` : '(top):0';
     };
-    const site = (fn, qualifiedName, owner, kind, structuralKey, label, allowedFields = []) => {
+    const site = (fn, qualifiedName, owner, kind, structuralKey, 
+    // Candidate nodes for the site's source position, most specific first.
+    // Nodes this pass synthesizes (the return ensureBlock wraps around an
+    // arrow's expression body) have no location; the next candidate does.
+    positionNodes, label, allowedFields = []) => {
         const targetId = `site-${shortHash([sourcePath, owner, kind, structuralKey])}`;
         const value = `${sourcePath}#${fn}:${targetId}${label ? `(${label})` : ''}`;
         // Leave room under the ingestion endpoint's 512-character key cap for a
         // static field label and its longest value-shape outcome.
         if (value.length > 360)
             throw new Error(`Telemetry site exceeds the ingestion key limit in ${sourcePath}`);
+        let position = null;
+        if (recordSourcePositions) {
+            const start = positionNodes.find(node => node?.loc?.start)?.loc.start;
+            if (!start)
+                throw new Error(`Telemetry site ${value} has no source position`);
+            position = { line: start.line, column: start.column };
+        }
         sites.set(value, {
             probe_key: value,
             site_id: targetId,
@@ -314,6 +332,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
             structural_key: structuralKey,
             ...(label ? { label } : {}),
             allowed_fields: [...allowedFields],
+            ...(position ?? {}),
         });
         return value;
     };
@@ -336,8 +355,9 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
             const functionPath = path.isFunction?.() ? path : path.getFunctionParent();
             return Boolean(functionPath && includedQualifiedNames.has(qualifiedFunctionName(functionPath)));
         };
+        const outsideProbedScope = (path) => !moduleScopeProbes && !path.getFunctionParent();
         const wrapTest = (path, syntax) => {
-            if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+            if (skipFileProbes || insideAccessor(path) || !selectedFunction(path) || outsideProbedScope(path))
                 return;
             const testPath = path.get('test');
             const test = testPath?.node;
@@ -347,7 +367,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
             const functionPath = path.getFunctionParent();
             const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
             const ordinal = nextOrdinal(path, `branch:${syntax}`);
-            const branchSite = site(fn, qualifiedName, ownerIdentity(path), 'condition', `${syntax}:${ordinal}`);
+            const branchSite = site(fn, qualifiedName, ownerIdentity(path), 'condition', `${syntax}:${ordinal}`, [test, path.node]);
             testPath.replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstBranch', branchSite), test));
             testPath.skip();
             probes.branches++;
@@ -356,6 +376,11 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
             visitor: {
                 Program: {
                     enter(path) {
+                        if (skipDirective && (path.node.directives ?? []).some((directive) => directive.value?.value === skipDirective)) {
+                            skippedByDirective = true;
+                            path.stop();
+                            return;
+                        }
                         helperName = path.scope.generateUidIdentifier('__haystackTelemetryPassthrough').name;
                         siteHelperName = path.scope.generateUidIdentifier('__haystackTelemetrySitePassthrough').name;
                         runtimeControlName = path.scope.generateUidIdentifier('__haystackTelemetryControl').name;
@@ -424,7 +449,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                         for (const [parameterIndex, parameter] of path.node.params.entries()) {
                             for (const [bindingIndex, identifier] of parameterBindings(t, parameter).entries()) {
                                 const fields = sourceFieldsForParameter(path, identifier.name);
-                                const parameterSite = site(fn, qualifiedFunctionName(path), ownerIdentity(path), 'parameter', `${parameterIndex}:${bindingIndex}:${identifier.name}`, `parameter:${identifier.name}`, fields);
+                                const parameterSite = site(fn, qualifiedFunctionName(path), ownerIdentity(path), 'parameter', `${parameterIndex}:${bindingIndex}:${identifier.name}`, [identifier, parameter, path.node], `parameter:${identifier.name}`, fields);
                                 statements.push(t.expressionStatement(optionalProbeCall(t, siteProbeName(path, '__hstValue', parameterSite), t.identifier(identifier.name))));
                                 probes.parameters++;
                             }
@@ -448,7 +473,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                 },
                 VariableDeclarator: {
                     exit(path) {
-                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path) || outsideProbedScope(path))
                             return;
                         if (!t.isIdentifier(path.node.id) || !path.node.init || !t.isExpression(path.node.init))
                             return;
@@ -456,7 +481,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                         const functionPath = path.getFunctionParent();
                         const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
                         const ordinal = nextOrdinal(path, `binding:${path.node.id.name}`);
-                        const valueSite = site(fn, qualifiedName, ownerIdentity(path), 'binding', `${path.node.id.name}:${ordinal}`, `binding:${path.node.id.name}`);
+                        const valueSite = site(fn, qualifiedName, ownerIdentity(path), 'binding', `${path.node.id.name}:${ordinal}`, [path.node], `binding:${path.node.id.name}`);
                         path.get('init').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstValue', valueSite), path.node.init));
                         path.get('init').skip();
                         probes.bindings++;
@@ -473,7 +498,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                         const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
                         const ordinal = nextOrdinal(path, 'return');
                         const fields = sourceFieldsForReturnedObject(path.node.argument);
-                        const returnSite = site(fn, qualifiedName, ownerIdentity(path), 'return', String(ordinal), 'return', fields);
+                        const returnSite = site(fn, qualifiedName, ownerIdentity(path), 'return', String(ordinal), [path.node, path.node.argument], 'return', fields);
                         path.get('argument').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstValue', returnSite), path.node.argument));
                         path.get('argument').skip();
                         probes.returns++;
@@ -481,7 +506,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                 },
                 ThrowStatement: {
                     exit(path) {
-                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path))
+                        if (skipFileProbes || insideAccessor(path) || !selectedFunction(path) || outsideProbedScope(path))
                             return;
                         if (!path.node.argument || !t.isExpression(path.node.argument))
                             return;
@@ -489,7 +514,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
                         const functionPath = path.getFunctionParent();
                         const qualifiedName = functionPath ? qualifiedFunctionName(functionPath) : '(top)';
                         const ordinal = nextOrdinal(path, 'throw');
-                        const throwSite = site(fn, qualifiedName, ownerIdentity(path), 'throw', String(ordinal), 'throw');
+                        const throwSite = site(fn, qualifiedName, ownerIdentity(path), 'throw', String(ordinal), [path.node, path.node.argument], 'throw');
                         path.get('argument').replaceWith(optionalProbeCall(t, siteProbeName(path, '__hstThrow', throwSite), path.node.argument));
                         path.get('argument').skip();
                         probes.throws++;
@@ -502,7 +527,7 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
     const transformed = babel.transformSync(code, {
         parserOpts: {
             sourceType: 'unambiguous',
-            plugins: ['jsx'],
+            plugins: parserPlugins,
         },
         plugins: [plugin],
         babelrc: false,
@@ -512,6 +537,8 @@ function instrumentSource(code, sourcePath, runtimeSpecifier, moduleType, contro
         retainLines: true,
         compact: false,
     });
+    if (skippedByDirective)
+        return null;
     if (!transformed?.code)
         throw new Error(`Instrumentation produced no code for ${sourcePath}`);
     if (!helperName || !siteHelperName || !runtimeControlName) {
@@ -662,6 +689,24 @@ function sourceForOutput(output, dist, sourceRoot) {
 function runtimeAssetPath() {
     return join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'telemetry', RUNTIME_FILENAME);
 }
+/**
+ * The runtime source bound to one control channel, plus the integrity token
+ * generated probes present to it and the hash a bootstrap verifies before
+ * evaluating it. Deterministic in the channel, so a bundler loader running in
+ * several worker processes and the step that later writes the runtime agree
+ * without exchanging anything.
+ */
+export function authenticateTelemetryRuntime(controlChannel) {
+    const runtimeTemplate = readFileSync(runtimeAssetPath(), 'utf8');
+    if (!runtimeTemplate.includes(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER) ||
+        !runtimeTemplate.includes(RUNTIME_INTEGRITY_PLACEHOLDER)) {
+        throw new Error('Telemetry runtime is missing its authentication placeholders');
+    }
+    const runtimeChannelSource = runtimeTemplate.replaceAll(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER, controlChannel);
+    const integrity = createHash('sha256').update(runtimeChannelSource).digest('hex');
+    const source = runtimeChannelSource.replaceAll(RUNTIME_INTEGRITY_PLACEHOLDER, integrity);
+    return { source, integrity, hash: createHash('sha256').update(source).digest('hex') };
+}
 function readExistingManifest(path) {
     if (!existsSync(path))
         return null;
@@ -741,15 +786,7 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
         normalizedPath(relative(dist, output)),
         normalizeLineEndings(readFileSync(output, 'utf8')),
     ]))}`;
-    const runtimeTemplate = readFileSync(runtimeAssetPath(), 'utf8');
-    if (!runtimeTemplate.includes(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER) ||
-        !runtimeTemplate.includes(RUNTIME_INTEGRITY_PLACEHOLDER)) {
-        throw new Error('Telemetry runtime is missing its authentication placeholders');
-    }
-    const runtimeChannelSource = runtimeTemplate.replaceAll(RUNTIME_CONTROL_CHANNEL_PLACEHOLDER, controlChannel);
-    const runtimeIntegrity = createHash('sha256').update(runtimeChannelSource).digest('hex');
-    const authenticatedRuntime = runtimeChannelSource.replaceAll(RUNTIME_INTEGRITY_PLACEHOLDER, runtimeIntegrity);
-    const authenticatedRuntimeHash = createHash('sha256').update(authenticatedRuntime).digest('hex');
+    const { source: authenticatedRuntime, integrity: runtimeIntegrity, hash: authenticatedRuntimeHash, } = authenticateTelemetryRuntime(controlChannel);
     const pending = [];
     const skipped = [];
     for (const output of outputFiles) {
@@ -765,7 +802,19 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
         if (!SAFE_SOURCE_PATH.test(sourcePath)) {
             throw new Error(`Source path contains a telemetry-reserved character (# or |): ${sourcePath}`);
         }
-        const transformed = instrumentSource(readFileSync(output, 'utf8'), sourcePath, runtimeSpecifierForOutput(output, dist), moduleTypeForOutput(output, dist), controlChannel, runtimeIntegrity, selectiveInstrumentation ? selectedSymbolsBySource.get(sourcePath) ?? new Set() : null);
+        const transformed = instrumentSource(readFileSync(output, 'utf8'), {
+            sourcePath,
+            runtimeSpecifier: runtimeSpecifierForOutput(output, dist),
+            moduleType: moduleTypeForOutput(output, dist),
+            controlChannel,
+            runtimeIntegrity,
+            includedQualifiedNames: selectiveInstrumentation ? selectedSymbolsBySource.get(sourcePath) ?? new Set() : null,
+            parserPlugins: ['jsx'],
+            // Compiled output has no source map here: its coordinates are not the
+            // source's, so sites carry none (see InstrumentedSite.line).
+            recordSourcePositions: false,
+            moduleScopeProbes: true,
+        });
         if (transformed)
             pending.push({ output, source: sourcePath, ...transformed });
     }
@@ -818,6 +867,128 @@ export function instrumentNodeTelemetryBuild(distDirectory, options) {
     writeFileSync(manifestPath, `${JSON.stringify(result, null, 2)}\n`);
     return result;
 }
+// ─── Bundled (source-level) instrumentation ─────────────────────────────────
+// A bundler packs server code into chunks that mirror no source file, so the
+// compiled-output pass above cannot map them. These two entry points let a
+// bundler loader instrument each source module as it is compiled, and a
+// post-compile step write the runtime beside the build. The runtime is never
+// bundled: a preload evaluates it by its real path.
+// `<T>value` casts are JSX in a .tsx file, so typescript and jsx go together
+// only there. Every set parses legacy decorators (TypeScript's
+// experimentalDecorators: `@Entity()` classes, members and parameters), which
+// the generator prints back where they were; `@` is a syntax error anywhere
+// else, so the plugin only widens what parses. Import attributes (`with
+// { type: 'json' }`) and `using` / `await using` are on by default in Babel 8
+// and named so the accepted syntax is stated here; Babel 8 removed the older
+// `assert { }` form, so such a module is one the loader leaves unchanged.
+const SHARED_PARSER_PLUGINS = ['decorators-legacy', 'importAttributes', 'explicitResourceManagement'];
+const BUNDLED_PARSER_PLUGINS = {
+    '.ts': ['typescript', ...SHARED_PARSER_PLUGINS],
+    '.mts': ['typescript', ...SHARED_PARSER_PLUGINS],
+    '.cts': ['typescript', ...SHARED_PARSER_PLUGINS],
+    '.tsx': ['typescript', 'jsx', ...SHARED_PARSER_PLUGINS],
+    '.js': ['jsx', ...SHARED_PARSER_PLUGINS],
+    '.jsx': ['jsx', ...SHARED_PARSER_PLUGINS],
+    '.mjs': ['jsx', ...SHARED_PARSER_PLUGINS],
+    '.cjs': ['jsx', ...SHARED_PARSER_PLUGINS],
+};
+export const BUNDLED_SOURCE_EXTENSIONS = Object.keys(BUNDLED_PARSER_PLUGINS);
+const BUNDLED_REGISTER_FILENAME = 'register.cjs';
+/**
+ * Instrument one source module inside a bundler. `sourcePath` is the
+ * repository-relative path every site records, so production counts join the
+ * change's files and line ranges exactly. A module Babel cannot parse is
+ * reported, not thrown: the bundler's compiler may accept syntax Babel does
+ * not, and telemetry must never be the reason a build fails. Any other error
+ * is ours and stays loud.
+ */
+export function instrumentBundledModule(code, options) {
+    const parserPlugins = BUNDLED_PARSER_PLUGINS[extname(options.sourcePath)];
+    if (!parserPlugins)
+        throw new Error(`Telemetry cannot parse ${options.sourcePath}: unsupported extension`);
+    if (!SAFE_SOURCE_PATH.test(options.sourcePath) || options.sourcePath.startsWith('/') ||
+        options.sourcePath.split('/').some(part => !part || part === '.' || part === '..')) {
+        throw new Error(`Telemetry source path must be repository-relative without # or |: ${options.sourcePath}`);
+    }
+    let instrumented;
+    try {
+        instrumented = instrumentSource(code, {
+            sourcePath: options.sourcePath,
+            runtimeSpecifier: '',
+            moduleType: 'bundled',
+            controlChannel: options.controlChannel,
+            runtimeIntegrity: options.runtimeIntegrity,
+            includedQualifiedNames: null,
+            parserPlugins,
+            recordSourcePositions: true,
+            skipDirective: 'use client',
+            moduleScopeProbes: false,
+        });
+    }
+    catch (error) {
+        if (error?.code !== 'BABEL_PARSE_ERROR')
+            throw error;
+        // The parser's own one-line reason and position, e.g. "Missing semicolon.
+        // (1:30)"; the code frame below it would copy customer source into the log.
+        const reason = String(error.message).split('\n')[0].replace(/^unknown:\s*/, '');
+        return { kind: 'unparsed', reason };
+    }
+    return instrumented ? { kind: 'instrumented', ...instrumented } : { kind: 'unchanged' };
+}
+/**
+ * Write the runtime, its manifest and the preload that installs it into
+ * `<outputDirectory>/.haystack-telemetry/`. The runtime reads the manifest
+ * beside its own real file; nothing here depends on where a bundler put the
+ * chunks. Returns the preload's absolute path for NODE_OPTIONS=--require.
+ */
+export function writeBundledTelemetryRuntime(options) {
+    const modules = [...options.modules].sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+    const sitesByProbe = new Map();
+    for (const module of modules) {
+        for (const site of module.sites) {
+            const existing = sitesByProbe.get(site.probe_key);
+            if (existing && JSON.stringify(existing) !== JSON.stringify(site)) {
+                throw new Error(`Telemetry site ${site.probe_key} was compiled from two different versions of ${site.source_path}`);
+            }
+            sitesByProbe.set(site.probe_key, site);
+        }
+    }
+    const sites = [...sitesByProbe.values()].sort((left, right) => left.site_id.localeCompare(right.site_id));
+    if (sites.length === 0)
+        throw new Error('Telemetry instrumented no server source; nothing to install');
+    if (sites.length > MAX_INSTRUMENTED_SITES) {
+        throw new Error(`Build contains ${sites.length} telemetry sites; maximum is ${MAX_INSTRUMENTED_SITES}`);
+    }
+    // The build identity covers exactly what was instrumented (every site's
+    // coordinates), so two builds of identical server source share one identity
+    // and any source change produces a new one.
+    const buildId = shortHash([options.bundler, ...sites.map(site => JSON.stringify(site))]);
+    const runtime = authenticateTelemetryRuntime(options.controlChannel);
+    const outputDirectory = resolve(options.outputDirectory);
+    const runtimeDirectory = join(outputDirectory, RUNTIME_DIRECTORY);
+    mkdirSync(runtimeDirectory, { recursive: true });
+    const manifest = {
+        schema_version: MANIFEST_SCHEMA_VERSION,
+        build_id: buildId,
+        bundler: options.bundler,
+        source_root: options.sourceRoot,
+        entry: null,
+        runtime: `${RUNTIME_DIRECTORY}/${RUNTIME_FILENAME}`,
+        instrumented_files: modules.map(module => ({ source_path: module.sourcePath, probes: module.probes })),
+        skipped_unparsed_files: [...new Map(options.unparsed.map(file => [file.sourcePath, file])).values()]
+            .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath))
+            .map(file => ({ source_path: file.sourcePath, reason: file.reason })),
+        sites,
+    };
+    writeFileSync(join(runtimeDirectory, MANIFEST_FILENAME), `${JSON.stringify(manifest, null, 2)}\n`);
+    writeFileSync(join(runtimeDirectory, RUNTIME_FILENAME), runtime.source);
+    const registerPath = join(runtimeDirectory, BUNDLED_REGISTER_FILENAME);
+    // The same hash-verified, cache-isolated evaluation the compiled-output
+    // entry bootstrap performs, run as a preload before the server's first
+    // module so every bundled probe binds on its first evaluation.
+    writeFileSync(registerPath, bootstrapFor(registerPath, outputDirectory, buildId, runtime.hash, `${options.controlChannel}_runtimeGuard`, `${options.controlChannel}_runtimeBlocked`));
+    return { registerPath, manifest };
+}
 export async function telemetryInstrumentCommand(distDirectory, options) {
     let includeSymbols = options.includeSymbols;
     if (options.includeSymbolsFile) {

package/dist/commands/verify-onboarding.js

@@ -14,11 +14,13 @@ import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSi
 import { trackOnboardingEvent } from '../utils/telemetry.js';
 import { gatewayFetch } from './case-batch.js';
 import { ONBOARDING_STAGES, ONBOARDING_VERSION, } from './onboarding-contract.js';
+import { sameNotes } from './onboarding-notes.js';
 import { deriveBaseSha, EXPLICIT_WALL_MS, resolveOriginRepository } from './verify-precompute.js';
 import { findGitRoot } from '../utils/hooks.js';
 const ONBOARDING_PATH = '/api/agent/cloud-verifier/onboarding';
 const FACTS_PATH = `${ONBOARDING_PATH}/facts`;
 const ANSWERS_PATH = `${ONBOARDING_PATH}/answers`;
+const NOTES_PATH = `${ONBOARDING_PATH}/notes`;
 const ONBOARD_RUN_ID = /^ob_[0-9a-f]{48}$/;
 const SHA256 = /^[0-9a-f]{64}$/;
 const COMMIT = /^[0-9a-f]{40}$/;
@@ -95,6 +97,8 @@ export function parseOnboardingStatus(value, expected) {
         invalid('its version choices');
     if (!isStrings(value.standIns) || !isStrings(value.unsetProviders) || !isStrings(value.standInGaps))
         invalid('its stand-ins');
+    if (!(value.worldMemoryMib === null || (typeof value.worldMemoryMib === 'number' && Number.isInteger(value.worldMemoryMib))))
+        invalid('its world memory');
     if (value.block !== null)
         parseOnboardingBlock(value.block);
     const checkpoint = value.checkpoint;
@@ -229,9 +233,15 @@ export function onboardingStep(status) {
     const stages = status.checkpoint?.execution.stages ?? [];
     const done = stages.filter(stage => stage.status === 'ok' || stage.status === 'reused').map(stage => stage.stage);
     const current = status.checkpoint?.stage;
+    // A deferred run's checkpoint is its last attempt's (stage cleanup): it is waiting, not cleaning up (2026-10-05, Excalidraw
+    // showed "cleaning up" for ten minutes behind a duplicate onboarding of the same commit).
     const doing = status.state !== 'onboarding' ? status.state
-        : current === undefined ? 'queued' : STAGE_WORDS[current];
-    return `Onboarding: ${doing}${done.length ? ` (done: ${done.join(', ')})` : ''}.`;
+        : status.checkpoint?.error?.code === 'deferred' ? 'waiting for an earlier onboarding of this commit to finish, then reusing it'
+            : current === undefined ? 'queued' : STAGE_WORDS[current];
+    // A world larger than the first size is what onboarding found the app needs; every crawl's VMs are that size.
+    const memory = status.state === 'ready' && status.worldMemoryMib !== null && status.worldMemoryMib > 4096
+        ? ` Its copies run with ${status.worldMemoryMib} MiB of memory: it ran out at 4096.` : '';
+    return `Onboarding: ${doing}${done.length ? ` (done: ${done.join(', ')})` : ''}.${memory}`;
 }
 /** The stage list, one line per stage the run has reached. */
 export function onboardingStageLines(status) {
@@ -369,6 +379,28 @@ export async function verifyAnswerCommand(questionId, choice, options) {
         return;
     }
 }
+/** 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. */
+export async function writeOnboardingNotes(repository, notes, token) {
+    for (let attempt = 1;; attempt += 1) {
+        const facts = await readFacts(repository, token);
+        if (sameNotes(facts.facts.notes, notes))
+            return 'unchanged';
+        const request = { repository, expectedFactsDigest: facts.factsDigest, notes };
+        const response = await gatewayFetch(`${NOTES_PATH}?repository=${encodeURIComponent(repository)}`, token, {
+            method: 'POST', body: JSON.stringify(request),
+        });
+        if (response.status === 409 && attempt < 3) {
+            await response.body?.cancel();
+            continue;
+        }
+        if (!response.ok)
+            throw await classifyHttpError(response, `Haystack API ${NOTES_PATH}`);
+        if (!sameNotes(parseFactsView(await body(response, 'facts'), repository).facts.notes, notes))
+            invalid('the notes it answered with');
+        return 'written';
+    }
+}
 const clock = () => new Date().toTimeString().slice(0, 8);
 /** `haystack verify onboarding`: the onboarding of the base `haystack verify` would use for this
  * checkout, read without starting anything; --wait follows it while it runs. */

package/dist/commands/verify-precompute.js

@@ -264,7 +264,11 @@ export async function derivePrecomputeRequest(gitRoot, owner, repository, deadli
 /** How long the crawl may take (CRAWL-V1 amendment 8); undefined: the service's default. */
 budgetMs, 
 /** Amendment 12: 'prepare' builds and freezes only (the turn-end hook); 'crawl' is `haystack verify`. */
-mode = 'crawl') {
+mode = 'crawl', 
+/** Amendment 16: `haystack verify --pool`; undefined: the service decides ('auto'). */
+pool, 
+/** Amendment 17: the coding agent's `--intent` and `--idea`s; each absent when it gave none. */
+agent = {}) {
     // Capture this before git and compression work so delivery latency cannot
     // make an older stop look newer than a later one.
     const observedAt = Date.now();
@@ -292,7 +296,8 @@ mode = 'crawl') {
             cacheKey,
             patchGzBase64: patchGzip.toString('base64'),
             patchSha256: createHash('sha256').update(patchGzip).digest('hex'),
-            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle, ...(budgetMs === undefined ? {} : { budgetMs }), mode } }),
+            ...(workCommit === baseSha ? {} : { crawl: { treeSha, changeTitle, ...(budgetMs === undefined ? {} : { budgetMs }), mode, ...(pool === undefined ? {} : { pool }),
+                    ...(agent.intent === undefined ? {} : { intent: agent.intent }), ...(agent.ideas === undefined ? {} : { ideas: agent.ideas }) } }),
         },
     };
 }
@@ -519,7 +524,11 @@ export async function captureCheckout(deadline,
 /** Amendment 12: the turn-end hook and `verify precompute` ask to prepare (build and freeze); `haystack verify` to crawl. */
 mode, repository, 
 /** `haystack verify --minutes`; undefined: the repository's .haystack.json crawl.minutes, else the service's default. */
-minutes) {
+minutes, 
+/** `haystack verify --pool`; undefined: the service decides. */
+pool, 
+/** `haystack verify --intent` and `--idea` (CRAWL-V1 amendment 17). */
+agent = {}) {
     const gitRoot = findGitRoot();
     if (!gitRoot) {
         throw new PrecomputeFailure('Run this command from a git repository.');
@@ -527,7 +536,7 @@ minutes) {
     const metadataDirectory = walkerMetadataDirectory(gitRoot, deadline);
     const target = repository ?? resolveOriginRepository(gitRoot);
     const chosen = minutes ?? configuredCrawlMinutes(gitRoot);
-    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline, chosen === undefined ? undefined : chosen * 60_000, mode);
+    const derivation = await derivePrecomputeRequest(gitRoot, target.owner, target.repository, deadline, chosen === undefined ? undefined : chosen * 60_000, mode, pool, agent);
     return { metadataDirectory, derivation };
 }
 /** The explicit (non-hook) submission of a capture: one synchronous