@vendoai/vendo 0.4.0

package/dist/cli/extract/harness.d.ts

@@ -0,0 +1,114 @@
+import { z } from "zod";
+/**
+ * The ExtractionHarness seam (install-dx v1, brainstorm 2026-07-18): Vendo
+ * owns the instructions, the deterministic validation, and the artifact
+ * contract; a world-class coding agent does the reading. Everything above
+ * this seam is vendor-neutral — swapping the harness (Claude Agent SDK today,
+ * anything tomorrow) is a config change, not an architecture change.
+ */
+/** One drafted polish entry for an extracted tool. The AI pass proposes;
+ *  deterministic guards in extraction.ts decide what applies. */
+export declare const draftToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    risk: z.ZodOptional<z.ZodEnum<["read", "write", "destructive"]>>;
+    critical: z.ZodOptional<z.ZodBoolean>;
+    /** false = wake a statically-unclassifiable tool (needs reasoning). */
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    reasoning: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    risk?: "read" | "write" | "destructive" | undefined;
+    critical?: boolean | undefined;
+    disabled?: boolean | undefined;
+    reasoning?: string | undefined;
+}, {
+    name: string;
+    description: string;
+    risk?: "read" | "write" | "destructive" | undefined;
+    critical?: boolean | undefined;
+    disabled?: boolean | undefined;
+    reasoning?: string | undefined;
+}>;
+export type DraftTool = z.infer<typeof draftToolSchema>;
+export declare const extractionDraftSchema: z.ZodObject<{
+    /** One-paragraph product brief drafted from the codebase. */
+    brief: z.ZodString;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        risk: z.ZodOptional<z.ZodEnum<["read", "write", "destructive"]>>;
+        critical: z.ZodOptional<z.ZodBoolean>;
+        /** false = wake a statically-unclassifiable tool (needs reasoning). */
+        disabled: z.ZodOptional<z.ZodBoolean>;
+        reasoning: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+        risk?: "read" | "write" | "destructive" | undefined;
+        critical?: boolean | undefined;
+        disabled?: boolean | undefined;
+        reasoning?: string | undefined;
+    }, {
+        name: string;
+        description: string;
+        risk?: "read" | "write" | "destructive" | undefined;
+        critical?: boolean | undefined;
+        disabled?: boolean | undefined;
+        reasoning?: string | undefined;
+    }>, "many">;
+    /** API surfaces the static extractor missed — surfaced to the dev, not
+     *  written anywhere (adding tools is future work on the sync side). */
+    missedSurfaces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    tools: {
+        name: string;
+        description: string;
+        risk?: "read" | "write" | "destructive" | undefined;
+        critical?: boolean | undefined;
+        disabled?: boolean | undefined;
+        reasoning?: string | undefined;
+    }[];
+    brief: string;
+    missedSurfaces?: string[] | undefined;
+}, {
+    tools: {
+        name: string;
+        description: string;
+        risk?: "read" | "write" | "destructive" | undefined;
+        critical?: boolean | undefined;
+        disabled?: boolean | undefined;
+        reasoning?: string | undefined;
+    }[];
+    brief: string;
+    missedSurfaces?: string[] | undefined;
+}>;
+export type ExtractionDraft = z.infer<typeof extractionDraftSchema>;
+export interface ExtractionRunInput {
+    root: string;
+    /** The complete staged instructions, composed by extraction.ts. */
+    instructions: string;
+    env: Record<string, string | undefined>;
+    /** Live narration line (surface discoveries, files being read). */
+    onProgress?: (line: string) => void;
+}
+export interface ExtractionHarness {
+    /** Stable identifier ("claude-agent-sdk"). */
+    id: string;
+    /** A short human label of the credential this harness would use
+     *  ("your Claude Code login", "your ANTHROPIC_API_KEY"), or null when the
+     *  harness cannot run on this machine. */
+    availability(input: {
+        root: string;
+        env: Record<string, string | undefined>;
+    }): Promise<string | null>;
+    /** Run the instructions and return the agent's final text (extraction.ts
+     *  parses and validates; the harness never interprets the draft). */
+    run(input: ExtractionRunInput): Promise<string>;
+}
+/** Extract a stage artifact from an agent's final text: prefer a fenced
+ *  block, else try each balanced object span until one validates against the
+ *  stage's schema. Throws on unparseable output. */
+export declare function parseArtifact<Schema extends z.ZodTypeAny>(text: string, schema: Schema): z.infer<Schema>;
+export declare function parseDraft(text: string): ExtractionDraft;

package/dist/cli/extract/harness.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+/**
+ * The ExtractionHarness seam (install-dx v1, brainstorm 2026-07-18): Vendo
+ * owns the instructions, the deterministic validation, and the artifact
+ * contract; a world-class coding agent does the reading. Everything above
+ * this seam is vendor-neutral — swapping the harness (Claude Agent SDK today,
+ * anything tomorrow) is a config change, not an architecture change.
+ */
+/** One drafted polish entry for an extracted tool. The AI pass proposes;
+ *  deterministic guards in extraction.ts decide what applies. */
+export const draftToolSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1).max(500),
+    risk: z.enum(["read", "write", "destructive"]).optional(),
+    critical: z.boolean().optional(),
+    /** false = wake a statically-unclassifiable tool (needs reasoning). */
+    disabled: z.boolean().optional(),
+    reasoning: z.string().max(500).optional(),
+});
+export const extractionDraftSchema = z.object({
+    /** One-paragraph product brief drafted from the codebase. */
+    brief: z.string().min(1).max(4000),
+    tools: z.array(draftToolSchema),
+    /** API surfaces the static extractor missed — surfaced to the dev, not
+     *  written anywhere (adding tools is future work on the sync side). */
+    missedSurfaces: z.array(z.string().max(300)).optional(),
+});
+/** Walk balanced `{…}` spans (string-aware) starting at each `{`, returning
+ *  each complete candidate — so prose containing stray braces around the real
+ *  JSON object cannot poison the parse (Greptile P2 on #363). */
+function* balancedObjectSpans(text) {
+    for (let start = text.indexOf("{"); start !== -1; start = text.indexOf("{", start + 1)) {
+        let depth = 0;
+        let inString = false;
+        for (let index = start; index < text.length; index += 1) {
+            const char = text[index];
+            if (inString) {
+                if (char === "\\")
+                    index += 1;
+                else if (char === '"')
+                    inString = false;
+                continue;
+            }
+            if (char === '"')
+                inString = true;
+            else if (char === "{")
+                depth += 1;
+            else if (char === "}") {
+                depth -= 1;
+                if (depth === 0) {
+                    yield text.slice(start, index + 1);
+                    break;
+                }
+            }
+        }
+    }
+}
+/** Extract a stage artifact from an agent's final text: prefer a fenced
+ *  block, else try each balanced object span until one validates against the
+ *  stage's schema. Throws on unparseable output. */
+export function parseArtifact(text, schema) {
+    const fenced = text.match(/```(?:json)?\s*\n([\s\S]*?)\n```/);
+    if (fenced?.[1] !== undefined) {
+        return schema.parse(JSON.parse(fenced[1]));
+    }
+    let firstError = new Error("no JSON object found in the agent's output");
+    let attempts = 0;
+    for (const span of balancedObjectSpans(text)) {
+        if (attempts >= 20)
+            break;
+        attempts += 1;
+        try {
+            return schema.parse(JSON.parse(span));
+        }
+        catch (error) {
+            if (attempts === 1)
+                firstError = error;
+        }
+    }
+    throw firstError;
+}
+export function parseDraft(text) {
+    return parseArtifact(text, extractionDraftSchema);
+}

package/dist/cli/extract/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Public seam for the extraction pipeline pieces the corpus AI eval matrix
+ * consumes (install-dx lane 3). Additive re-exports only — the pipeline
+ * itself lives in the sibling modules and is owned by the init flow.
+ */
+export { draftToolSchema, extractionDraftSchema, parseDraft, type DraftTool, type ExtractionDraft, type ExtractionHarness, type ExtractionRunInput, } from "./harness.js";
+export { applyDraft, composeInstructions } from "./extraction.js";
+export { runStagedExtraction, staticToolSchema, type StagedExtractionInput, type StagedExtractionResult, type StaticTool, } from "./stages.js";
+export { claudeHarness, type ClaudeHarnessOptions } from "./claude-harness.js";

package/dist/cli/extract/index.js

@@ -0,0 +1,9 @@
+/**
+ * Public seam for the extraction pipeline pieces the corpus AI eval matrix
+ * consumes (install-dx lane 3). Additive re-exports only — the pipeline
+ * itself lives in the sibling modules and is owned by the init flow.
+ */
+export { draftToolSchema, extractionDraftSchema, parseDraft, } from "./harness.js";
+export { applyDraft, composeInstructions } from "./extraction.js";
+export { runStagedExtraction, staticToolSchema, } from "./stages.js";
+export { claudeHarness } from "./claude-harness.js";

package/dist/cli/extract/npx-engine-harness.d.ts

@@ -0,0 +1,73 @@
+import { type ExecFileException } from "node:child_process";
+import type { ExtractionHarness } from "./harness.js";
+/**
+ * Last-resort extraction harness: nothing Claude-shaped is installed on the
+ * dev's machine (no Agent SDK, no `claude` binary, no `codex` binary), but
+ * they do have a usable credential — so init fetches Claude Code itself via
+ * `npm exec` rather than degrading straight to the honest skip. This is the
+ * fourth and final rung of the ladder in extraction.ts.
+ *
+ * Cross-task contract (a parallel task builds `@vendoai/engine` to this exact
+ * shape): `npm exec --yes @vendoai/engine@<PINNED_VERSION> -- run`, job JSON
+ * `{ instructions, root }` on the child's stdin, credentials/base-url/headers
+ * ride the child's process env (never the job JSON), stdout is EXACTLY the
+ * agent's final text, stderr is progress/narration, exit 0 = success. The
+ * version is pinned exact (never a range) so this rung's behavior can't
+ * drift out from under init on a machine with no local install to pin
+ * instead.
+ *
+ * Availability deliberately never touches npm or the network — it is called
+ * eagerly for every rung on every `vendo init`, and a probe here would mean
+ * every init pays an npm-registry round trip just to build the "AI polish?"
+ * prompt. The ~250MB download surprise is disclosed instead via the
+ * run-time notice below, right before the first real network access.
+ *
+ * Gateway fuel: mirrors claude-cli-harness.ts — when the dev has none of
+ * ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, or
+ * ANTHROPIC_BASE_URL (the corporate-gateway/custom-endpoint path) but
+ * VENDO_API_KEY is set, the child runs against Vendo Cloud's model gateway
+ * instead of degrading to unavailable (see gateway-fuel.ts). Own credential
+ * always wins — availability() must label these honestly (not as "Vendo
+ * Cloud key") since composeGatewayFuel itself refuses to overlay onto any of
+ * them; a wrong label here would make the consent prompt lie about what
+ * run() actually does.
+ */
+export declare const ENGINE_PACKAGE_NAME = "@vendoai/engine";
+export declare const ENGINE_PACKAGE_VERSION = "0.1.0";
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+type Exec = (args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    input: string;
+    onStderrLine?: (line: string) => void;
+}) => Promise<ExecResult>;
+/** Pure mapping from a completed `execFile` callback into an ExecResult —
+ *  pulled out of the real spawn so the four ways `error` shows up (a normal
+ *  nonzero exit, a real spawn-layer failure, the RUN_TIMEOUT_MS kill, or the
+ *  MAX_BUFFER_BYTES kill) each get direct unit coverage without actually
+ *  spawning anything (mirrors resolveCodexExecResult in
+ *  codex-cli-harness.ts). The four are easy to conflate — all leave
+ *  `error.code` non-numeric — but they need different messages: a killed
+ *  15-minute extraction run is not npm being uninstalled, and a >10MB
+ *  narration stream is not a timeout. */
+export declare function resolveNpmExecResult(error: ExecFileException | null, stdout: string, stderr: string): ExecResult;
+/** Line-buffered splitter for a live-streaming descriptor, extracted out of
+ *  execNpmEngine so it's directly unit-testable without a real child
+ *  process: a line split across two `data` chunks, and — the bug this
+ *  fixes — a trailing line with no final newline, which `flush()` still
+ *  delivers instead of silently dropping the child's last progress line
+ *  when the stream ends without one. */
+export declare function createLineSplitter(onLine: (line: string) => void): {
+    push(chunk: string): void;
+    flush(): void;
+};
+export interface NpxEngineHarnessOptions {
+    /** Test seam. */
+    exec?: Exec;
+}
+export declare function npxEngineHarness(options?: NpxEngineHarnessOptions): ExtractionHarness;
+export {};

package/dist/cli/extract/npx-engine-harness.js

@@ -0,0 +1,225 @@
+import { execFile } from "node:child_process";
+import { composeGatewayFuel, hasOwnAnthropicEnvOverride } from "./gateway-fuel.js";
+/**
+ * Last-resort extraction harness: nothing Claude-shaped is installed on the
+ * dev's machine (no Agent SDK, no `claude` binary, no `codex` binary), but
+ * they do have a usable credential — so init fetches Claude Code itself via
+ * `npm exec` rather than degrading straight to the honest skip. This is the
+ * fourth and final rung of the ladder in extraction.ts.
+ *
+ * Cross-task contract (a parallel task builds `@vendoai/engine` to this exact
+ * shape): `npm exec --yes @vendoai/engine@<PINNED_VERSION> -- run`, job JSON
+ * `{ instructions, root }` on the child's stdin, credentials/base-url/headers
+ * ride the child's process env (never the job JSON), stdout is EXACTLY the
+ * agent's final text, stderr is progress/narration, exit 0 = success. The
+ * version is pinned exact (never a range) so this rung's behavior can't
+ * drift out from under init on a machine with no local install to pin
+ * instead.
+ *
+ * Availability deliberately never touches npm or the network — it is called
+ * eagerly for every rung on every `vendo init`, and a probe here would mean
+ * every init pays an npm-registry round trip just to build the "AI polish?"
+ * prompt. The ~250MB download surprise is disclosed instead via the
+ * run-time notice below, right before the first real network access.
+ *
+ * Gateway fuel: mirrors claude-cli-harness.ts — when the dev has none of
+ * ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN, or
+ * ANTHROPIC_BASE_URL (the corporate-gateway/custom-endpoint path) but
+ * VENDO_API_KEY is set, the child runs against Vendo Cloud's model gateway
+ * instead of degrading to unavailable (see gateway-fuel.ts). Own credential
+ * always wins — availability() must label these honestly (not as "Vendo
+ * Cloud key") since composeGatewayFuel itself refuses to overlay onto any of
+ * them; a wrong label here would make the consent prompt lie about what
+ * run() actually does.
+ */
+export const ENGINE_PACKAGE_NAME = "@vendoai/engine";
+export const ENGINE_PACKAGE_VERSION = "0.1.0";
+// A one-time ~250MB package fetch plus the extraction stages themselves (which
+// can already run for minutes over a real codebase on the other rungs) needs
+// more headroom than the PATH-binary rungs' 10-minute budget.
+const RUN_TIMEOUT_MS = 15 * 60 * 1_000;
+const MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+/** Pure mapping from a completed `execFile` callback into an ExecResult —
+ *  pulled out of the real spawn so the four ways `error` shows up (a normal
+ *  nonzero exit, a real spawn-layer failure, the RUN_TIMEOUT_MS kill, or the
+ *  MAX_BUFFER_BYTES kill) each get direct unit coverage without actually
+ *  spawning anything (mirrors resolveCodexExecResult in
+ *  codex-cli-harness.ts). The four are easy to conflate — all leave
+ *  `error.code` non-numeric — but they need different messages: a killed
+ *  15-minute extraction run is not npm being uninstalled, and a >10MB
+ *  narration stream is not a timeout. */
+export function resolveNpmExecResult(error, stdout, stderr) {
+    if (error === null)
+        return { stdout, stderr, code: 0 };
+    if (typeof error.code === "number")
+        return { stdout, stderr, code: error.code };
+    if (error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER") {
+        // execFile's `maxBuffer` kill also sets error.killed, so this must be
+        // checked BEFORE the killed branch below — a >10MB narration stream is
+        // not the 15-minute timeout, and labeling it as one would send the dev
+        // chasing a slowness that isn't there.
+        const megabytes = Math.round(MAX_BUFFER_BYTES / (1024 * 1024));
+        return {
+            stdout: "",
+            stderr: `npm exec output exceeded the ${megabytes}MB buffer — the engine's narration stream was `
+                + "larger than expected, so the child was killed before finishing",
+            code: 1,
+        };
+    }
+    if (error.killed === true) {
+        // execFile's `timeout` option SIGTERMs a still-running child — a
+        // legitimate long extraction run, not a broken npm install. This must be
+        // checked before the spawn-failure branch below: a kill leaves
+        // error.code null (not a string), so it would otherwise fall into "npm
+        // could not be launched" and mislabel the dev's own long-running job as
+        // a missing npm.
+        const minutes = Math.round(RUN_TIMEOUT_MS / 60_000);
+        return {
+            stdout: "",
+            stderr: `npm exec was killed for exceeding the ${minutes}-minute timeout`
+                + (error.signal !== undefined ? ` (${error.signal})` : ""),
+            code: 1,
+        };
+    }
+    if (typeof error.code === "string") {
+        // A real spawn-layer failure (error.code is an errno string like
+        // "ENOENT" or "EACCES", set when the OS never launched the child at
+        // all) — npm itself could not be launched: not installed, not on PATH,
+        // or not executable. execFile's own stdout/stderr are empty in this
+        // case, so the actionable detail has to come from error.message.
+        return {
+            stdout: "",
+            stderr: `npm could not be launched (${error.message}) — is npm installed and on PATH?`,
+            code: 1,
+        };
+    }
+    // Any other shape (no numeric exit code, not killed, no string spawn
+    // code) — don't fabricate a diagnosis; forward whatever npm itself wrote.
+    // An offline registry lands here: npm still launches and exits non-zero
+    // with its own descriptive stderr (e.g. "npm error code ENOTFOUND"),
+    // which run()'s nonzero-exit handling forwards to the dev verbatim.
+    return { stdout, stderr, code: 1 };
+}
+/** Line-buffered splitter for a live-streaming descriptor, extracted out of
+ *  execNpmEngine so it's directly unit-testable without a real child
+ *  process: a line split across two `data` chunks, and — the bug this
+ *  fixes — a trailing line with no final newline, which `flush()` still
+ *  delivers instead of silently dropping the child's last progress line
+ *  when the stream ends without one. */
+export function createLineSplitter(onLine) {
+    let buffer = "";
+    return {
+        push(chunk) {
+            buffer += chunk;
+            let index = buffer.indexOf("\n");
+            while (index !== -1) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                if (line.length > 0)
+                    onLine(line);
+                index = buffer.indexOf("\n");
+            }
+        },
+        flush() {
+            if (buffer.length > 0)
+                onLine(buffer);
+            buffer = "";
+        },
+    };
+}
+function execNpmEngine(args, options) {
+    return new Promise((resolve) => {
+        // stderr is progress/narration per the child protocol — forward it line
+        // by line as it streams in, not just once the process exits; flush()
+        // in the callback below delivers any trailing partial line too.
+        const splitter = createLineSplitter((line) => options.onStderrLine?.(line));
+        const child = execFile("npm", args, { cwd: options.cwd, env: options.env, timeout: RUN_TIMEOUT_MS, maxBuffer: MAX_BUFFER_BYTES }, (error, stdout, stderr) => {
+            splitter.flush();
+            resolve(resolveNpmExecResult(error, stdout, stderr));
+        });
+        child.stderr?.on("data", (chunk) => splitter.push(chunk.toString()));
+        // If the child exits (or is killed by the timeout) before the stdin
+        // write drains, Node emits an unhandled EPIPE 'error' on this stream —
+        // with no listener, that's an uncaughtException that aborts all of
+        // `vendo init`, bypassing extraction.ts's graceful per-rung degradation.
+        // The real outcome always arrives via the execFile callback's exit code
+        // + stderr above, so this handler is intentionally a no-op.
+        child.stdin?.on("error", () => { });
+        child.stdin?.write(options.input);
+        child.stdin?.end();
+    });
+}
+function isSet(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+// Every label this rung can return carries the download disclosure, since
+// (unlike the PATH-binary rungs) a fetch always happens here.
+const DOWNLOAD_NOTE = "via the Vendo engine, ~250MB one-time download";
+const DOWNLOAD_SUFFIX = ` (${DOWNLOAD_NOTE})`;
+export function npxEngineHarness(options = {}) {
+    const exec = options.exec ?? execNpmEngine;
+    return {
+        id: "npx-engine",
+        async availability({ env }) {
+            // The child spawns with {...process.env, ...input.env} (see run()), so
+            // the label must be judged against that SAME merged view — an ambient
+            // (process.env) own credential is the one the child would actually
+            // use, even when the caller's partial env carries only VENDO_API_KEY.
+            const merged = { ...process.env, ...env };
+            if (isSet(merged["ANTHROPIC_API_KEY"]))
+                return `your ANTHROPIC_API_KEY${DOWNLOAD_SUFFIX}`;
+            // The corporate-gateway/custom-endpoint env vars are an own credential
+            // too (see gateway-fuel.ts's INVARIANT) — composeGatewayFuel refuses to
+            // overlay onto them regardless of what run() passes, so labeling this
+            // rung "your Vendo Cloud key" here would be a lie about what actually
+            // runs. Per-var labels (same priority order as claude-cli-harness.ts)
+            // so the consent line names the credential that's really in play.
+            if (hasOwnAnthropicEnvOverride(merged)) {
+                if (isSet(merged["ANTHROPIC_AUTH_TOKEN"]))
+                    return `your ANTHROPIC_AUTH_TOKEN${DOWNLOAD_SUFFIX}`;
+                if (isSet(merged["CLAUDE_CODE_OAUTH_TOKEN"]))
+                    return `your CLAUDE_CODE_OAUTH_TOKEN${DOWNLOAD_SUFFIX}`;
+                return `your ANTHROPIC_BASE_URL${DOWNLOAD_SUFFIX}`;
+            }
+            if (isSet(merged["VENDO_API_KEY"])) {
+                return `your Vendo Cloud key (managed inference, ${DOWNLOAD_NOTE})`;
+            }
+            return null;
+        },
+        async run(input) {
+            // Merge FIRST, then guard — the child is spawned with the caller's env
+            // over process.env, so the own-credential verdict and composeGatewayFuel
+            // must evaluate that same merged env. Guarding input.env alone would
+            // let the overlay clobber an ambient (process.env) BYO endpoint the
+            // child would otherwise have used. composeGatewayFuel already refuses
+            // to overlay onto these env vars on its own (defense in depth) —
+            // computed explicitly here too so this rung's own-credential verdict
+            // matches availability()'s exactly, the same belt-and-suspenders style
+            // as claude-cli-harness.ts.
+            const merged = { ...process.env, ...input.env };
+            const hasOwnKey = isSet(merged["ANTHROPIC_API_KEY"]) || hasOwnAnthropicEnvOverride(merged);
+            const overlay = composeGatewayFuel({ env: merged, ownCredentialAvailable: hasOwnKey });
+            // Visible-never-silent: the ~250MB fetch is a real surprise on a
+            // machine with nothing installed, so it's disclosed up front, before
+            // the child (and its network access) ever starts.
+            input.onProgress?.(`Fetching ${ENGINE_PACKAGE_NAME}@${ENGINE_PACKAGE_VERSION} via npm exec (~250MB one-time download; `
+                + "npm caches it locally, so later runs skip the download)…");
+            const job = JSON.stringify({ instructions: input.instructions, root: input.root });
+            const args = ["exec", "--yes", `${ENGINE_PACKAGE_NAME}@${ENGINE_PACKAGE_VERSION}`, "--", "run"];
+            // Forward the caller's env so a key present only in the passed map
+            // (not process.env) still authenticates the child; gateway fuel (if
+            // applicable) wins last — mirrors claude-cli-harness.ts.
+            const result = await exec(args, {
+                cwd: input.root,
+                env: { ...merged, ...overlay },
+                input: job,
+                onStderrLine: input.onProgress,
+            });
+            if (result.code !== 0) {
+                throw new Error(`npm exec ${ENGINE_PACKAGE_NAME}@${ENGINE_PACKAGE_VERSION} exited with code ${result.code}: `
+                    + `${result.stderr.trim() || "(no stderr)"}`);
+            }
+            return result.stdout;
+        },
+    };
+}

package/dist/cli/extract/stages.d.ts

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { type ExtractionDraft, type ExtractionHarness } from "./harness.js";
+import { modelThemeSchema, type ThemeSlotValues } from "../theme/extract-theme.js";
+/**
+ * The staged extraction pipeline (install-dx, PostHog lesson: narrow stages
+ * beat one-shot). Four required passes plus one optional pass, all over the
+ * SAME harness seam — each is one `harness.run(instructions)` with its own
+ * narrow instructions and its own zod-validated artifact, written to
+ * `.vendo/data/extract/<stage>.json` so a failed run is diagnosable stage by
+ * stage:
+ *
+ * 1. survey — map the repo: frameworks, where the API surfaces live, and a
+ *    grouping of the static tool list into surfaces (cheap/fast; respects a
+ *    VENDO_EXTRACTION_SURVEY_MODEL override).
+ * 2. draft — one focused pass per surface, drafting judgment for just that
+ *    surface's tools. Surfaces run sequentially (rate-limit friendly); a
+ *    failed surface is SKIPPED with an honest note, never aborting the run.
+ * 3. cross-check — one pass over the combined draft for naming consistency,
+ *    duplicate coverage, and risk sanity. It may only AMEND entries within
+ *    the same schema (unknown names ignored, omitted entries stand); a
+ *    failure degrades to the uncross-checked drafts.
+ * 4. brief — drafted from what the survey and drafts learned; a failure
+ *    keeps the current brief.
+ * 5. theme — OPTIONAL, only when the caller supplies `theme` input and the
+ *    allowlist left brand slots unfilled: fills those slots the same way the
+ *    old theme model pass did, but over this harness seam (Read/Glob/Grep the
+ *    repo instead of a fixed evidence-file set). A failure degrades to a note
+ *    — the exact reads and neutral defaults still stand.
+ *
+ * The combined output feeds the EXISTING applyDraft guards in extraction.ts
+ * unchanged — deterministic verification stays the single gate. Nothing here
+ * assumes a vendor; the model override rides VENDO_EXTRACTION_MODEL, which
+ * every harness already honors.
+ */
+export declare const BRIEF_TEMPLATE = "Describe this product, its users, and the jobs the agent should help them complete.";
+/** Static facts don't clutter passes that only need names — kept small. */
+export declare const staticToolSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    risk: z.ZodOptional<z.ZodEnum<["read", "write", "destructive"]>>;
+    disabled: z.ZodOptional<z.ZodBoolean>;
+    method: z.ZodOptional<z.ZodString>;
+    path: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    path?: string | undefined;
+    method?: string | undefined;
+    risk?: "read" | "write" | "destructive" | undefined;
+    description?: string | undefined;
+    disabled?: boolean | undefined;
+}, {
+    name: string;
+    path?: string | undefined;
+    method?: string | undefined;
+    risk?: "read" | "write" | "destructive" | undefined;
+    description?: string | undefined;
+    disabled?: boolean | undefined;
+}>;
+export type StaticTool = z.infer<typeof staticToolSchema>;
+export declare const surveySchema: z.ZodObject<{
+    /** Frameworks/routers the surveyor identified (context for later stages). */
+    frameworks: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    surfaces: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        /** One line on where the surface lives in the code. */
+        note: z.ZodOptional<z.ZodString>;
+        tools: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        tools: string[];
+        name: string;
+        note?: string | undefined;
+    }, {
+        tools: string[];
+        name: string;
+        note?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    surfaces: {
+        tools: string[];
+        name: string;
+        note?: string | undefined;
+    }[];
+    frameworks?: string[] | undefined;
+}, {
+    surfaces: {
+        tools: string[];
+        name: string;
+        note?: string | undefined;
+    }[];
+    frameworks?: string[] | undefined;
+}>;
+export type Survey = z.infer<typeof surveySchema>;
+export declare function staticFacts(tools: StaticTool[]): string;
+export declare function composeInstructions(tools: StaticTool[], appName: string, surface?: {
+    name: string;
+    note?: string;
+}): string;
+/**
+ * Instructions for the OPTIONAL theme stage — the SOLE copy of the theme
+ * judgment rules (extract-theme.ts's old model pass and its prompt were
+ * deleted when the deterministic split landed; that file now owns only the
+ * exact pass, validators, and assembly).
+ */
+export declare function composeThemeInstructions(input: {
+    needed: string[];
+    alreadyExact: Record<string, string>;
+    evidencePaths: string[];
+    appName: string;
+}): string;
+interface NormalizedSurface {
+    name: string;
+    slug: string;
+    note?: string;
+    tools: StaticTool[];
+}
+/** Deterministic normalization of the survey grouping: unknown names are
+ *  dropped, a tool claimed twice keeps its first surface, unassigned tools
+ *  land in a catch-all pass, and a runaway surface count is merged down. The
+ *  drafting stage always covers EVERY static tool exactly once. */
+export declare function normalizeSurfaces(survey: Survey | null, tools: StaticTool[], notes: string[]): NormalizedSurface[];
+export interface StagedExtractionInput {
+    root: string;
+    env: Record<string, string | undefined>;
+    harness: ExtractionHarness;
+    tools: StaticTool[];
+    appName: string;
+    onProgress?: (line: string) => void;
+    /** Optional theme stage input — omitted entirely when the caller has no
+     *  theme extraction to do (e.g. init running without a theme pass). */
+    theme?: {
+        needed: Array<keyof ThemeSlotValues>;
+        alreadyExact: Record<string, string>;
+        evidencePaths: string[];
+    };
+}
+export interface StagedExtractionResult {
+    draft: ExtractionDraft;
+    /** Honest degradation notes (skipped surfaces, failed cross-check, …). */
+    notes: string[];
+    /** false = the brief stage failed and draft.brief is the pre-existing one. */
+    briefFromStage: boolean;
+    /** Present only when the theme stage ran and succeeded. */
+    theme?: z.infer<typeof modelThemeSchema>;
+}
+/** Orchestrate the staged pipeline. Throws only when no stage produced
+ *  anything usable (the error names the failed stage); partial failures
+ *  degrade with notes instead. */
+export declare function runStagedExtraction(input: StagedExtractionInput): Promise<StagedExtractionResult>;
+export {};