@vendoai/vendo 0.4.2 → 0.4.4

package/dist/capability-misses.js

@@ -1,6 +1,6 @@
 import { canonicalJson, sha256Hex, } from "@vendoai/core";
 import { envOptOut, loadConfig } from "@vendoai/telemetry";
-import { cloudFetch } from "./cli/cloud/client.js";
+import { cloudKeyFetch } from "./cloud-key-fetch.js";
 const DEFAULT_DATA_DIR = ".vendo/data";
 const DEFAULT_BATCH_SIZE = 100;
 const DEFAULT_QUEUE_LIMIT = 1_000;
@@ -60,8 +60,7 @@ function createMissUploader(options) {
             unrefTimer(timeout);
             try {
                 const surface = await options.surface;
-                const response = await cloudFetch("/api/v1/misses", {
-                    auth: "key",
+                const response = await cloudKeyFetch("/api/v1/misses", {
                     apiKey: options.apiKey,
                     env: options.env,
                     fetchImpl: options.fetchImpl,

package/dist/cli/cloud/client.d.ts

@@ -5,11 +5,8 @@ export declare class CloudError extends Error {
     readonly status: number;
     constructor(code: string, message: string, status: number);
 }
-export interface CloudUrlOptions {
-    apiUrl?: string;
-    env?: Record<string, string | undefined>;
-}
-export declare function resolveCloudBaseUrl(options?: CloudUrlOptions): string;
+export { resolveCloudBaseUrl, type CloudUrlOptions } from "../../cloud-key-fetch.js";
+import { type CloudUrlOptions } from "../../cloud-key-fetch.js";
 export interface SessionStore {
     read(): Promise<CloudSession | null>;
     write(session: CloudSession): Promise<void>;

package/dist/cli/cloud/client.js

@@ -15,10 +15,10 @@ export class CloudError extends Error {
         this.status = status;
     }
 }
-export function resolveCloudBaseUrl(options = {}) {
-    const value = options.apiUrl ?? (options.env ?? process.env).VENDO_CLOUD_URL ?? DEFAULT_CLOUD_URL;
-    return value.replace(/\/+$/, "");
-}
+// Base-URL resolution lives with the portable runtime helper so server-side
+// code (capability misses) never imports this Node/CLI module.
+export { resolveCloudBaseUrl } from "../../cloud-key-fetch.js";
+import { resolveCloudBaseUrl } from "../../cloud-key-fetch.js";
 function requestUrl(path, options) {
     const base = resolveCloudBaseUrl(options);
     const suffix = base.endsWith("/api/v1") && path.startsWith("/api/v1/")

package/dist/cli/cloud/device-login.d.ts

@@ -19,6 +19,17 @@ export interface DeviceLoginOptions {
         file that lets a fresh run resume a still-open ceremony (#479). */
     home?: string;
 }
+/**
+ * Write-preflight (0.4.1 E2E cert M4): prove `.env.local` is writable BEFORE
+ * any claim is opened or redeemed. Sandboxed agent runs — headless Claude
+ * Code protects env files even under --dangerously-skip-permissions — can
+ * deny the write; without this check the ceremony redeems the single-use
+ * claim, the key mints server-side, and the write failure loses it. A real
+ * append-mode open is the probe (permission checks like `access(W_OK)` don't
+ * see sandbox policies, which deny at open time); a probe-created empty file
+ * is removed again. Returns the failure detail, or null when writable.
+ */
+export declare function preflightEnvLocalWrite(root: string): Promise<string | null>;
 /**
  * `vendo login` — the top-level command surface: the identical ceremony
  * wrapped in one `command_run` row (command "login", TELEMETRY.md). The

package/dist/cli/cloud/device-login.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { open, stat, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import { option } from "./args.js";
 import { isVendoKey, resolveCloudBaseUrl } from "./client.js";
@@ -27,6 +28,30 @@ function defaultOpenBrowser(url) {
     const { command, args } = browserOpenCommand(process.platform, url);
     execFile(command, args, () => undefined); // best-effort: the printed URL is the fallback
 }
+/**
+ * Write-preflight (0.4.1 E2E cert M4): prove `.env.local` is writable BEFORE
+ * any claim is opened or redeemed. Sandboxed agent runs — headless Claude
+ * Code protects env files even under --dangerously-skip-permissions — can
+ * deny the write; without this check the ceremony redeems the single-use
+ * claim, the key mints server-side, and the write failure loses it. A real
+ * append-mode open is the probe (permission checks like `access(W_OK)` don't
+ * see sandbox policies, which deny at open time); a probe-created empty file
+ * is removed again. Returns the failure detail, or null when writable.
+ */
+export async function preflightEnvLocalWrite(root) {
+    const path = join(root, ".env.local");
+    const existedBefore = await stat(path).then(() => true, () => false);
+    try {
+        const handle = await open(path, "a");
+        await handle.close();
+        if (!existedBefore)
+            await unlink(path).catch(() => undefined);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 function ceremonyFrom(value) {
     const body = value;
     if (typeof body?.claim_token !== "string"
@@ -92,6 +117,18 @@ export async function runDeviceLogin(args, options = {}) {
     const waitMs = waitSeconds === undefined ? undefined : waitSeconds * 1000;
     const pendingHome = options.home === undefined ? {} : { home: options.home };
     const claimCwd = options.root ?? process.cwd();
+    // Prove the key's landing file is writable BEFORE the ceremony touches the
+    // network: a claim is single-use, so a post-approval write failure loses
+    // the minted key (M4). This is a WRITE failure, distinct from a timeout —
+    // the error says so instead of the generic polling copy.
+    const writeProblem = await preflightEnvLocalWrite(claimCwd);
+    if (writeProblem !== null) {
+        output.error(`Cannot write ${join(claimCwd, ".env.local")} (${writeProblem}). ` +
+            "`vendo login` lands the minted key there, so the ceremony was NOT started and no key was minted. " +
+            "This is a file-write problem, not a timeout: fix write access (sandboxed agent runs often deny env-file " +
+            "writes — re-run outside the sandbox or have your human run `vendo login`), then re-run.");
+        return 1;
+    }
     try {
         // A still-open claim from a dead process (#479): resume polling it so the
         // human's late approval — against the code they were already shown —
@@ -176,7 +213,21 @@ export async function runDeviceLogin(args, options = {}) {
                 if (typeof key !== "string" || !isVendoKey(key)) {
                     throw new Error("Vendo Cloud returned an invalid credential");
                 }
-                await upsertEnvLocal(root, "VENDO_API_KEY", key);
+                try {
+                    await upsertEnvLocal(root, "VENDO_API_KEY", key);
+                }
+                catch (writeError) {
+                    // The claim is consumed and the key minted — a resume can never
+                    // succeed, so the pending file goes; and this must read as a WRITE
+                    // failure, never the timeout/polling copy (M4). The key is never
+                    // printed, so the minted key is unrecoverable here: name the
+                    // console cleanup explicitly.
+                    await deletePendingClaim(claimCwd, pendingHome);
+                    throw new Error(`Approved and the key was minted, but writing it to ${join(root, ".env.local")} failed ` +
+                        `(${writeError instanceof Error ? writeError.message : String(writeError)}). ` +
+                        "The key was NOT saved and is not shown anywhere: revoke it in the console (Keys page), " +
+                        "fix write access to .env.local, and run `vendo login` again.");
+                }
                 await deletePendingClaim(claimCwd, pendingHome);
                 // Never print the key itself — .env.local is the hand-off, last4 the
                 // receipt. A resumed run names the full path: it may differ from cwd.

package/dist/cli/dep-versions.d.ts

@@ -23,4 +23,4 @@ export declare function installedAiVersion(root: string): Promise<string | null>
  * Read the host project's dependency versions (deps + devDeps) for telemetry.
  * Non-throwing: a missing or malformed package.json returns {}.
  */
-export declare function detectDepVersions(root: string, framework: HostFramework): Promise<DepVersions>;
+export declare function detectDepVersions(root: string, framework: HostFramework | "custom"): Promise<DepVersions>;

package/dist/cli/dep-versions.js

@@ -56,7 +56,7 @@ export async function detectDepVersions(root, framework) {
         const manifest = JSON.parse(await readFile(join(root, "package.json"), "utf8"));
         const dependencies = { ...manifest.devDependencies, ...manifest.dependencies };
         const out = {};
-        const frameworkPackage = framework === "unknown" ? undefined : FRAMEWORK_PACKAGE[framework];
+        const frameworkPackage = framework === "unknown" || framework === "custom" ? undefined : FRAMEWORK_PACKAGE[framework];
         const frameworkVersion = frameworkPackage === undefined ? undefined : bareVersion(dependencies[frameworkPackage]);
         if (frameworkVersion !== undefined)
             out.frameworkVersion = frameworkVersion;

package/dist/cli/doctor-codes.d.ts

@@ -17,9 +17,13 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-WIRE-003": "the Next.js catch-all handler app/api/vendo/[...vendo]/route.ts is missing";
     readonly "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>";
     readonly "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared";
+    readonly "E-WIRE-006": "no visible agent surface is mounted (<VendoRoot> alone renders nothing)";
+    readonly "E-WIRE-007": "no createVendo server wiring found in an unknown-framework host";
+    readonly "E-WIRE-008": "no <VendoRoot> found in an unknown-framework host's source";
     readonly "E-CFG-001": "a required .vendo/ config file is missing";
     readonly "E-CFG-002": ".vendo/data/.gitignore is missing";
     readonly "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support";
+    readonly "E-DEP-002": "the running wire serves a different @vendoai/vendo version than this CLI (split-brain install)";
     readonly "E-UI-001": "an ejected surface predates the installed @vendoai/ui";
     readonly "E-DEV-001": "the dev server could not be started for the probe";
     readonly "E-LIVE-001": "/status returned an invalid composition response";
@@ -27,6 +31,7 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-LIVE-003": "/status returned an invalid execution venue";
     readonly "E-LIVE-004": "no execution venue is configured";
     readonly "E-LIVE-005": "the host /status does not report an execution venue (version skew)";
+    readonly "E-LIVE-006": "the app's root page returns a server error while the wire answers";
     readonly "E-AUTH-001": "present credentials did not reach the host API";
     readonly "E-AUTH-002": "the present credential probe is unreachable";
     readonly "E-AUTH-003": "the present credential probe cannot run while the dev server is down";
@@ -46,6 +51,8 @@ export declare const DOCTOR_ERROR_CODES: {
     readonly "E-TURN-001": "the live model turn did not answer";
     readonly "E-TURN-002": "the live model turn cannot run while the dev server is down";
     readonly "E-CLOUD-001": "VENDO_API_KEY is set but not usable";
+    readonly "E-TOOLS-001": "every extracted host tool is disabled or excluded (zero live host tools)";
+    readonly "E-TOOLS-002": "the extracted tool surface is empty (zero host tools)";
 };
 export type DoctorErrorCode = keyof typeof DOCTOR_ERROR_CODES;
 /** Complete list of every code doctor can emit, for CI enumeration. */

package/dist/cli/doctor-codes.js

@@ -18,9 +18,13 @@ export const DOCTOR_ERROR_CODES = {
     "E-WIRE-003": "the Next.js catch-all handler app/api/vendo/[...vendo]/route.ts is missing",
     "E-WIRE-004": "the Next.js root layout is not wrapped in <VendoRoot>",
     "E-WIRE-005": "the @vendoai/vendo (or vendoai alias) dependency is not declared",
+    "E-WIRE-006": "no visible agent surface is mounted (<VendoRoot> alone renders nothing)",
+    "E-WIRE-007": "no createVendo server wiring found in an unknown-framework host",
+    "E-WIRE-008": "no <VendoRoot> found in an unknown-framework host's source",
     "E-CFG-001": "a required .vendo/ config file is missing",
     "E-CFG-002": ".vendo/data/.gitignore is missing",
     "E-DEP-001": "the installed ai package is a major version @vendoai/vendo does not support",
+    "E-DEP-002": "the running wire serves a different @vendoai/vendo version than this CLI (split-brain install)",
     "E-UI-001": "an ejected surface predates the installed @vendoai/ui",
     "E-DEV-001": "the dev server could not be started for the probe",
     "E-LIVE-001": "/status returned an invalid composition response",
@@ -28,6 +32,7 @@ export const DOCTOR_ERROR_CODES = {
     "E-LIVE-003": "/status returned an invalid execution venue",
     "E-LIVE-004": "no execution venue is configured",
     "E-LIVE-005": "the host /status does not report an execution venue (version skew)",
+    "E-LIVE-006": "the app's root page returns a server error while the wire answers",
     "E-AUTH-001": "present credentials did not reach the host API",
     "E-AUTH-002": "the present credential probe is unreachable",
     "E-AUTH-003": "the present credential probe cannot run while the dev server is down",
@@ -47,6 +52,8 @@ export const DOCTOR_ERROR_CODES = {
     "E-TURN-001": "the live model turn did not answer",
     "E-TURN-002": "the live model turn cannot run while the dev server is down",
     "E-CLOUD-001": "VENDO_API_KEY is set but not usable",
+    "E-TOOLS-001": "every extracted host tool is disabled or excluded (zero live host tools)",
+    "E-TOOLS-002": "the extracted tool surface is empty (zero host tools)",
 };
 /** Complete list of every code doctor can emit, for CI enumeration. */
 export const doctorErrorCodes = Object.keys(DOCTOR_ERROR_CODES);

package/dist/cli/doctor-live.js

@@ -158,7 +158,17 @@ export async function startDevServerForProbe(options) {
         log.push(`spawn error: ${error.message}\n`);
         failSpawn();
     });
-    const stop = () => { child.kill("SIGTERM"); };
+    // Destroy the piped streams too: `npm run dev` grandchildren (the actual
+    // next/vite process) can survive the SIGTERM and keep the inherited pipe
+    // fds open, and the live 'data' listeners would then hold doctor's event
+    // loop — the process would hang after printing its verdict instead of
+    // exiting with it (exit-code honesty, 0.4.1 E2E cert defect 13 family).
+    const stop = () => {
+        child.kill("SIGTERM");
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        child.unref?.(); // injected test doubles may not implement it
+    };
     const up = await Promise.race([
         waitForStatus(options.statusUrl, fetchImpl, options.timeoutMs ?? 120_000),
         spawnFailed,

package/dist/cli/doctor.js

@@ -5,6 +5,7 @@ import { cloudDoctor, liveModelTurn, startDevServerForProbe, } from "./doctor-li
 import { installedAiVersion } from "./dep-versions.js";
 import { doctorFixRef } from "./doctor-codes.js";
 import { EJECT_MANIFEST_FILE } from "./eject.js";
+import { overridesFileSchema, toolsFileSchema } from "@vendoai/actions";
 import { detectFramework, detectVendoWiring } from "./framework.js";
 import { walk } from "./theme/walk.js";
 import { remoteUrls, sameUrl, validateRegistryServer } from "./mcp/registry.js";
@@ -93,8 +94,40 @@ export async function runDoctor(options) {
     const warn = (id, code, message) => { warnings += 1; checks.push({ id, status: "warning", message, error_code: code, fix_ref: doctorFixRef(code) }); if (!json)
         output.error(`warning: ${message}`); };
     const framework = await detectFramework(root);
-    if (framework === "express") {
-        const wiring = await detectVendoWiring(root);
+    // The generated vendo/vendo-root.tsx wrapper carries the <VendoRoot> AND
+    // <VendoOverlay /> markers itself, so an unexcluded scan would pass the
+    // client/surface gates even when NO layout mounts the wrapper — the exact
+    // doctor-green-but-invisible failure E-WIRE-006 exists to catch. Mirror
+    // init's layout decision: exclude the wrapper from the scan, then let a
+    // user-code <VendoRoot> mount next to an overlay-bearing wrapper satisfy
+    // the surface (the wrapper renders the overlay once a layout mounts it).
+    const wrapperCandidates = [
+        join(root, "vendo", "vendo-root.tsx"),
+        join(root, "src", "vendo", "vendo-root.tsx"),
+    ];
+    let wrapperWithOverlay = false;
+    for (const candidate of wrapperCandidates) {
+        const source = await readFile(candidate, "utf8").catch(() => null);
+        if (source !== null && source.includes("<VendoOverlay"))
+            wrapperWithOverlay = true;
+    }
+    const scanned = await detectVendoWiring(root, { exclude: wrapperCandidates });
+    const wiring = { ...scanned, surface: scanned.surface || (scanned.client && wrapperWithOverlay) };
+    if (framework === "unknown") {
+        // No framework to pattern-match (field case: a Cloudflare Worker + Vite
+        // host failed E-WIRE-003/004 forever) — judge the wiring by the same
+        // bounded source scan init uses, never by another framework's file
+        // layout. The surface check below still runs; it is source-generic.
+        if (scanned.server)
+            pass("wiring/server", "createVendo server wiring found");
+        else
+            fail("wiring/server", "E-WIRE-007", "no createVendo server wiring found — import createVendo from @vendoai/vendo/server and mount vendo.handler on your runtime's request entry");
+        if (scanned.client)
+            pass("wiring/client", "<VendoRoot> wraps the client");
+        else
+            warn("wiring/client", "E-WIRE-008", "no <VendoRoot> found in the host source — the @vendoai/ui hooks and embeds need it; ignore this if the host renders a fully custom surface");
+    }
+    else if (framework === "express") {
         if (wiring.server)
             pass("wiring/express-server", "Express server is wired");
         else
@@ -113,21 +146,32 @@ export async function runDoctor(options) {
             pass("wiring/next-route", "catch-all handler is wired");
         else
             fail("wiring/next-route", "E-WIRE-003", "missing app/api/vendo/[...vendo]/route.ts");
-        const layoutCandidates = [join(root, "app", "layout.tsx"), join(root, "src", "app", "layout.tsx")];
+        // The mount may live in ANY layout, not just the root one (i18n/route-group
+        // hosts mount in e.g. app/[locale]/layout.tsx — the literal root-layout
+        // grep fought exactly that correct wiring in the 0.4.1 E2E cert), and the
+        // correct scaffold mounts the generated vendo/vendo-root.tsx wrapper —
+        // whose export is also named VendoRoot, so the marker holds there too.
         let rootWired = false;
-        for (const path of layoutCandidates) {
-            try {
-                if ((await readFile(path, "utf8")).includes("<VendoRoot"))
+        for (const appDir of [join(root, "app"), join(root, "src", "app")]) {
+            for (const path of await walk(appDir, (rel) => /(^|[\\/])layout\.(?:tsx|jsx|js)$/.test(rel))) {
+                const source = await readFile(path, "utf8").catch(() => "");
+                if (source.includes("<VendoRoot") || source.includes("<VendoProvider"))
                     rootWired = true;
             }
-            catch {
-                // Try the other layout convention.
-            }
         }
         if (rootWired)
             pass("wiring/next-root", "<VendoRoot> wraps the app");
         else
-            fail("wiring/next-root", "E-WIRE-004", "root layout is not wrapped in <VendoRoot>");
+            fail("wiring/next-root", "E-WIRE-004", "no app layout mounts <VendoRoot> — wrap the app in the generated vendo/vendo-root.tsx wrapper (its export is also named VendoRoot), in the root layout or any layout that covers your pages");
+    }
+    // Visible surface (0.4.1 E2E cert B3): <VendoRoot> is a context provider
+    // that renders NOTHING — two certified stacks ended doctor-green with no
+    // way for a user to reach the agent. Green must mean visible.
+    if (wiring.surface) {
+        pass("wiring/surface", "a visible agent surface is mounted (<VendoOverlay /> or an equivalent)");
+    }
+    else {
+        fail("wiring/surface", "E-WIRE-006", "no visible agent surface is mounted — <VendoRoot> renders nothing by itself; mount <VendoOverlay /> (init generates vendo/vendo-root.tsx for this), or render your own surface (<VendoThread />, <VendoToolResult>, the BYO embeds)");
     }
     if (await hasDependency(root))
         pass("wiring/dependency", "@vendoai/vendo dependency is declared");
@@ -155,6 +199,42 @@ export async function runDoctor(options) {
     }
     if (!await exists(join(root, ".vendo", "data", ".gitignore")))
         warn("config/data-gitignore", "E-CFG-002", ".vendo/data/.gitignore is missing");
+    // The core promise, statically checkable: does the agent have any HOST
+    // tool it may actually call? All-disabled is an explicit misconfiguration
+    // (fail); an empty extraction is a strong warning — connector-only hosts
+    // are legitimate, but a fresh install landing here means extraction found
+    // nothing user-facing (field case: an infra product whose surface was all
+    // internal endpoints ended with tools: [] and a silently useless agent).
+    const toolsRaw = await readOptional(join(root, ".vendo", "tools.json"));
+    const overridesRaw = await readOptional(join(root, ".vendo", "overrides.json"));
+    if (toolsRaw !== null) {
+        try {
+            const toolsFile = toolsFileSchema.parse(JSON.parse(toolsRaw));
+            let overridesTools = {};
+            if (overridesRaw !== null) {
+                try {
+                    overridesTools = overridesFileSchema.parse(JSON.parse(overridesRaw)).tools;
+                }
+                catch {
+                    // Malformed overrides are their own (pre-existing) failure surface.
+                }
+            }
+            const live = toolsFile.tools.filter((tool) => (overridesTools[tool.name]?.disabled ?? tool.disabled ?? false) !== true);
+            if (toolsFile.tools.length === 0) {
+                warn("tools/live-surface", "E-TOOLS-002", "the extracted tool surface is empty — the agent cannot act on this product's API; re-run `vendo init` extraction (or ignore if this deployment is connector-only)");
+            }
+            else if (live.length === 0) {
+                fail("tools/live-surface", "E-TOOLS-001", `zero live host tools — all ${toolsFile.tools.length} extracted tools are disabled or excluded; review the audience exclusions in .vendo/overrides.json and re-enable the end-user surface (disabled: false)`);
+            }
+            else {
+                pass("tools/live-surface", `${live.length} live host tool${live.length === 1 ? "" : "s"}`);
+            }
+        }
+        catch {
+            // Not the vendo/tools@1 shape (e.g. a placeholder {}) — the config
+            // checks above already govern presence; nothing to grade here.
+        }
+    }
     // §4 customization ladder — ejected chrome drift. The ejected pixels are the
     // host's code, so a version gap is awareness (warn), never breakage (fail):
     // the hooks/wire dependency keeps working; only new presentation is missed.
@@ -235,6 +315,18 @@ export async function runDoctor(options) {
         else {
             pass("live/status", `/status live round-trip (${body.version}, ${body.posture})`);
             liveComposition = true;
+            // Split-brain guard (0.4.2 re-run, invoify defect 13): a direct
+            // @vendoai/vendo dependency pinned to an older range beats the vendoai
+            // umbrella's for the APP import, so `npm install vendoai@latest` runs a
+            // new CLI while /status silently serves the old runtime. Any CLI/wire
+            // version disagreement — split-brain or just a dev server started
+            // before the upgrade — means doctor is not certifying what users run.
+            if (body.version === CLI_VERSION) {
+                pass("deps/version-skew", `CLI and running wire agree on @vendoai/vendo ${CLI_VERSION}`);
+            }
+            else {
+                fail("deps/version-skew", "E-DEP-002", `the running wire serves @vendoai/vendo ${body.version} but this CLI is ${CLI_VERSION} — likely a split-brain install (a direct @vendoai/vendo dependency pinned to an older range wins over the vendoai umbrella's). Fix: npm install @vendoai/vendo@${CLI_VERSION} (or remove the direct @vendoai/vendo dependency and reinstall), then restart the dev server and re-run doctor.`);
+            }
             // 10-mcp §1 — the door flag lives under blocks.mcp.
             mcpEnabled = body.blocks.mcp === true;
             sandboxVenue = body.blocks.sandbox;
@@ -254,7 +346,26 @@ export async function runDoctor(options) {
         }
     }
     catch {
-        fail("live/status", "E-LIVE-002", `/status is unreachable at ${statusUrl}/status`);
+        fail("live/status", "E-LIVE-002", `/status is unreachable at ${statusUrl}/status — doctor expects the WIRE BASE (your app origin plus the mount path, e.g. http://localhost:3000/api/vendo); a bare site origin passed to --url is missing the /api/vendo part`);
+    }
+    // Render gate (0.4.1 E2E cert M3): a live wire proves nothing about the
+    // PAGES — the certified invoify install had every page 500ing (registry
+    // passed across the Server Component boundary) while doctor exited 0. One
+    // cheap GET of the app root catches a site that is down for users.
+    if (liveComposition) {
+        try {
+            const response = await fetchImpl(`${new URL(statusUrl).origin}/`, { headers: { accept: "text/html" } });
+            if (response.status >= 500) {
+                fail("live/render", "E-LIVE-006", `the app's root page returned ${response.status} — the site is crashing for users even though the wire answers (typical cause: the component registry imported in a Server Component layout; mount it via the generated vendo/vendo-root.tsx wrapper instead). Check the dev server log.`);
+            }
+            else {
+                pass("live/render", `the app's root page renders (HTTP ${response.status})`);
+            }
+        }
+        catch {
+            // The wire answered but the origin root didn't resolve at all — hosts
+            // that serve no page at / are not doctor's business; skip silently.
+        }
     }
     if (!liveComposition) {
         fail("auth/present", "E-AUTH-003", `present credential probe cannot run; start the dev server at ${statusUrl} and retry`);

package/dist/cli/extract/apply.js

@@ -1,6 +1,6 @@
 import { join, resolve } from "node:path";
 import { z } from "zod";
-import { vendoSync } from "@vendoai/actions";
+import { vendoSync } from "@vendoai/actions/sync";
 import { detectDepVersions } from "../dep-versions.js";
 import { detectFramework } from "../framework.js";
 import { applyDraft, reportApplied } from "./extraction.js";

package/dist/cli/extract/delegate.js

@@ -41,6 +41,10 @@ export const EXTRACTION_DRAFT_JSON_SCHEMA = {
                         type: "boolean",
                         description: "false = wake a statically-unclassifiable tool (requires reasoning and risk).",
                     },
+                    audience: {
+                        enum: ["end-user", "operator", "internal"],
+                        description: "Who the handler's own auth admits; non-end-user grades exclude the tool by default.",
+                    },
                     reasoning: { type: "string", maxLength: 500 },
                 },
             },
@@ -66,10 +70,14 @@ export function composeDelegatedInstructions(tools, appName) {
         "",
         "Rules:",
         "- Produce ONE json document matching the provided draftSchema:",
-        '  { "brief": string, "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "reasoning"? }], "missedSurfaces"?: string[] }',
+        '  { "brief": string, "tools": [{ "name", "description", "risk"?, "critical"?, "disabled"?, "audience"?, "reasoning"? }], "missedSurfaces"?: string[] }',
         "- tools: include ONLY names from the list above. Rewrite each description so an agent choosing tools understands what it actually does (read the handler source). <= 200 chars each.",
         "- risk: you may RAISE risk (read->write->destructive) when the handler is more dangerous than labeled; never lower it. Mark irreversible operations critical: true.",
         "- A tool listed as disabled was statically unclassifiable. If you can read its handler and grade it, set disabled: false WITH a risk and one-line reasoning. Leave it out otherwise.",
+        "- audience: who the handler's own auth admits — \"end-user\" (a signed-in customer acting on their own data),",
+        "  \"operator\" (admin/staff/support consoles), or \"internal\" (machine-to-machine: webhooks, cron, reconciliation,",
+        "  service tokens). Read the auth checks, not the route name. When unsure, default to internal — non-end-user",
+        "  tools are excluded from the embedded agent by default, and a wrong \"end-user\" grade exposes a privileged surface.",
         "- missedSurfaces: API surfaces you found that the list is missing (path + one line). Do not invent tools for them.",
         "- brief: one paragraph — what the product does, who uses it, the jobs the agent should help with. Written from the actual code, no marketing fluff.",
         `- Save the draft to a json file and apply it with \`${APPLY_COMMAND}\` — deterministic guards validate every entry before anything lands in .vendo/.`,

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

@@ -8,6 +8,10 @@ export interface AppliedSummary {
     riskRaised: number;
     critical: number;
     woken: number;
+    /** Non-end-user-audience tools excluded (disabled) this apply. */
+    excluded: number;
+    /** Tools still live after this apply — zero means the agent cannot act on the host API at all. */
+    enabledAfter: number;
     briefWritten: boolean;
     refused: string[];
     missedSurfaces: string[];

package/dist/cli/extract/extraction.js

@@ -50,7 +50,7 @@ export async function applyDraft(input) {
         ? { format: "vendo/overrides@1", tools: {} }
         : overridesSchema.parse(JSON.parse(raw));
     const summary = {
-        described: 0, riskRaised: 0, critical: 0, woken: 0,
+        described: 0, riskRaised: 0, critical: 0, woken: 0, excluded: 0, enabledAfter: 0,
         briefWritten: false, refused: [], missedSurfaces: input.draft.missedSurfaces ?? [],
     };
     for (const entry of input.draft.tools) {
@@ -70,7 +70,10 @@ export async function applyDraft(input) {
         // evidence, so a reasoned wake carries the model's grade without tripping
         // the downgrade guard (Greptile P1 / Devin on #363). A human-set risk or
         // disabled decision always wins.
-        const isWake = entry.disabled === false && fact.disabled === true;
+        // A wake claiming a non-end-user audience is contradictory; audience
+        // exclusion (fail-closed) wins and the wake leg never runs.
+        const nonEndUser = entry.audience === "operator" || entry.audience === "internal";
+        const isWake = entry.disabled === false && fact.disabled === true && !nonEndUser;
         if (isWake && existing.disabled === undefined) {
             if (entry.reasoning === undefined || entry.risk === undefined) {
                 summary.refused.push(`${entry.name}: waking a disabled tool needs reasoning and a risk grade`);
@@ -96,9 +99,27 @@ export async function applyDraft(input) {
             next.critical = true;
             summary.critical += 1;
         }
+        // Audience: recorded as provenance; a non-end-user grade excludes the
+        // tool by default. A human decision on either field always wins — a
+        // hand-set disabled (true OR false) or audience is never touched.
+        if (entry.audience !== undefined && existing.audience === undefined) {
+            next.audience = entry.audience;
+            if (nonEndUser && existing.disabled === undefined && next.disabled !== false) {
+                if (next.disabled !== true)
+                    summary.excluded += 1;
+                next.disabled = true;
+            }
+        }
         if (JSON.stringify(next) !== JSON.stringify(existing))
             overrides.tools[entry.name] = next;
     }
+    // The number that actually matters to an end user: how many tools the
+    // agent can still call once static grades and overrides settle. Zero means
+    // the product's core promise silently degraded — reportApplied warns.
+    summary.enabledAfter = input.tools.filter((tool) => {
+        const override = overrides.tools[tool.name] ?? {};
+        return (override.disabled ?? tool.disabled ?? false) !== true;
+    }).length;
     await writeText(overridesPath, `${JSON.stringify(overrides, null, 2)}\n`);
     const briefPath = join(input.root, ".vendo", "brief.md");
     const currentBrief = ((await readOptional(briefPath)) ?? "").trim();
@@ -117,6 +138,7 @@ export function reportApplied(input) {
         ...(applied.riskRaised > 0 ? [`${applied.riskRaised} risk raises`] : []),
         ...(applied.critical > 0 ? [`${applied.critical} critical marks`] : []),
         ...(applied.woken > 0 ? [`${applied.woken} tools woken`] : []),
+        ...(applied.excluded > 0 ? [`${applied.excluded} operator/internal tools excluded`] : []),
         ...(input.briefDrafted ? ["brief drafted"] : []),
     ];
     output.log(`AI polish applied: ${parts.join(" · ")} → .vendo/overrides.json, .vendo/brief.md${input.artifactsNote ?? ""}`);
@@ -124,6 +146,11 @@ export function reportApplied(input) {
         output.error(`  ${note}`);
     for (const refused of applied.refused)
         output.error(`  refused: ${refused}`);
+    if (applied.enabledAfter === 0) {
+        output.error("  WARNING: zero live tools after apply — every extracted tool is disabled or excluded, so the embedded "
+            + "agent cannot act on this product's API. Review the audience exclusions in .vendo/overrides.json "
+            + "(re-enable the end-user surface with disabled: false) or re-run extraction.");
+    }
     for (const missed of applied.missedSurfaces)
         output.log(`  missed surface (not extracted yet): ${missed}`);
 }

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

@@ -15,10 +15,14 @@ export declare const draftToolSchema: z.ZodObject<{
     critical: z.ZodOptional<z.ZodBoolean>;
     /** false = wake a statically-unclassifiable tool (needs reasoning). */
     disabled: z.ZodOptional<z.ZodBoolean>;
+    /** Who the handler's own auth admits; non-end-user grades exclude the tool
+     *  by default (applyDraft). */
+    audience: z.ZodOptional<z.ZodEnum<["end-user", "operator", "internal"]>>;
     reasoning: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     description: string;
+    audience?: "end-user" | "operator" | "internal" | undefined;
     risk?: "read" | "write" | "destructive" | undefined;
     critical?: boolean | undefined;
     disabled?: boolean | undefined;
@@ -26,6 +30,7 @@ export declare const draftToolSchema: z.ZodObject<{
 }, {
     name: string;
     description: string;
+    audience?: "end-user" | "operator" | "internal" | undefined;
     risk?: "read" | "write" | "destructive" | undefined;
     critical?: boolean | undefined;
     disabled?: boolean | undefined;
@@ -42,10 +47,14 @@ export declare const extractionDraftSchema: z.ZodObject<{
         critical: z.ZodOptional<z.ZodBoolean>;
         /** false = wake a statically-unclassifiable tool (needs reasoning). */
         disabled: z.ZodOptional<z.ZodBoolean>;
+        /** Who the handler's own auth admits; non-end-user grades exclude the tool
+         *  by default (applyDraft). */
+        audience: z.ZodOptional<z.ZodEnum<["end-user", "operator", "internal"]>>;
         reasoning: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -53,6 +62,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     }, {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -65,6 +75,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     tools: {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;
@@ -76,6 +87,7 @@ export declare const extractionDraftSchema: z.ZodObject<{
     tools: {
         name: string;
         description: string;
+        audience?: "end-user" | "operator" | "internal" | undefined;
         risk?: "read" | "write" | "destructive" | undefined;
         critical?: boolean | undefined;
         disabled?: boolean | undefined;

package/dist/cli/extract/harness.js

@@ -15,6 +15,9 @@ export const draftToolSchema = z.object({
     critical: z.boolean().optional(),
     /** false = wake a statically-unclassifiable tool (needs reasoning). */
     disabled: z.boolean().optional(),
+    /** Who the handler's own auth admits; non-end-user grades exclude the tool
+     *  by default (applyDraft). */
+    audience: z.enum(["end-user", "operator", "internal"]).optional(),
     reasoning: z.string().max(500).optional(),
 });
 export const extractionDraftSchema = z.object({