@vendoai/vendo 0.4.1 → 0.4.3

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"
@@ -91,13 +116,28 @@ export async function runDeviceLogin(args, options = {}) {
     const waitSeconds = waitRaw !== undefined && /^\d+$/.test(waitRaw) ? Number(waitRaw) : undefined;
     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 —
-        // still lands the key. An expired or unreadable file is discarded (a
-        // fresh ceremony overwrites it below).
-        const pending = await readPendingClaim(pendingHome);
-        const resume = pending !== null && pending.api_url === base && pending.expires_at > now()
+        // still lands the key. Claims are scoped per project directory (0.4.2):
+        // only THIS cwd's ceremony is ever resumed, so concurrent logins in other
+        // repos neither clobber this one nor get resumed by it. An expired or
+        // unreadable file is discarded (a fresh ceremony overwrites it below).
+        const pending = await readPendingClaim(claimCwd, pendingHome);
+        const resume = pending !== null && pending.api_url === base && pending.cwd === claimCwd && pending.expires_at > now()
             ? pending
             : null;
         let claimToken;
@@ -173,8 +213,22 @@ 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);
-                await deletePendingClaim(pendingHome);
+                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.
                 output.log(`Approved — wrote VENDO_API_KEY (…${key.slice(-4)}) to ${resume !== null ? join(root, ".env.local") : ".env.local"}.`);
@@ -190,11 +244,11 @@ export async function runDeviceLogin(args, options = {}) {
             if (error === "slow_down")
                 return "slow_down"; // RFC 8628 §3.5
             if (error === "expired_token") {
-                await deletePendingClaim(pendingHome);
+                await deletePendingClaim(claimCwd, pendingHome);
                 throw new Error("The code expired before it was approved; run `vendo login` again.");
             }
             if (error === "access_denied") {
-                await deletePendingClaim(pendingHome);
+                await deletePendingClaim(claimCwd, pendingHome);
                 throw new Error("Your human denied the request — no key was minted.");
             }
             // Any other token error is terminal for THIS claim (invalid_grant =
@@ -202,7 +256,7 @@ export async function runDeviceLogin(args, options = {}) {
             // again). Delete the pending file so the next `vendo login` opens a
             // fresh claim instead of resuming into the same error forever — the
             // exact trap a live install hit.
-            await deletePendingClaim(pendingHome);
+            await deletePendingClaim(claimCwd, pendingHome);
             const description = poll.body?.error_description;
             throw new Error(typeof description === "string"
                 ? description
@@ -230,7 +284,7 @@ export async function runDeviceLogin(args, options = {}) {
                 if (result === "slow_down")
                     intervalMs += 5000;
             }
-            await deletePendingClaim(pendingHome);
+            await deletePendingClaim(claimCwd, pendingHome);
             throw new Error("The code expired before it was approved; run `vendo login` again.");
         }
         // Bounded budget: poll immediately, then pace by interval, stopping at
@@ -243,7 +297,7 @@ export async function runDeviceLogin(args, options = {}) {
             if (result === "slow_down")
                 intervalMs += 5000;
             if (now() >= deadline) {
-                await deletePendingClaim(pendingHome);
+                await deletePendingClaim(claimCwd, pendingHome);
                 throw new Error("The code expired before it was approved; run `vendo login` again.");
             }
             if (now() >= pollDeadline)

package/dist/cli/cloud/pending-claim.d.ts

@@ -23,7 +23,10 @@ export interface PendingClaimOptions {
     home?: string;
 }
 /** An unreadable or malformed file reads as "no pending claim" — the caller
-    discards it by opening (and persisting) a fresh ceremony. */
-export declare function readPendingClaim(options?: PendingClaimOptions): Promise<PendingClaim | null>;
+    discards it by opening (and persisting) a fresh ceremony. Only a claim
+    opened for THIS cwd is ever returned. A pre-0.4.2 machine-global file is
+    honored (and migrated) only when its recorded cwd matches; someone else's
+    ceremony is never resumed. */
+export declare function readPendingClaim(cwd: string, options?: PendingClaimOptions): Promise<PendingClaim | null>;
 export declare function writePendingClaim(claim: PendingClaim, options?: PendingClaimOptions): Promise<void>;
-export declare function deletePendingClaim(options?: PendingClaimOptions): Promise<void>;
+export declare function deletePendingClaim(cwd: string, options?: PendingClaimOptions): Promise<void>;

package/dist/cli/cloud/pending-claim.js

@@ -1,7 +1,17 @@
+import { createHash } from "node:crypto";
 import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
-function pendingClaimPath(options = {}) {
+/** Claims are keyed by the project directory they were opened for. A single
+    machine-global file let two concurrent `vendo login` runs clobber each
+    other, and let project A resume (and receive the key for) project B's
+    ceremony — found by the 0.4.1 E2E certification campaign. */
+function pendingClaimPath(cwd, options = {}) {
+    const name = `${createHash("sha256").update(cwd).digest("hex").slice(0, 16)}.json`;
+    return join(options.home ?? homedir(), ".vendo", "pending-claims", name);
+}
+/** The pre-0.4.2 machine-global location — read once for migration. */
+function legacyPendingClaimPath(options = {}) {
     return join(options.home ?? homedir(), ".vendo", "pending-claim.json");
 }
 function isPendingClaim(value) {
@@ -16,23 +26,37 @@ function isPendingClaim(value) {
         && typeof claim.api_url === "string"
         && typeof claim.cwd === "string";
 }
-/** An unreadable or malformed file reads as "no pending claim" — the caller
-    discards it by opening (and persisting) a fresh ceremony. */
-export async function readPendingClaim(options = {}) {
+async function readClaimFile(path) {
     try {
-        const value = JSON.parse(await readFile(pendingClaimPath(options), "utf8"));
+        const value = JSON.parse(await readFile(path, "utf8"));
         return isPendingClaim(value) ? value : null;
     }
     catch {
         return null;
     }
 }
+/** An unreadable or malformed file reads as "no pending claim" — the caller
+    discards it by opening (and persisting) a fresh ceremony. Only a claim
+    opened for THIS cwd is ever returned. A pre-0.4.2 machine-global file is
+    honored (and migrated) only when its recorded cwd matches; someone else's
+    ceremony is never resumed. */
+export async function readPendingClaim(cwd, options = {}) {
+    const scoped = await readClaimFile(pendingClaimPath(cwd, options));
+    if (scoped !== null)
+        return scoped.cwd === cwd ? scoped : null;
+    const legacy = await readClaimFile(legacyPendingClaimPath(options));
+    if (legacy === null || legacy.cwd !== cwd)
+        return null;
+    await writePendingClaim(legacy, options);
+    await rm(legacyPendingClaimPath(options), { force: true });
+    return legacy;
+}
 export async function writePendingClaim(claim, options = {}) {
-    const path = pendingClaimPath(options);
+    const path = pendingClaimPath(claim.cwd, options);
     await mkdir(join(path, ".."), { recursive: true, mode: 0o700 });
     await writeFile(path, `${JSON.stringify(claim, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
     await chmod(path, 0o600);
 }
-export async function deletePendingClaim(options = {}) {
-    await rm(pendingClaimPath(options), { force: true });
+export async function deletePendingClaim(cwd, options = {}) {
+    await rm(pendingClaimPath(cwd, options), { force: true });
 }

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

@@ -17,9 +17,11 @@ 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-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 +29,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";

package/dist/cli/doctor-codes.js

@@ -18,9 +18,11 @@ 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-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 +30,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",

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

@@ -93,8 +93,26 @@ 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);
+    // 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 === "express") {
-        const wiring = await detectVendoWiring(root);
         if (wiring.server)
             pass("wiring/express-server", "Express server is wired");
         else
@@ -113,21 +131,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");
@@ -235,6 +264,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 +295,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/framework.d.ts

@@ -2,7 +2,22 @@ export type HostFramework = "next" | "express" | "unknown";
 export interface VendoWiring {
     server: boolean;
     client: boolean;
+    /** A VISIBLE agent surface is mounted — <VendoRoot> alone is a context
+        provider that renders nothing (0.4.1 E2E cert B3: by-the-book installs
+        ended doctor-green with nothing on screen). */
+    surface: boolean;
 }
+/** What counts as a visible surface: the shipped chrome (<VendoOverlay> and
+    the pieces it is built from), the BYO embeds a host chat renders, and the
+    hooks a host uses to drive a custom surface. Deliberately generous — this
+    list gates a doctor FAILURE, so a host with any plausible surface of its
+    own must pass. */
+export declare const SURFACE_MARKERS: readonly string[];
 export declare function detectFramework(root: string): Promise<HostFramework>;
-/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
-export declare function detectVendoWiring(root: string): Promise<VendoWiring>;
+/** Bounded source scan shared by init and doctor so their wiring verdicts
+    agree. `exclude` skips generated files whose own markers would count as
+    host wiring (init's layout decision excludes the vendo-root wrapper: its
+    <VendoOverlay /> is only real once a layout mounts the wrapper itself). */
+export declare function detectVendoWiring(root: string, options?: {
+    exclude?: string[];
+}): Promise<VendoWiring>;

package/dist/cli/framework.js

@@ -1,6 +1,24 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { walk } from "./theme/walk.js";
+/** What counts as a visible surface: the shipped chrome (<VendoOverlay> and
+    the pieces it is built from), the BYO embeds a host chat renders, and the
+    hooks a host uses to drive a custom surface. Deliberately generous — this
+    list gates a doctor FAILURE, so a host with any plausible surface of its
+    own must pass. */
+export const SURFACE_MARKERS = [
+    "<VendoOverlay",
+    "<VendoThread",
+    "<VendoTrigger",
+    "<VendoPalette",
+    "<VendoSlot",
+    "<VendoAppEmbed",
+    "<VendoApprovalEmbed",
+    "<VendoToolResult",
+    "useVendoOverlay(",
+    "useVendoThread(",
+    "useSlotApp(",
+];
 const SOURCE_FILE = /\.(?:[cm]?[jt]sx?)$/;
 const SOURCE_SCAN_MAX_FILES = 2_000;
 export async function detectFramework(root) {
@@ -17,20 +35,29 @@ export async function detectFramework(root) {
         return "unknown";
     }
 }
-/** Bounded source scan shared by init and doctor so their wiring verdicts agree. */
-export async function detectVendoWiring(root) {
+/** Bounded source scan shared by init and doctor so their wiring verdicts
+    agree. `exclude` skips generated files whose own markers would count as
+    host wiring (init's layout decision excludes the vendo-root wrapper: its
+    <VendoOverlay /> is only real once a layout mounts the wrapper itself). */
+export async function detectVendoWiring(root, options = {}) {
     let server = false;
     let client = false;
+    let surface = false;
+    const excluded = new Set(options.exclude ?? []);
     const files = await walk(root, (relativePath) => SOURCE_FILE.test(relativePath), SOURCE_SCAN_MAX_FILES);
     for (const file of files) {
+        if (excluded.has(file))
+            continue;
         const source = await readFile(file, "utf8").catch(() => "");
         const code = source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
         if (code.includes("@vendoai/vendo/server") && /\bcreateVendo\s*\(/.test(code))
             server = true;
-        if (code.includes("<VendoRoot"))
+        if (code.includes("<VendoRoot") || code.includes("<VendoProvider"))
             client = true;
-        if (server && client)
+        if (SURFACE_MARKERS.some((marker) => code.includes(marker)))
+            surface = true;
+        if (server && client && surface)
             break;
     }
-    return { server, client };
+    return { server, client, surface };
 }

package/dist/cli/init-scaffolds.d.ts

@@ -8,6 +8,28 @@ export declare function authConfigLines(auth: AuthMatch): string;
     as `catalog` (data fields only), `<VendoRoot components={registry}>` reads
     the component references. Generated only while absent — never clobbered. */
 export declare function registrySource(variant: "tsx" | "mjs"): string;
+/** The anonymous-composition principal line (no auth preset wired). The
+    subject matches the demo principal both existing-agents quickstarts set in
+    their chat routes — the wire route MUST resolve the same subject as the
+    host's agent loop, or every app/approval created in chat is invisible to
+    the embeds, which call this route directly (0.4.1 E2E cert blocker B4:
+    a `() => null` wire against a demo-user chat route rendered an infinite
+    skeleton). Replaced wholesale when an auth preset is wired. */
+export declare function anonymousPrincipalLines(): string;
+/**
+ * The client mount wrapper (visible-surface fix, 0.4.1 E2E cert B3/M3): one
+ * generated "use client" boundary owns the registry + theme imports and
+ * mounts `<VendoOverlay />` — the launcher pill + panel end users actually
+ * see. The registry holds component references, so importing it in a Server
+ * Component layout and passing it into the client provider fails RSC
+ * serialization ("Only plain objects can be passed to Client Components");
+ * this wrapper is the layout-safe mount. Generated only while absent.
+ */
+export declare function vendoRootWrapperSource(options: {
+    /** Posix-style import specifier from the wrapper's dir to .vendo/theme.json,
+        or null when resolveJsonModule is explicitly disabled. */
+    themeSpecifier: string | null;
+}): string;
 export declare function routeSource(options: {
     serverActions: boolean;
     auth: AuthMatch | null;

package/dist/cli/init-scaffolds.js

@@ -48,6 +48,56 @@ export function registrySource(variant) {
         ? `${header}import type { ComponentRegistry } from "@vendoai/vendo";\n\nexport const registry = {} satisfies ComponentRegistry;\n`
         : `${header}export const registry = {};\n`;
 }
+/** The anonymous-composition principal line (no auth preset wired). The
+    subject matches the demo principal both existing-agents quickstarts set in
+    their chat routes — the wire route MUST resolve the same subject as the
+    host's agent loop, or every app/approval created in chat is invisible to
+    the embeds, which call this route directly (0.4.1 E2E cert blocker B4:
+    a `() => null` wire against a demo-user chat route rendered an infinite
+    skeleton). Replaced wholesale when an auth preset is wired. */
+export function anonymousPrincipalLines() {
+    return `  // Who the wire's callers act as. This must resolve the SAME subject your\n` +
+        `  // agent loop uses (the docs' chat routes set this demo principal), or apps\n` +
+        `  // and approvals created in chat are invisible to the embeds, which call\n` +
+        `  // this route directly. Replace both sides with your real session lookup.\n` +
+        `  principal: async () => ({ kind: "user" as const, subject: "demo-user" }),\n`;
+}
+/**
+ * The client mount wrapper (visible-surface fix, 0.4.1 E2E cert B3/M3): one
+ * generated "use client" boundary owns the registry + theme imports and
+ * mounts `<VendoOverlay />` — the launcher pill + panel end users actually
+ * see. The registry holds component references, so importing it in a Server
+ * Component layout and passing it into the client provider fails RSC
+ * serialization ("Only plain objects can be passed to Client Components");
+ * this wrapper is the layout-safe mount. Generated only while absent.
+ */
+export function vendoRootWrapperSource(options) {
+    const withTheme = options.themeSpecifier !== null;
+    return `"use client";\n\n` +
+        `/**\n` +
+        ` * The Vendo client mount — generated by \`vendo init\`, then yours.\n` +
+        ` * This "use client" boundary owns the registry${withTheme ? " and theme" : ""} imports: the\n` +
+        ` * registry carries component references, which cannot cross a Server\n` +
+        ` * Component boundary as props (RSC serialization). <VendoOverlay /> is the\n` +
+        ` * visible surface — the launcher pill + panel. Swap it for your own\n` +
+        ` * surface (<VendoThread />, the BYO embeds) whenever you like.\n` +
+        ` */\n` +
+        `import { VendoOverlay, VendoRoot as VendoClientRoot } from "@vendoai/vendo/react";\n` +
+        `import type { ReactNode } from "react";\n` +
+        `import { registry } from "./registry";\n` +
+        (withTheme
+            ? `import theme from ${JSON.stringify(options.themeSpecifier)};\n` +
+                `import type { VendoTheme } from "@vendoai/vendo";\n`
+            : "") +
+        `\nexport function VendoRoot({ children }: { children: ReactNode }) {\n` +
+        `  return (\n` +
+        `    <VendoClientRoot components={registry}${withTheme ? " theme={theme as VendoTheme}" : ""}>\n` +
+        `      {children}\n` +
+        `      <VendoOverlay />\n` +
+        `    </VendoClientRoot>\n` +
+        `  );\n` +
+        `}\n`;
+}
 /** The preset's own import line (its own subpath, never "@vendoai/vendo/server"
     — corpus-triage Task 9: a shared barrel meant any host importing the
     server entry statically re-resolved every preset's optional peer dep,
@@ -61,7 +111,7 @@ export function routeSource(options) {
         (options.serverActions ? `import { serverActions } from "./vendo-actions";\n` : "") +
         `import { registry } from ${JSON.stringify(options.registrySpecifier)};\n` +
         `\nconst vendo = createVendo({\n` +
-        (options.auth === null ? `  principal: async () => null,\n` : authConfigLines(options.auth)) +
+        (options.auth === null ? anonymousPrincipalLines() : authConfigLines(options.auth)) +
         `  catalog: registry,\n` +
         (options.serverActions ? `  serverActions,\n` : "") +
         `  policy: {}, // .vendo/policy.json: destructive asks, reads run\n` +
@@ -143,17 +193,19 @@ export function expressServerSource(typescript, auth = null) {
     const registrySpecifier = typescript ? "./registry" : "./registry.mjs";
     const clientHint = typescript
         ? ` *   // in the client entry — theme.json adopts the host brand (08 §4);\n` +
-            ` *   // the cast narrows TypeScript's widened JSON-module string literals:\n` +
-            ` *   import { VendoRoot } from "@vendoai/vendo/react";\n` +
+            ` *   // the cast narrows TypeScript's widened JSON-module string literals;\n` +
+            ` *   // <VendoOverlay /> is the visible surface (launcher pill + panel):\n` +
+            ` *   import { VendoOverlay, VendoRoot } from "@vendoai/vendo/react";\n` +
             ` *   import { registry } from "<path-to>/vendo/registry";\n` +
             ` *   import theme from "<path-to>/.vendo/theme.json";\n` +
             ` *   import type { VendoTheme } from "@vendoai/vendo";\n` +
-            ` *   root.render(<VendoRoot components={registry} theme={theme as VendoTheme}><App /></VendoRoot>);\n`
-        : ` *   // in the client entry — theme.json adopts the host brand (08 §4):\n` +
-            ` *   import { VendoRoot } from "@vendoai/vendo/react";\n` +
+            ` *   root.render(<VendoRoot components={registry} theme={theme as VendoTheme}><App /><VendoOverlay /></VendoRoot>);\n`
+        : ` *   // in the client entry — theme.json adopts the host brand (08 §4);\n` +
+            ` *   // <VendoOverlay /> is the visible surface (launcher pill + panel):\n` +
+            ` *   import { VendoOverlay, VendoRoot } from "@vendoai/vendo/react";\n` +
             ` *   import { registry } from "<path-to>/vendo/registry.mjs";\n` +
             ` *   import theme from "<path-to>/.vendo/theme.json";\n` +
-            ` *   root.render(<VendoRoot components={registry} theme={theme}><App /></VendoRoot>);\n`;
+            ` *   root.render(<VendoRoot components={registry} theme={theme}><App /><VendoOverlay /></VendoRoot>);\n`;
     return `/**\n` +
         ` * Add these wiring lines in your host:\n` +
         ` *   app.use("/api/vendo", mountVendo());\n` +
@@ -165,7 +217,7 @@ export function expressServerSource(typescript, auth = null) {
         `import { registry } from ${JSON.stringify(registrySpecifier)};\n` +
         types +
         `\nconst vendo = createVendo({\n` +
-        (auth === null ? `  principal: async () => null,\n` : authConfigLines(auth)) +
+        (auth === null ? anonymousPrincipalLines() : authConfigLines(auth)) +
         `  catalog: registry,\n` +
         `  policy: {}, // .vendo/policy.json: destructive asks, reads run\n` +
         `});\n\n` +