@wenrwa/marketplace-cli 0.8.7 → 0.8.9

package/dist/bridge/previewForwarder.d.ts

@@ -0,0 +1,116 @@
+/**
+ * tp-06 (docs/prd/team-preview.md module 4, ADR-0014) — the Team preview
+ * forwarder: the tenant boundary between the shared preview gateway and the
+ * owner's machine.
+ *
+ * Members reach the owner's running `main` only through the preview gateway
+ * (a shared Fly app). The gateway dials this machine over Fly's private
+ * network (6PN), which is organisation-wide: every user's machine can reach
+ * every other user's machine over it. So this module:
+ *
+ *   - listens on ONE port, on the machine's own 6PN address (never a
+ *     wildcard), and
+ *   - forwards a connection ONLY when it comes from the gateway's address
+ *     (configured as an address or a `.internal` name, resolved and pinned),
+ *   - and ONLY to `127.0.0.1:<preview port>` — the port the tp-05 preview
+ *     checkout serves on. The target is fixed at construction; nothing a
+ *     peer sends can choose another port.
+ *
+ * Every other connection is destroyed before a byte is read from it. HTTP and
+ * WebSocket upgrades both pass, because this is a plain TCP pipe.
+ *
+ * Modelled on bws-08's companionForwarder.ts, with the same crash discipline:
+ * nothing here may throw synchronously, emit an unhandled 'error', or reject
+ * unhandled into the bridge's crash handlers (installBridgeCrashHandlers,
+ * twr-05).
+ *
+ * TWO-LANE (ADR-0014): hosted only. The local bridge must never open this
+ * listener — a laptop has no 6PN address and opening it to outside traffic
+ * would expose the laptop. buildPreviewForwarder returns a no-op whenever
+ * there is no `fly-local-6pn` entry, and it is only ever called from the
+ * container (`--relay`) branch of commands/bridge.ts.
+ */
+import * as net from 'net';
+/** The fixed port the preview app serves on, on 127.0.0.1 only (tp-05 starts
+ *  the preview's `start` script with this PORT). Distinct from the usual dev
+ *  ports so it never collides with the owner's own dev server. */
+export declare const PREVIEW_PORT_DEFAULT = 4800;
+/** The port the forwarder listens on, on the machine's 6PN address. The
+ *  gateway (tp-08 `target`, tp-10) dials `[<6pn>]:<this>`. */
+export declare const PREVIEW_FORWARDER_PORT_DEFAULT = 4801;
+/** How often a `.internal` gateway name is re-resolved. Between refreshes the
+ *  allowlist is pinned: no DNS lookup ever happens per connection. */
+export declare const PREVIEW_GATEWAY_REFRESH_MS_DEFAULT: number;
+export interface PreviewPorts {
+    previewPort: number;
+    forwarderPort: number;
+}
+/** Env knobs `HT_PREVIEW_PORT` / `HT_PREVIEW_FORWARDER_PORT`. The forwarder
+ *  never shares the preview port: a preview app that (wrongly) binds a
+ *  wildcard address would otherwise make the bind fail. */
+export declare function resolvePreviewPorts(env?: Record<string, string | undefined>): PreviewPorts;
+/**
+ * One canonical spelling per IP so the allowlist compare can't be dodged by
+ * formatting: IPv4 as dotted quad, IPv6 fully expanded to eight lower-case
+ * 4-digit groups. An IPv4-mapped IPv6 peer (`::ffff:1.2.3.4`) is unwrapped to
+ * its IPv4 form, and a zone id (`%eth0`) is dropped. Anything that isn't an
+ * IP (a host name, garbage) → null, which never matches.
+ */
+export declare function canonicalAddress(addr: string | null | undefined): string | null;
+export type GatewayLookup = (name: string) => Promise<string[]>;
+export interface PreviewForwarderDeps {
+    /** The machine's own 6PN address in production (`fly-local-6pn`); `::1`
+     *  or `::` in tests. Never a wildcard in production. */
+    listenHost: string;
+    /** 0 picks an ephemeral port (tests only). */
+    listenPort: number;
+    /** The ONE port anything is ever forwarded to, always on 127.0.0.1. */
+    targetPort: number;
+    /** The gateway: IP addresses and/or names (a Fly `.internal` name). Names
+     *  are resolved at start() and pinned; see refreshMs. */
+    allowed: string[];
+    lookup?: GatewayLookup;
+    /** Re-resolve names this often (a gateway machine replaced by a deploy gets
+     *  a new 6PN address). A failed refresh keeps the pinned set. */
+    refreshMs?: number;
+    setIntervalFn?: (cb: () => void, ms: number) => unknown;
+    clearIntervalFn?: (handle: unknown) => void;
+    net?: Pick<typeof net, 'createServer' | 'createConnection'>;
+    /** Reads the peer address off an accepted socket. Injectable so loopback
+     *  tests can play a 6PN peer. Default: `socket.remoteAddress`. */
+    remoteAddressOf?: (socket: net.Socket) => string | undefined;
+    onBindError?: (err: Error) => void;
+    onResolveError?: (name: string, err: Error) => void;
+}
+export interface PreviewForwarder {
+    /** Resolves the allowlist, then binds. Resolves once listening (or once a
+     *  bind error was reported). Never rejects. */
+    start(): Promise<void>;
+    /** Closes the listener and stops refreshing. Safe to call more than once. */
+    stop(): void;
+    /** The bound port, or null when not listening. */
+    port(): number | null;
+    /** The pinned allowlist, canonical spellings. */
+    allowedAddresses(): string[];
+}
+export declare function createPreviewForwarder(deps: PreviewForwarderDeps): PreviewForwarder;
+/** Same interface, zero behaviour — the local lane and unconfigured boxes. */
+export declare function createNoopPreviewForwarder(): PreviewForwarder;
+export interface BuildPreviewForwarderOpts {
+    env?: Record<string, string | undefined>;
+    /** Reads /etc/hosts. Throwing (no such file) means "not a Fly machine". */
+    readHosts: () => string;
+    net?: Pick<typeof net, 'createServer' | 'createConnection'>;
+    lookup?: GatewayLookup;
+    log?: (...args: unknown[]) => void;
+}
+/**
+ * The one place the lane decision is made. A real forwarder only when BOTH:
+ *   - this is a Fly machine (`fly-local-6pn` in /etc/hosts) — the local
+ *     bridge never has one, so it never binds (ADR-0014: Team preview is
+ *     hosted-only; a laptop must not be opened to outside traffic), and
+ *   - `HT_PREVIEW_GATEWAY` names the gateway (comma-separated addresses or
+ *     `.internal` names). Unset = off: the feature stays inert until the
+ *     gateway exists (tp-11) and the image is released (tp-12).
+ */
+export declare function buildPreviewForwarder(opts: BuildPreviewForwarderOpts): PreviewForwarder;

package/dist/bridge/previewForwarder.js

@@ -0,0 +1,323 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_GATEWAY_REFRESH_MS_DEFAULT = exports.PREVIEW_FORWARDER_PORT_DEFAULT = exports.PREVIEW_PORT_DEFAULT = void 0;
+exports.resolvePreviewPorts = resolvePreviewPorts;
+exports.canonicalAddress = canonicalAddress;
+exports.createPreviewForwarder = createPreviewForwarder;
+exports.createNoopPreviewForwarder = createNoopPreviewForwarder;
+exports.buildPreviewForwarder = buildPreviewForwarder;
+/**
+ * tp-06 (docs/prd/team-preview.md module 4, ADR-0014) — the Team preview
+ * forwarder: the tenant boundary between the shared preview gateway and the
+ * owner's machine.
+ *
+ * Members reach the owner's running `main` only through the preview gateway
+ * (a shared Fly app). The gateway dials this machine over Fly's private
+ * network (6PN), which is organisation-wide: every user's machine can reach
+ * every other user's machine over it. So this module:
+ *
+ *   - listens on ONE port, on the machine's own 6PN address (never a
+ *     wildcard), and
+ *   - forwards a connection ONLY when it comes from the gateway's address
+ *     (configured as an address or a `.internal` name, resolved and pinned),
+ *   - and ONLY to `127.0.0.1:<preview port>` — the port the tp-05 preview
+ *     checkout serves on. The target is fixed at construction; nothing a
+ *     peer sends can choose another port.
+ *
+ * Every other connection is destroyed before a byte is read from it. HTTP and
+ * WebSocket upgrades both pass, because this is a plain TCP pipe.
+ *
+ * Modelled on bws-08's companionForwarder.ts, with the same crash discipline:
+ * nothing here may throw synchronously, emit an unhandled 'error', or reject
+ * unhandled into the bridge's crash handlers (installBridgeCrashHandlers,
+ * twr-05).
+ *
+ * TWO-LANE (ADR-0014): hosted only. The local bridge must never open this
+ * listener — a laptop has no 6PN address and opening it to outside traffic
+ * would expose the laptop. buildPreviewForwarder returns a no-op whenever
+ * there is no `fly-local-6pn` entry, and it is only ever called from the
+ * container (`--relay`) branch of commands/bridge.ts.
+ */
+const net = __importStar(require("net"));
+const dns = __importStar(require("dns"));
+const companionForwarder_1 = require("./companionForwarder");
+/** The fixed port the preview app serves on, on 127.0.0.1 only (tp-05 starts
+ *  the preview's `start` script with this PORT). Distinct from the usual dev
+ *  ports so it never collides with the owner's own dev server. */
+exports.PREVIEW_PORT_DEFAULT = 4800;
+/** The port the forwarder listens on, on the machine's 6PN address. The
+ *  gateway (tp-08 `target`, tp-10) dials `[<6pn>]:<this>`. */
+exports.PREVIEW_FORWARDER_PORT_DEFAULT = 4801;
+/** How often a `.internal` gateway name is re-resolved. Between refreshes the
+ *  allowlist is pinned: no DNS lookup ever happens per connection. */
+exports.PREVIEW_GATEWAY_REFRESH_MS_DEFAULT = 5 * 60_000;
+function parsePort(raw) {
+    if (!raw)
+        return null;
+    const n = Number(raw.trim());
+    return Number.isInteger(n) && n > 0 && n < 65536 ? n : null;
+}
+/** Env knobs `HT_PREVIEW_PORT` / `HT_PREVIEW_FORWARDER_PORT`. The forwarder
+ *  never shares the preview port: a preview app that (wrongly) binds a
+ *  wildcard address would otherwise make the bind fail. */
+function resolvePreviewPorts(env = process.env) {
+    const previewPort = parsePort(env.HT_PREVIEW_PORT) ?? exports.PREVIEW_PORT_DEFAULT;
+    let forwarderPort = parsePort(env.HT_PREVIEW_FORWARDER_PORT) ?? exports.PREVIEW_FORWARDER_PORT_DEFAULT;
+    if (forwarderPort === previewPort)
+        forwarderPort = exports.PREVIEW_FORWARDER_PORT_DEFAULT;
+    return { previewPort, forwarderPort };
+}
+/**
+ * One canonical spelling per IP so the allowlist compare can't be dodged by
+ * formatting: IPv4 as dotted quad, IPv6 fully expanded to eight lower-case
+ * 4-digit groups. An IPv4-mapped IPv6 peer (`::ffff:1.2.3.4`) is unwrapped to
+ * its IPv4 form, and a zone id (`%eth0`) is dropped. Anything that isn't an
+ * IP (a host name, garbage) → null, which never matches.
+ */
+function canonicalAddress(addr) {
+    if (!addr)
+        return null;
+    let a = addr.trim().toLowerCase();
+    const zone = a.indexOf('%');
+    if (zone >= 0)
+        a = a.slice(0, zone);
+    if (a.startsWith('::ffff:') && net.isIPv4(a.slice(7)))
+        a = a.slice(7);
+    if (net.isIPv4(a))
+        return a;
+    if (!net.isIPv6(a))
+        return null;
+    // Turn an embedded IPv4 tail (e.g. `64:ff9b::1.2.3.4`) into two hex groups.
+    const lastColon = a.lastIndexOf(':');
+    const tail = a.slice(lastColon + 1);
+    if (net.isIPv4(tail)) {
+        const [b0, b1, b2, b3] = tail.split('.').map(Number);
+        a = `${a.slice(0, lastColon + 1)}${((b0 << 8) | b1).toString(16)}:${((b2 << 8) | b3).toString(16)}`;
+    }
+    const [head, rest] = a.includes('::') ? a.split('::') : [a, null];
+    const headGroups = head ? head.split(':') : [];
+    const restGroups = rest ? rest.split(':') : [];
+    const fill = rest === null ? [] : new Array(8 - headGroups.length - restGroups.length).fill('0');
+    const groups = [...headGroups, ...fill, ...restGroups];
+    if (groups.length !== 8)
+        return null;
+    return groups.map((g) => g.padStart(4, '0')).join(':');
+}
+const defaultLookup = async (name) => {
+    const results = await dns.promises.lookup(name, { all: true });
+    return results.map((r) => r.address);
+};
+function createPreviewForwarder(deps) {
+    const netImpl = deps.net ?? net;
+    const lookup = deps.lookup ?? defaultLookup;
+    const scheduleInterval = deps.setIntervalFn ?? ((cb, ms) => setInterval(cb, ms));
+    const cancelInterval = deps.clearIntervalFn ?? ((h) => clearInterval(h));
+    const remoteAddressOf = deps.remoteAddressOf ?? ((s) => s.remoteAddress);
+    // Fixed here, once: the only destination this module can ever dial.
+    const TARGET = Object.freeze({ host: '127.0.0.1', port: deps.targetPort });
+    const literal = new Set();
+    const names = [];
+    for (const entry of deps.allowed) {
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        const c = canonicalAddress(trimmed);
+        if (c)
+            literal.add(c);
+        else
+            names.push(trimmed);
+    }
+    // The pinned per-name resolutions. Empty until resolved: fail closed.
+    const resolved = new Map();
+    let allowSet = new Set(literal);
+    const rebuild = () => {
+        const next = new Set(literal);
+        for (const set of resolved.values())
+            for (const a of set)
+                next.add(a);
+        allowSet = next;
+    };
+    let server = null;
+    let refreshHandle = null;
+    let stopped = false;
+    const resolveNames = async () => {
+        await Promise.all(names.map(async (name) => {
+            try {
+                const addrs = (await lookup(name)).map(canonicalAddress).filter((a) => !!a);
+                if (addrs.length > 0)
+                    resolved.set(name, new Set(addrs));
+            }
+            catch (err) {
+                // Keep whatever was pinned before (nothing, on the first try).
+                deps.onResolveError?.(name, err instanceof Error ? err : new Error(String(err)));
+            }
+        }));
+        rebuild();
+    };
+    const onConnection = (socket) => {
+        const remote = canonicalAddress(remoteAddressOf(socket));
+        if (!remote || !allowSet.has(remote)) {
+            // THE tenant-boundary line. An accepted socket is paused, so destroying
+            // it here means a refused peer's bytes are never read.
+            socket.destroy();
+            return;
+        }
+        const upstream = netImpl.createConnection({ host: TARGET.host, port: TARGET.port });
+        const teardown = () => {
+            socket.destroy();
+            upstream.destroy();
+        };
+        // Both legs need an 'error' listener: an unhandled one would throw into
+        // the bridge's crash handlers (a preview that's mid-restart is an
+        // ordinary ECONNREFUSED, not a crash).
+        socket.on('error', teardown);
+        upstream.on('error', teardown);
+        socket.pipe(upstream);
+        upstream.pipe(socket);
+    };
+    const bind = () => new Promise((resolve) => {
+        let s;
+        try {
+            s = netImpl.createServer(onConnection);
+        }
+        catch (err) {
+            deps.onBindError?.(err instanceof Error ? err : new Error(String(err)));
+            resolve();
+            return;
+        }
+        server = s;
+        s.on('error', (err) => {
+            // Bind failures (EADDRINUSE, EADDRNOTAVAIL) arrive here, async.
+            if (server === s)
+                server = null;
+            deps.onBindError?.(err);
+            resolve();
+        });
+        s.listen(deps.listenPort, deps.listenHost, () => resolve());
+    });
+    return {
+        async start() {
+            if (stopped || server)
+                return;
+            await resolveNames();
+            if (stopped)
+                return;
+            if (names.length > 0 && refreshHandle === null) {
+                refreshHandle = scheduleInterval(() => {
+                    void resolveNames();
+                }, deps.refreshMs ?? exports.PREVIEW_GATEWAY_REFRESH_MS_DEFAULT);
+                refreshHandle?.unref?.();
+            }
+            await bind();
+        },
+        stop() {
+            stopped = true;
+            if (refreshHandle !== null) {
+                cancelInterval(refreshHandle);
+                refreshHandle = null;
+            }
+            const s = server;
+            server = null;
+            if (s) {
+                try {
+                    s.close();
+                }
+                catch {
+                    // already closed
+                }
+            }
+        },
+        port() {
+            const addr = server?.address();
+            return addr && typeof addr === 'object' ? addr.port : null;
+        },
+        allowedAddresses() {
+            return Array.from(allowSet);
+        },
+    };
+}
+/** Same interface, zero behaviour — the local lane and unconfigured boxes. */
+function createNoopPreviewForwarder() {
+    return {
+        start: async () => { },
+        stop: () => { },
+        port: () => null,
+        allowedAddresses: () => [],
+    };
+}
+/**
+ * The one place the lane decision is made. A real forwarder only when BOTH:
+ *   - this is a Fly machine (`fly-local-6pn` in /etc/hosts) — the local
+ *     bridge never has one, so it never binds (ADR-0014: Team preview is
+ *     hosted-only; a laptop must not be opened to outside traffic), and
+ *   - `HT_PREVIEW_GATEWAY` names the gateway (comma-separated addresses or
+ *     `.internal` names). Unset = off: the feature stays inert until the
+ *     gateway exists (tp-11) and the image is released (tp-12).
+ */
+function buildPreviewForwarder(opts) {
+    const env = opts.env ?? process.env;
+    const log = opts.log ?? console.log;
+    let listenHost = null;
+    try {
+        listenHost = (0, companionForwarder_1.resolveFlyLocal6pnHost)(opts.readHosts());
+    }
+    catch {
+        listenHost = null;
+    }
+    if (!listenHost) {
+        log('[bridge] preview forwarder off: not a hosted machine (ADR-0014)');
+        return createNoopPreviewForwarder();
+    }
+    const allowed = (env.HT_PREVIEW_GATEWAY || '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (allowed.length === 0) {
+        log('[bridge] preview forwarder off: HT_PREVIEW_GATEWAY not set');
+        return createNoopPreviewForwarder();
+    }
+    const { previewPort, forwarderPort } = resolvePreviewPorts(env);
+    return createPreviewForwarder({
+        listenHost,
+        listenPort: forwarderPort,
+        targetPort: previewPort,
+        allowed,
+        lookup: opts.lookup,
+        net: opts.net,
+        onBindError: (err) => console.error(`[bridge] preview forwarder: failed to bind ${forwarderPort} on ${listenHost}:`, err.message),
+        onResolveError: (name, err) => console.error(`[bridge] preview forwarder: cannot resolve ${name}:`, err.message),
+    });
+}

package/dist/bridge/previewFrames.d.ts

@@ -0,0 +1,63 @@
+/**
+ * tp-05 — the Team preview relay frames (docs/prd/team-preview.md module 5).
+ *
+ * Server → bridge, each correlated by `requestId` (the `ensure-checkout`
+ * pattern). Workspace-addressed, open NO PTY, so — like `ensure-checkout` —
+ * they are absent from SESSION_ADDRESSED_FRAMES. None carries a branch: the
+ * preview is pinned to the remote's default branch (ADR-0014).
+ *
+ *   preview-start  { requestId, workspaceId, repoUrl?, gitCredential?, mode? }
+ *   preview-update { requestId, workspaceId, repoUrl?, gitCredential?, mode? }
+ *   preview-stop   { requestId, workspaceId }
+ *   preview-logs   { requestId, workspaceId }
+ *
+ * Bridge → server:
+ *   preview-result       { requestId, workspaceId, phase, ok, status, … }
+ *     start/update answer `phase: 'accepted'` at once (a build takes minutes;
+ *     the backend must not hold a request open for it), then `phase: 'done'`
+ *     with the outcome. stop answers `done` only.
+ *   preview-logs-result  { requestId, workspaceId, ok, log, truncated }
+ *
+ * LOCAL LANE — scoped out in writing (ADR-0014, two-lane rule). A laptop's
+ * bridge listens only on the laptop, laptops sleep, and reaching one from the
+ * gateway would mean opening it to the internet. So every preview frame that
+ * reaches a local bridge (its `--crew-relay` dial) gets the typed answer
+ * `{ error: 'unsupported', reason: 'local_lane' }` — never a silent drop the
+ * backend would have to time out on.
+ */
+import type { PreviewMode, PreviewRunner } from './previewCheckout';
+export declare const PREVIEW_FRAME_TYPES: ReadonlySet<string>;
+export type PreviewFrame = {
+    t: 'preview-start' | 'preview-update';
+    requestId: string;
+    workspaceId: string;
+    repoUrl?: string;
+    gitCredential?: {
+        token: string;
+        repoFullName?: string;
+        expiresAt?: string;
+    };
+    mode?: PreviewMode;
+} | {
+    t: 'preview-stop' | 'preview-logs';
+    requestId: string;
+    workspaceId: string;
+};
+export type PreviewLane = 
+/** The hosted container's bridge with a runner wired. */
+{
+    kind: 'hosted';
+    runner: PreviewRunner;
+}
+/** A laptop bridge (ADR-0014: out of scope). */
+ | {
+    kind: 'local';
+}
+/** A hosted bridge that has no runner (should not happen once wired). */
+ | {
+    kind: 'none';
+};
+type Send = (frame: Record<string, unknown>) => void;
+/** Answer one preview frame. Never throws; every path sends a typed reply. */
+export declare function handlePreviewFrame(frame: PreviewFrame, lane: PreviewLane, send: Send): void;
+export {};

package/dist/bridge/previewFrames.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREVIEW_FRAME_TYPES = void 0;
+exports.handlePreviewFrame = handlePreviewFrame;
+exports.PREVIEW_FRAME_TYPES = new Set([
+    'preview-start',
+    'preview-update',
+    'preview-stop',
+    'preview-logs',
+]);
+function replyType(t) {
+    return t === 'preview-logs' ? 'preview-logs-result' : 'preview-result';
+}
+function resultFrame(requestId, phase, r) {
+    const ok = r.status === 'running' || r.status === 'stopped' || r.status === 'building';
+    return { t: 'preview-result', requestId, phase, ok, ...r };
+}
+/** Answer one preview frame. Never throws; every path sends a typed reply. */
+function handlePreviewFrame(frame, lane, send) {
+    const { requestId, workspaceId } = frame;
+    const t = replyType(frame.t);
+    if (lane.kind === 'local') {
+        // ADR-0014 — the local lane is out of scope; say so, typed.
+        send({ t, requestId, workspaceId, ok: false, ...(t === 'preview-result' ? { phase: 'done' } : {}), error: 'unsupported', reason: 'local_lane' });
+        return;
+    }
+    if (lane.kind === 'none') {
+        send({ t, requestId, workspaceId, ok: false, ...(t === 'preview-result' ? { phase: 'done' } : {}), error: 'unsupported', reason: 'bridge-cannot-preview' });
+        return;
+    }
+    const { runner } = lane;
+    const failed = (err) => send({
+        t: 'preview-result', requestId, workspaceId, phase: 'done', ok: false, status: 'failed',
+        message: err instanceof Error ? err.message.slice(0, 200) : 'Preview failed.',
+    });
+    switch (frame.t) {
+        case 'preview-start':
+        case 'preview-update': {
+            const req = {
+                workspaceId,
+                repoUrl: frame.repoUrl,
+                gitCredential: frame.gitCredential,
+                mode: frame.mode === 'dev' ? 'dev' : frame.mode === 'built' ? 'built' : undefined,
+            };
+            send(resultFrame(requestId, 'accepted', { ...runner.status(workspaceId), status: 'building' }));
+            const op = frame.t === 'preview-start' ? runner.start(req) : runner.update(req);
+            op.then((r) => send(resultFrame(requestId, 'done', r)), failed);
+            return;
+        }
+        case 'preview-stop':
+            runner.stop({ workspaceId }).then((r) => send(resultFrame(requestId, 'done', r)), failed);
+            return;
+        case 'preview-logs': {
+            const { log, truncated } = runner.logs({ workspaceId });
+            send({ t: 'preview-logs-result', requestId, workspaceId, ok: true, log, truncated });
+            return;
+        }
+    }
+}

package/dist/bridge/relayClient.d.ts

@@ -10,6 +10,7 @@ import { GitRun } from './changesReporter';
 import { buildChangesReport as buildChangesReportReal } from './changesReport';
 import { CheckoutInventoryDeps } from './checkoutInventory';
 import type { CheckoutResult } from './repoCheckout';
+import type { PreviewRunner } from './previewCheckout';
 /**
  * fcct-27 — typed refusal when `resolveLaunch` names a binary this machine does
  * not have. Typed (like CONTAINER_MEMORY_EXHAUSTED) so the conductor renders a
@@ -144,6 +145,14 @@ export interface RelayClientOpts {
         repoUrl?: string;
         gitCredential?: InjectedGitCredential;
     }) => Promise<CheckoutResult>;
+    /**
+     * tp-05 — the Team preview runner (previewCheckout.ts). Wired on the HOSTED
+     * container bridge only. When `onlyRelayOwnedSessions` is set (a laptop's
+     * crew-relay dial) every preview frame is answered `unsupported /
+     * local_lane` regardless (ADR-0014 scopes the local lane out); absent on a
+     * hosted bridge → `unsupported / bridge-cannot-preview`.
+     */
+    preview?: PreviewRunner;
     /**
      * fcct-27 — what a relay-opened session actually SPAWNS.
      *
@@ -330,6 +339,12 @@ export interface RelayClientOpts {
         ok: false;
         reason: 'not-found' | 'invalid-agent-id' | 'too-large' | 'transcript-unavailable';
     };
+    /**
+     * tp-02 — resolve a workspace id to the checkout root whose `.env` names
+     * the Keys list shows (bridge.ts: `<reposBaseDir>/<workspaceId>`). Absent →
+     * an `env-names` frame gets a typed refusal, never a hang.
+     */
+    resolveEnvNamesRoot?: (workspaceId: string) => string | null | undefined;
     /** Injectable for tests: defaults to `new WebSocket(url)` from `ws`. */
     wsFactory?: (url: string) => WebSocketLike;
     backoff?: BackoffOpts;

package/dist/bridge/relayClient.js

@@ -114,6 +114,9 @@ const diskPreflight_1 = require("./diskPreflight");
 const checkoutParkAndRemove_1 = require("./checkoutParkAndRemove");
 const attachmentWriter_1 = require("./attachmentWriter");
 const envSaver_1 = require("./envSaver");
+const envNames_1 = require("./envNames");
+// tp-05 — Team preview frames (ADR-0014). See previewFrames.ts.
+const previewFrames_1 = require("./previewFrames");
 const PROTOCOL_VERSION = 1;
 /**
  * fcct-27 — typed refusal when `resolveLaunch` names a binary this machine does
@@ -1624,6 +1627,23 @@ function startRelayClient(opts) {
                             .catch(() => send(socket, { t: 'transcript-content', requestId, workspaceId, ok: false, reason: 'transcript-unavailable' }));
                         break;
                     }
+                    case 'env-names': {
+                        // tp-02: the NAMES in this workspace's `.env`, never a value —
+                        // envNames.ts parses on this machine and replies names only.
+                        // Never logged. requestId echoed so the backend can correlate.
+                        if (!opts.resolveEnvNamesRoot) {
+                            send(socket, {
+                                t: 'env-names-result',
+                                requestId: frame.requestId,
+                                workspaceId: frame.workspaceId,
+                                ok: false,
+                                reason: 'bridge-cannot-read-env-names',
+                            });
+                            break;
+                        }
+                        send(socket, (0, envNames_1.handleEnvNamesFrame)(frame, opts.resolveEnvNamesRoot));
+                        break;
+                    }
                     case 'browser-open': {
                         // cbs-02: a headless Chromium session, driven over CDP. This
                         // branch NEVER touches opts.sessions / SessionManager — a
@@ -1827,6 +1847,22 @@ function startRelayClient(opts) {
                         browserDrivers.get(frame.sessionId)?.resume().catch(() => { });
                         browserDrivers.get(frame.sessionId)?.reload().catch(() => { });
                         break;
+                    case 'preview-start':
+                    case 'preview-update':
+                    case 'preview-stop':
+                    case 'preview-logs':
+                        // tp-05 — ADR-0014: a laptop bridge (the crew-relay dial, the only
+                        // relay client with onlyRelayOwnedSessions) is the local lane, and
+                        // the local lane is out of scope — typed `unsupported`, never a drop.
+                        (0, previewFrames_1.handlePreviewFrame)(frame, opts.onlyRelayOwnedSessions
+                            ? { kind: 'local' }
+                            : opts.preview
+                                ? { kind: 'hosted', runner: opts.preview }
+                                : { kind: 'none' }, 
+                        // A build outlives a relay reconnect: answer on the LIVE socket,
+                        // not the one the request arrived on.
+                        (reply) => send(ws ?? socket, reply));
+                        break;
                     case 'companion-allow': {
                         // bws-08 — session-less tenant-boundary control frame (see
                         // companionFrames.ts's doc comment). Validated with the runtime

package/dist/bridge/server.d.ts

@@ -74,6 +74,13 @@ export interface BridgeServerOpts {
         ok: false;
         reason: 'not-found' | 'outside-root' | 'too-large' | 'binary' | 'conflict';
     } | null>;
+    /**
+     * tp-02 — resolve a REGISTERED local workspace id to its project folder, for
+     * GET /local-env-names/:workspaceId (the Keys list: `.env` names, never
+     * values — envNames.ts). null → 404 (not registered on this device). Its
+     * presence is what /discovery advertises as the `env-names` capability.
+     */
+    resolveEnvNamesRoot?: (workspaceId: string) => string | null | undefined;
     /** lws-05: the device name to advertise on /discovery (arena renders "✓
      *  Bridge connected — <device>"). Absent/null when the device is not yet
      *  registered — the modal falls back to a generic connected label. */