@vendoai/vendo 0.4.2 → 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"
@@ -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/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` +

package/dist/cli/init.d.ts

@@ -21,7 +21,8 @@ export interface InitPlan {
         path: string;
         diff: string;
     }>;
-    /** The one line init never writes itself: the user pastes it. */
+    /** Whatever wiring the run could not do safely itself (empty when the
+        layout auto-wire landed): the paste lines for the user. */
     manualSteps: string[];
     /** --agent only: deterministic extraction results, so an agent can act on
         real tool names instead of re-deriving them. */
@@ -114,5 +115,14 @@ export interface StarProcess {
     repo URL instead, one line, no error noise. Exported for the timeout's
     direct unit test only. */
 export declare function starViaGh(spawnStar: NonNullable<InitOptions["spawnStar"]>, timeoutMs?: number): Promise<boolean>;
+/**
+ * The one bounded edit init makes to user-authored code (visible-surface fix,
+ * 0.4.1 E2E cert B3): mount the generated client wrapper around the layout's
+ * `{children}` and import it. Null — leave the file untouched, fall back to
+ * the printed paste — whenever a Vendo mount already exists (idempotence) or
+ * the file doesn't have exactly one JSX `{children}` to wrap (ambiguity).
+ * Exported for direct unit tests.
+ */
+export declare function wireNextLayout(source: string, wrapperSpecifier: string): string | null;
 /** 09-vendo §5 — idempotent, zero-question setup. */
 export declare function runInit(options: InitOptions): Promise<number>;