@vincentt-xr/cli 0.1.4 → 0.2.0

package/dist/login/loginCommand.js

@@ -0,0 +1,72 @@
+// `vincentt login` transcript orchestration — the L1–L4 flows from the f1 design's
+// CLI section, using the design-system CLI voice (→ in-progress, ✓ success, ✗ failure;
+// never prompt for an org; one success line names identity + active org; every error ends
+// with the exact next command; a token is NEVER printed; no stack traces).
+//
+// The IO boundary (print, current identity, run the PKCE flow, clock) is injected so every
+// L1–L4 branch is unit-testable with no real browser, socket, or config file.
+/** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
+export function displayConfigPath(absPath, home) {
+    if (home && absPath.startsWith(home))
+        return `~${absPath.slice(home.length)}`;
+    return absPath;
+}
+/** The active org is the personal one (login lands on personal; the CLI never prompts). */
+export function activeOrg(memberships) {
+    return memberships.find((m) => m.orgKind === "personal") ?? memberships[0];
+}
+/**
+ * The success line's org clause: "Active org: <personal>" plus, when the user belongs to
+ * team orgs too, "· also a member of: A, B". A platform-invited creator with only a personal
+ * org gets just the active-org line (no trailing clause).
+ */
+export function orgSummaryLine(identity) {
+    const active = activeOrg(identity.memberships);
+    const activeName = active?.orgName ?? "Personal";
+    const others = identity.memberships
+        .filter((m) => m !== active)
+        .map((m) => m.orgName)
+        .filter(Boolean);
+    const base = `  Active org: ${activeName}`;
+    return others.length ? `${base}   ·   also a member of: ${others.join(", ")}` : base;
+}
+/**
+ * Drive `vincentt login`. Returns an exit code (0 ok, 1 failed). Never throws for expected
+ * failure states (timeout, cancel, state-mismatch) — they print a ✗ line ending with the
+ * exact retry command and return 1. No stack trace, no token printed.
+ */
+export async function loginCommand(deps, opts = {}) {
+    const displayPath = displayConfigPath(deps.configPath, deps.home);
+    if (opts.force) {
+        deps.print("→ Replacing the existing token on this machine…");
+        await deps.clearToken();
+    }
+    else {
+        // L2 — already signed in: no browser, no re-mint.
+        const existing = await deps.currentToken();
+        if (existing) {
+            const who = await deps.whoAmI().catch(() => undefined);
+            const email = who?.email ?? "your account";
+            deps.print(`✓ Already signed in as ${email} (token in ${displayPath})`);
+            deps.print("  Re-run with `vincentt login --force` to sign in as someone else.");
+            return 0;
+        }
+    }
+    // L1 / L4 — run the loopback + PKCE flow.
+    try {
+        const { identity, configPath } = await deps.runLogin();
+        deps.print(`✓ Signed in as ${identity.email}`);
+        deps.print(orgSummaryLine(identity));
+        deps.print(`  Token saved to ${displayConfigPath(configPath, deps.home)}`);
+        deps.print("");
+        deps.print("Run `vincentt --help` to see what you can do.");
+        return 0;
+    }
+    catch (err) {
+        // L4 — timeout / callback failure: ✗ line + the exact next command. No token written.
+        const message = err instanceof Error ? err.message : "Sign-in failed.";
+        deps.print(`✗ ${message}`);
+        deps.print("  Run `vincentt login` to try again.");
+        return 1;
+    }
+}

package/dist/login/pkce.d.ts

@@ -0,0 +1,47 @@
+/** The PKCE + state material minted once per login attempt. */
+export interface PkceMaterial {
+    /** Opaque anti-CSRF token echoed back on the loopback callback; verified constant-time. */
+    state: string;
+    /** The secret the CLI keeps; sent to /exchange. Never leaves the machine until then. */
+    codeVerifier: string;
+    /** base64url(SHA-256(codeVerifier)); sent to the browser/console, binds the exchange. */
+    codeChallenge: string;
+}
+/** SHA-256 → base64url. Exported for the exchange-binding assertion in tests. */
+export declare function s256(input: string): string;
+/**
+ * Mint fresh `state` + PKCE `code_verifier`/`code_challenge` (S256). The verifier is a
+ * high-entropy 32-byte value (well within RFC 7636's 43–128 char range once base64url'd).
+ */
+export declare function makePkceMaterial(): PkceMaterial;
+/**
+ * Constant-time equality for the returned `state` vs the expected one. Length-mismatched
+ * inputs return false without leaking timing (timingSafeEqual throws on unequal lengths).
+ */
+export declare function stateMatches(expected: string, actual: string | null): boolean;
+/** Prefix a scheme when the user passed a bare host; localhost defaults to http. */
+export declare function normalizeBaseUrl(u: string): string;
+/**
+ * The console URL the browser opens: `/cli-auth?redirect_uri=<loopback>&state=…&code_challenge=…`.
+ * The console signs the user in (passwordless), shows the Grant CLI access consent screen,
+ * POSTs /access-tokens {code_challenge, state}, and redirects the resulting auth_code to the
+ * loopback. The code_verifier is NOT in this URL — only its challenge.
+ */
+export declare function buildCliAuthUrl(consoleBase: string, redirectUri: string, material: PkceMaterial): string;
+/** A compact, human-copyable fallback URL for the "if it doesn't open" line. */
+export declare function shortenUrl(url: string, max?: number): string;
+export type CallbackResult = {
+    ok: true;
+    code: string;
+} | {
+    ok: false;
+    reason: "state_mismatch" | "denied" | "missing_code";
+    message: string;
+};
+/**
+ * Interpret the loopback redirect (`127.0.0.1:PORT?code=…&state=…`). State is verified
+ * constant-time FIRST, always — a mismatch rejects before the code is even read, so a
+ * forged/stray callback can never drive an exchange (QA-F1-C3). The console signals a
+ * user cancel via `?error=access_denied`.
+ */
+export declare function parseCallback(params: URLSearchParams, expectedState: string): CallbackResult;

package/dist/login/pkce.js

@@ -0,0 +1,106 @@
+// PKCE + loopback protocol primitives for `vincentt login` (f1 account/org model).
+//
+// The durable PAT is NEVER placed in a redirect query string. The browser round-trip
+// carries only a single-use, short-TTL `auth_code`; the CLI redeems it over a POST to
+// /access-tokens/exchange with a PKCE `code_verifier`, and the raw PAT is returned in the
+// response body, once. A stolen redirect (?code=…) is useless without the CLI's verifier.
+//
+// These are the pure, side-effect-free pieces (crypto + URL shaping + constant-time
+// state compare) split out from the loopback/HTTP orchestration in pkceLogin.ts so every
+// branch is unit-testable without a browser or a socket.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+/** base64url with no padding (RFC 7636 §A). */
+function base64url(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
+}
+/** SHA-256 → base64url. Exported for the exchange-binding assertion in tests. */
+export function s256(input) {
+    return base64url(createHash("sha256").update(input).digest());
+}
+/**
+ * Mint fresh `state` + PKCE `code_verifier`/`code_challenge` (S256). The verifier is a
+ * high-entropy 32-byte value (well within RFC 7636's 43–128 char range once base64url'd).
+ */
+export function makePkceMaterial() {
+    const state = base64url(randomBytes(24));
+    const codeVerifier = base64url(randomBytes(32));
+    return { state, codeVerifier, codeChallenge: s256(codeVerifier) };
+}
+/**
+ * Constant-time equality for the returned `state` vs the expected one. Length-mismatched
+ * inputs return false without leaking timing (timingSafeEqual throws on unequal lengths).
+ */
+export function stateMatches(expected, actual) {
+    if (actual == null)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(actual);
+    if (a.length !== b.length)
+        return false;
+    return timingSafeEqual(a, b);
+}
+/** Prefix a scheme when the user passed a bare host; localhost defaults to http. */
+export function normalizeBaseUrl(u) {
+    if (/^https?:\/\//i.test(u))
+        return u;
+    const local = /^(localhost|127\.0\.0\.1)(:|\/|$)/i.test(u);
+    return `${local ? "http" : "https"}://${u}`;
+}
+/**
+ * The console URL the browser opens: `/cli-auth?redirect_uri=<loopback>&state=…&code_challenge=…`.
+ * The console signs the user in (passwordless), shows the Grant CLI access consent screen,
+ * POSTs /access-tokens {code_challenge, state}, and redirects the resulting auth_code to the
+ * loopback. The code_verifier is NOT in this URL — only its challenge.
+ */
+export function buildCliAuthUrl(consoleBase, redirectUri, material) {
+    const u = new URL("/cli-auth", normalizeBaseUrl(consoleBase));
+    // Param name is `redirect_uri` (OAuth convention) — the console's parseCliParams reads
+    // exactly this; `state` + `code_challenge` also match the console contract. The verifier
+    // is NEVER put here.
+    u.searchParams.set("redirect_uri", redirectUri);
+    u.searchParams.set("state", material.state);
+    u.searchParams.set("code_challenge", material.codeChallenge);
+    return u.toString();
+}
+/** A compact, human-copyable fallback URL for the "if it doesn't open" line. */
+export function shortenUrl(url, max = 60) {
+    return url.length <= max ? url : `${url.slice(0, max - 1)}…`;
+}
+/**
+ * Interpret the loopback redirect (`127.0.0.1:PORT?code=…&state=…`). State is verified
+ * constant-time FIRST, always — a mismatch rejects before the code is even read, so a
+ * forged/stray callback can never drive an exchange (QA-F1-C3). The console signals a
+ * user cancel via `?error=access_denied`.
+ */
+export function parseCallback(params, expectedState) {
+    if (!stateMatches(expectedState, params.get("state"))) {
+        return {
+            ok: false,
+            reason: "state_mismatch",
+            message: "State mismatch — ignoring an unexpected callback.",
+        };
+    }
+    const error = params.get("error");
+    if (error) {
+        return {
+            ok: false,
+            reason: "denied",
+            message: error === "access_denied"
+                ? "Access was cancelled in the browser."
+                : `Sign-in failed: ${error}`,
+        };
+    }
+    const code = params.get("code");
+    if (!code) {
+        return {
+            ok: false,
+            reason: "missing_code",
+            message: "No authorization code in the callback.",
+        };
+    }
+    return { ok: true, code };
+}

package/dist/login/pkceLogin.d.ts

@@ -0,0 +1,53 @@
+import { type AuthBackend, type Identity } from "./authBackend.js";
+export interface PkceLoginOptions {
+    /** Console origin that serves /cli-auth (browser target). */
+    consoleUrl: string;
+    /** Backend API base URL the PAT authenticates against. */
+    apiUrl: string;
+    /** Abort if the browser round-trip doesn't complete in time. Default 5 min. */
+    timeoutMs?: number;
+    /** Backend calls (exchange + me). Default: real HTTP against apiUrl. */
+    backend?: AuthBackend;
+    /** Pick a free loopback port. Default: the OS ephemeral picker. */
+    pickPort?: () => Promise<number>;
+    /** Launch the browser. Default: spawn the platform opener. Tests pass a capturing fake. */
+    openBrowser?: (url: string) => void;
+    /** Persist the PAT. Default: write ~/.vincentt/config.json. */
+    saveToken?: (apiUrl: string, pat: string) => Promise<string>;
+    /** Emit an in-progress line (the "→ Opening…" / fallback / "Waiting…" narration). */
+    onProgress?: (line: string) => void;
+}
+export interface PkceLoginResult {
+    identity: Identity;
+    configPath: string;
+}
+/** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
+export declare class LoginTimeoutError extends Error {
+    constructor();
+}
+/** Thrown when the loopback callback fails state-verify or is cancelled (QA-F1-C3). */
+export declare class LoginCallbackError extends Error {
+    constructor(message: string);
+}
+/** The platform command + args to open `url` in the default browser. */
+export declare function browserOpenCommand(url: string, platform?: string): {
+    cmd: string;
+    args: string[];
+};
+type SpawnLike = (cmd: string, args: string[], opts: {
+    stdio: "ignore";
+    detached: boolean;
+}) => {
+    on: (e: "error", cb: () => void) => void;
+    unref: () => void;
+};
+/** Launch the browser via an injected spawn; a throw is swallowed (fallback = the printed URL). */
+export declare function launchBrowser(url: string, spawn: SpawnLike, platform?: string): void;
+/**
+ * Run the loopback + PKCE exchange, persist the PAT, and confirm identity via /me.
+ * Resolves with the confirmed identity + the config path; rejects with LoginTimeoutError
+ * or LoginCallbackError. NO token is written on any failure (the write only happens after
+ * a successful exchange).
+ */
+export declare function runPkceLogin(opts: PkceLoginOptions): Promise<PkceLoginResult>;
+export {};

package/dist/login/pkceLogin.js

@@ -0,0 +1,152 @@
+// The `vincentt login` loopback + PKCE code-exchange orchestration (f1 Scenario 4).
+//
+// Ordering is security-load-bearing:
+//   1. Start the loopback listener on 127.0.0.1:<ephemeral> FIRST (before the browser).
+//   2. Mint state + PKCE code_verifier/code_challenge (S256).
+//   3. Open the browser to /cli-auth?redirect_uri=<loopback>&state=…&code_challenge=….
+//   4. On the loopback callback: verify state constant-time (reject mismatch → no exchange).
+//   5. POST /access-tokens/exchange {code, code_verifier} → raw PAT (in body, once).
+//   6. Write ~/.vincentt/config.json, then GET /me Bearer <PAT> to confirm identity + orgs.
+//
+// Every external boundary is injected (getFreePort, listen, openBrowser, backend, clock/
+// timeout, config write) so the whole flow is unit-testable against a stub backend + fake
+// browser + temp config dir, with no real socket or network.
+import { createServer } from "node:http";
+import { getFreePort } from "../preview/net.js";
+import { writeMachineConfig } from "../shared/config.js";
+import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.js";
+import { httpAuthBackend } from "./authBackend.js";
+/** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
+export class LoginTimeoutError extends Error {
+    constructor() {
+        super("Sign-in timed out (no approval within 5 minutes).");
+        this.name = "LoginTimeoutError";
+    }
+}
+/** Thrown when the loopback callback fails state-verify or is cancelled (QA-F1-C3). */
+export class LoginCallbackError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LoginCallbackError";
+    }
+}
+/** The platform command + args to open `url` in the default browser. */
+export function browserOpenCommand(url, platform = process.platform) {
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    return { cmd, args };
+}
+/** Launch the browser via an injected spawn; a throw is swallowed (fallback = the printed URL). */
+export function launchBrowser(url, spawn, platform) {
+    const { cmd, args } = browserOpenCommand(url, platform);
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* falls back to the printed URL — never fatal */
+    }
+}
+function defaultOpenBrowser(url) {
+    // Lazy import keeps this module importable in tests that never open a browser.
+    void import("node:child_process").then(({ spawn }) => launchBrowser(url, spawn));
+}
+// The loopback success/failure page. This is a standalone HTTP response served on
+// 127.0.0.1 (it cannot import the console's React design system), so the console's
+// AuthLayout auth-card is mirrored here token-for-token: --color-sand page, white
+// --color-surface card (rounded-2xl, p-7), the terminal glyph on --color-primary-faint,
+// and the light/dark palette. A subtle green/red tints only the glyph on ok/failure.
+function browserPage(ok, heading, body) {
+    // The terminal glyph the console uses on the Grant-CLI screen (icons.terminal).
+    const glyph = '<svg width="22" height="22" viewBox="0 0 24 24" fill="none" stroke="currentColor" ' +
+        'stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+        '<polyline points="4 17 10 11 4 5"/><line x1="12" y1="19" x2="20" y2="19"/></svg>';
+    const esc = (s) => s.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+    // Glyph tint: primary on success, danger on failure — everything else stays on-brand.
+    const glyphColorLight = ok ? "#1E4492" : "#dc2626";
+    const glyphColorDark = ok ? "#5a8fd8" : "#f2a4a0";
+    const glyphBgLight = ok ? "#EBF6FD" : "#fbeaea";
+    const glyphBgDark = ok ? "#0d1a2e" : "#3a1f1f";
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1"><title>Vincentt</title>
+<style>:root{color-scheme:light dark;--sand:#f5f9fd;--surface:#ffffff;--border:#dce8f2;
+--ink:#232528;--ui:#6e7178;--glyph:${glyphColorLight};--glyph-bg:${glyphBgLight};--shadow:0 10px 30px -12px rgba(30,68,146,.25)}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+font-family:"DM Sans",-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+background:var(--sand);color:var(--ink)}.card{width:min(92vw,420px);background:var(--surface);
+border:1px solid var(--border);border-radius:16px;padding:28px;box-shadow:var(--shadow)}
+.glyph{width:48px;height:48px;margin:0 0 16px;border-radius:16px;color:var(--glyph);
+background:var(--glyph-bg);display:flex;align-items:center;justify-content:center}
+h1{font-size:18px;font-weight:600;line-height:1.35;margin:0 0 8px;letter-spacing:-.01em}
+p{font-size:14px;line-height:1.5;color:var(--ui);margin:0}
+@media(prefers-color-scheme:dark){:root{--sand:#0f1114;--surface:#161920;--border:#262b33;
+--ink:#e8ecf0;--ui:#7a8290;--glyph:${glyphColorDark};--glyph-bg:${glyphBgDark};--shadow:0 10px 30px -12px rgba(0,0,0,.5)}}
+</style></head><body><div class="card"><div class="glyph">${glyph}</div>
+<h1>${esc(heading)}</h1><p>${esc(body)}</p></div></body></html>`;
+}
+/**
+ * Run the loopback + PKCE exchange, persist the PAT, and confirm identity via /me.
+ * Resolves with the confirmed identity + the config path; rejects with LoginTimeoutError
+ * or LoginCallbackError. NO token is written on any failure (the write only happens after
+ * a successful exchange).
+ */
+export async function runPkceLogin(opts) {
+    const backend = opts.backend ?? httpAuthBackend(opts.apiUrl);
+    const pickPort = opts.pickPort ?? getFreePort;
+    const openBrowser = opts.openBrowser ?? defaultOpenBrowser;
+    const saveToken = opts.saveToken ?? ((apiUrl, pat) => writeMachineConfig({ apiUrl, pat }));
+    const progress = opts.onProgress ?? (() => { });
+    const material = makePkceMaterial();
+    const port = await pickPort();
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const authUrl = buildCliAuthUrl(opts.consoleUrl, redirectUri, material);
+    // (4) await the loopback callback; verify state; hand back the auth_code.
+    const code = await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            // A received request always carries a url; the base makes it absolute for parsing.
+            const url = new URL(req.url, `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404, { "content-type": "text/plain" });
+                res.end("Not found");
+                return;
+            }
+            const result = parseCallback(url.searchParams, material.state);
+            res.writeHead(result.ok ? 200 : 400, {
+                "content-type": "text/html; charset=utf-8",
+            });
+            res.end(result.ok
+                ? browserPage(true, "You're all set", "Return to your terminal — you can close this tab.")
+                : browserPage(false, "Sign-in failed", result.message));
+            if (result.ok) {
+                server.close();
+                resolve(result.code);
+            }
+            else if (result.reason !== "state_mismatch") {
+                // A cancel is a real, terminal failure. A state mismatch is a stray/forged
+                // callback — answer it but keep waiting for the genuine one (or the timeout).
+                server.close();
+                reject(new LoginCallbackError(result.message));
+            }
+        });
+        server.on("error", reject);
+        // (1) listener up FIRST; only then (3) open the browser + print the fallback.
+        server.listen(port, "127.0.0.1", () => {
+            progress("→ Opening your browser to sign in…");
+            progress(`  If it doesn't open, visit: ${authUrl}`);
+            progress("");
+            progress("  Waiting for you to approve access in the browser…");
+            openBrowser(authUrl);
+        });
+        const timer = setTimeout(() => {
+            server.close();
+            reject(new LoginTimeoutError());
+        }, opts.timeoutMs ?? 5 * 60_000);
+        timer.unref();
+    });
+    // (5) redeem the code for the raw PAT; (6) persist then confirm identity.
+    const pat = await backend.exchange(code, material.codeVerifier);
+    const configPath = await saveToken(opts.apiUrl.replace(/\/$/, ""), pat);
+    const identity = await backend.me(pat);
+    return { identity, configPath };
+}

package/dist/mcp/server.js

@@ -35,11 +35,23 @@ async function guard(run) {
 export async function shutdownActivePreview() {
     await previewStop();
 }
+// An MCP tool description is NOT documentation — it is the routing logic the
+// agent executes. The shipped `viewer` text sent an agent asked about "this
+// tester's phone" to the coordinate that churns, and the word doing the damage
+// was "device". It stays out of both descriptions below.
+//
+// There is no `sessionId` parameter. It took the raw client-supplied key, which
+// made a free-form string an agent could be talked into echoing the same leak
+// from the other direction.
 const sharedInput = {
-    sessionId: z
+    tester: z
         .string()
         .optional()
-        .describe("Filter to one preview session (phone). Omit for all."),
+        .describe("Filter to ONE tester, e.g. `t1`. THIS IS THE FILTER YOU WANT for 'it breaks on their phone but not mine': a tester is one browser tab, recognised across refreshes, so it still resolves after the tester reloads — which they will have done before reporting the bug. Several testers normally share one preview and a merged stream is not debuggable. The ids currently connected are listed at the top of any unfiltered result."),
+    viewer: z
+        .string()
+        .optional()
+        .describe("Filter to ONE connection, e.g. `viewer-2`. This is the SUB-COORDINATE below `tester` and is rarely what you want: a single tab opens several connections, so this shows a fraction of one tester's traffic. A label identifies a CONNECTION, not a person; one that reconnects gets a new label and the old one is never reused. Use `tester` unless you are debugging a specific connection."),
     since: z
         .number()
         .optional()
@@ -68,38 +80,38 @@ export function createHarnessMcp(opts = {}) {
             ...sharedInput,
             errorsOnly: z.boolean().optional().describe("Return only error-level logs."),
         },
-    }, async ({ sessionId, since, limit, errorsOnly }) => ({
+    }, async ({ tester, viewer, since, limit, errorsOnly }) => ({
         content: [
             {
                 type: "text",
-                text: await diagRead(baseProjectDir, "log", { sessionId, since, limit, errorsOnly }, relayClient, now),
+                text: await diagRead(baseProjectDir, "log", { tester, viewer, since, limit, errorsOnly }, relayClient, now),
             },
         ],
     }));
     server.registerTool("diag_network", {
         description: "Read fetch/XHR requests the preview app made on the device (method, URL, status, duration). Use to find failed asset loads or slow calls without DevTools.",
         inputSchema: sharedInput,
-    }, async ({ sessionId, since, limit }) => ({
+    }, async ({ tester, viewer, since, limit }) => ({
         content: [
             {
                 type: "text",
-                text: await diagRead(baseProjectDir, "network", { sessionId, since, limit }, relayClient, now),
+                text: await diagRead(baseProjectDir, "network", { tester, viewer, since, limit }, relayClient, now),
             },
         ],
     }));
     server.registerTool("diag_trace", {
         description: "Read performance samples from the device (fps, longest main-thread task, long-task count, phase marks). Replaces hand-exporting a DevTools trace to spot jank.",
         inputSchema: sharedInput,
-    }, async ({ sessionId, since, limit }) => ({
+    }, async ({ tester, viewer, since, limit }) => ({
         content: [
             {
                 type: "text",
-                text: await diagRead(baseProjectDir, "trace", { sessionId, since, limit }, relayClient, now),
+                text: await diagRead(baseProjectDir, "trace", { tester, viewer, since, limit }, relayClient, now),
             },
         ],
     }));
     server.registerTool("project_create", {
-        description: "Create a Vincentt project this working directory publishes to. If the directory has no app yet, it scaffolds the v2-template starter into it (like GitHub's Use-this-template); then it writes a local .vincentt/project.json binding and reserves <slug>.vincentt.app. Ask the user for a project name AND a slug before calling; pass what they give. Omit either to accept a default — name = folder name, slug = a platform-assigned catchy one. The slug is the permanent public subdomain (locked once published), so confirm it with the user. Run once per new app; publish with project_publish to go live.",
+        description: "Register a Vincentt project for this working directory and reserve its <slug>.vincentt.app address, then write the local .vincentt/project.json binding. This does NOT scaffold an app — run `vincentt init` first for that (it needs no account). Ask the user for a project name AND an address before calling; pass what they give. The address is never auto-assigned: if it is taken, this returns suggestions and creates nothing, so re-ask the user rather than picking one. The address is permanent once published. Run once per new app; publish with project_publish to go live.",
         inputSchema: {
             name: z
                 .string()
@@ -108,18 +120,23 @@ export function createHarnessMcp(opts = {}) {
             slug: z
                 .string()
                 .optional()
-                .describe("Desired subdomain slug (<slug>.vincentt.app), lowercase kebab-case. Omit to let the platform assign one. Permanent once published."),
-            scaffold: z
+                .describe("Desired address (<slug>.vincentt.app), lowercase kebab-case. Defaults to one derived from the name. Never auto-assigned on a collision. Permanent once published."),
+            org: z
+                .string()
+                .optional()
+                .describe("Slug of the organization to create the project in. Defaults to the user's active org."),
+            force: z
                 .boolean()
                 .optional()
-                .describe("Whether to scaffold the v2-template starter when the directory has no app. Defaults to true; set false to bind an existing/empty directory without cloning."),
+                .describe("Replace a binding this folder already has."),
             ...projectDirInput,
         },
-    }, async ({ name, slug, scaffold, projectDir }) => guard(async () => {
+    }, async ({ name, slug, org, force, projectDir }) => guard(async () => {
         const result = await projectCreate(resolveProjectDir(baseProjectDir, projectDir), {
             name,
             slug,
-            scaffold,
+            org,
+            force,
         });
         return result.message;
     }));
@@ -130,7 +147,10 @@ export function createHarnessMcp(opts = {}) {
                 .string()
                 .optional()
                 .describe("Path to the built dist directory, relative to the project (default: dist)."),
-            note: z.string().optional().describe("Optional release note recorded with the version."),
+            note: z
+                .string()
+                .optional()
+                .describe("Optional release note recorded with the version."),
             ...projectDirInput,
         },
     }, async ({ distDir, note, projectDir }) => guard(async () => {
@@ -141,7 +161,7 @@ export function createHarnessMcp(opts = {}) {
         return result.message;
     }));
     server.registerTool("preview_start", {
-        description: "Start a live on-device preview: serves the app, opens a public https tunnel, and wires the diagnostics relay so diag_logs/diag_network/diag_trace read from the connected device. Returns the URL to open on a phone. Requires a project_create binding; cloudflared is auto-provisioned if missing. One preview at a time — call preview_stop before starting another. The dev server keeps running until preview_stop, so start it once and iterate.",
+        description: "Start a live on-device preview: serves the app at an https link a phone can open, and wires the diagnostics relay so diag_logs/diag_network/diag_trace read from the connected devices. Returns the URL to open on a phone — no sign-in is needed on the phone, and several devices can open the same link at once. Requires a project_create binding and a signed-in account. The link is temporary: it stops working when the preview stops, and at a 12-hour maximum. One preview at a time per folder — call preview_stop before starting another. The dev server keeps running until preview_stop, so start it once and iterate.",
         inputSchema: { ...projectDirInput },
     }, async ({ projectDir }) => guard(async () => {
         if (getActivePreview()) {
@@ -154,19 +174,26 @@ export function createHarnessMcp(opts = {}) {
         const readiness = preview.appReady
             ? ""
             : `\nNote: the app on :${preview.appPort} isn't responding yet — the URL may be blank until its build finishes. Check diag_logs.`;
-        return (`Live preview running — open on your device:\n${preview.url}\n\n` +
-            `Diagnostics are live: diag_logs / diag_network / diag_trace now read from this device.\n` +
+        return (`Preview is live — open this on a device:\n${preview.url}\n\n` +
+            `No sign-in is needed on the phone, and several devices can open it at once.\n` +
+            `Diagnostics are live: diag_logs / diag_network / diag_trace read from the\n` +
+            `connected devices; pass \`tester\` to filter to one tester's stream.\n` +
+            // The GRANT, the session id and the edge hostname are absent, and stay
+            // absent. This text lands verbatim in an agent's transcript, which is
+            // exactly why f1's "a token is never printed" extends to grants.
+            `The link is temporary and stops working at ${preview.expiresAt}.\n` +
             `Call preview_stop when finished.${readiness}`);
     }));
     server.registerTool("preview_stop", {
-        description: "Stop the running preview: tears down the tunnel (and its DNS route), the app dev server, and the diagnostics relay. Safe to call when nothing is running.",
+        description: "Stop the running preview: ends the session, closes the tunnel, and tears down the app dev server and the diagnostics relay. The link stops working immediately. Safe to call when nothing is running.",
         inputSchema: {},
     }, async () => guard(async () => {
         const stopped = await previewStop();
         if (!stopped)
             return "No preview is running.";
         // The preview's relay is gone; send diag reads back to the default.
-        relayClient = opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
+        relayClient =
+            opts.relay ?? httpRelayClient(opts.relayUrl ?? "http://localhost:7331");
         return "Preview stopped. Tunnel and dev server torn down.";
     }));
     return server;