@wenrwa/marketplace-cli 0.4.4 → 0.4.6

package/dist/bridge/relayClient.js

@@ -0,0 +1,517 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assembleSessionEnv = assembleSessionEnv;
+exports.startRelayClient = startRelayClient;
+/**
+ * ht-05 — Terminal Bridge relay mode (dial-out).
+ *
+ * Instead of listening on localhost for browser connections (server.ts),
+ * this DIALS OUT to the platform relay over a single outbound wss
+ * connection, authenticates with a per-container relay token, and serves
+ * the same v1 frame protocol (see PROTOCOL.md) through the existing
+ * SessionManager. Multi-session multiplexing is unchanged: every frame
+ * already carries a sessionId, so one outbound socket serves every session
+ * exactly like the local server serves them over N inbound sockets.
+ *
+ * PTYs live in the SessionManager, not the socket — a relay drop never
+ * kills a session. This module owns only: dialing out, the auth frame,
+ * frame routing through SessionManager, and reconnect-with-backoff. It
+ * does no scrollback bookkeeping of its own (SessionManager already does
+ * that) — on re-pair the pane sends `attach` again and gets a fresh
+ * `replay`, exactly as it would against the local server.
+ */
+const ws_1 = require("ws");
+const activityParser_1 = require("./activityParser");
+const PROTOCOL_VERSION = 1;
+/**
+ * pucc-14 — assemble the per-session PTY env for a workspace-scoped `open`.
+ *
+ * Pure + exported so the env contract is unit-tested without a socket. Merges
+ * the relay-injected `env` (which already carries WENRWA_WORKSPACE_ID +
+ * WENRWA_CONNECT_TOKEN) and layers on:
+ *   - WENRWA_WORKSPACE_ID  — fallback if the relay didn't pre-set it in `env`.
+ *   - WENRWA_CONNECT_TOKEN — the workspace-bound Connect Token (MCP world-wiring).
+ *   - HT_AUTONOMOUS        — per-session: `claude` vs `claude --dangerously-skip-permissions`.
+ *   - WENRWA_GIT_TOKEN / WENRWA_GIT_REPO — the workspace git credential, read by
+ *     git-credential-wenrwa for clone-on-demand + in-terminal git (per-workspace,
+ *     no backend round-trip). The token rides the PTY env only; it is never
+ *     logged here.
+ */
+function assembleSessionEnv(frame) {
+    const env = { ...(frame.env ?? {}) };
+    if (frame.workspaceId)
+        env.WENRWA_WORKSPACE_ID = frame.workspaceId;
+    if (frame.connectToken)
+        env.WENRWA_CONNECT_TOKEN = frame.connectToken;
+    env.HT_AUTONOMOUS = frame.autonomous ? '1' : '0';
+    if (frame.gitCredential) {
+        env.WENRWA_GIT_TOKEN = frame.gitCredential.token;
+        env.WENRWA_GIT_REPO = frame.gitCredential.repoFullName;
+    }
+    return env;
+}
+function send(ws, frame) {
+    if (ws.readyState === ws_1.WebSocket.OPEN)
+        ws.send(JSON.stringify(frame));
+}
+function startRelayClient(opts) {
+    const backoff = {
+        initialMs: opts.backoff?.initialMs ?? 250,
+        maxMs: opts.backoff?.maxMs ?? 10_000,
+        factor: opts.backoff?.factor ?? 2,
+        jitter: opts.backoff?.jitter ?? Math.random,
+    };
+    const wsFactory = opts.wsFactory ?? ((url) => new ws_1.WebSocket(url));
+    const scheduleTimeout = opts.setTimeoutFn ?? ((cb, ms) => setTimeout(cb, ms));
+    const cancelTimeout = opts.clearTimeoutFn ?? ((h) => clearTimeout(h));
+    const scheduleInterval = opts.setIntervalFn ?? ((cb, ms) => setInterval(cb, ms));
+    const cancelInterval = opts.clearIntervalFn ?? ((h) => clearInterval(h));
+    // pucc-int-03 activity-tap config (enabled by default; the container bridge
+    // runs Claude Code, so observing its tool-use is the norm).
+    const activityEnabled = opts.emitActivity !== false;
+    const activityThrottleMs = opts.activityThrottleMs ?? 1000;
+    const now = opts.nowFn ?? Date.now;
+    let stopped = false;
+    let ws = null;
+    let connected = false;
+    let attempt = 0;
+    let reconnectHandle = null;
+    // cbs-02: browser session drivers, keyed by sessionId. Declared OUTSIDE
+    // connect() — like `opts.sessions` — so a running Chromium (and its
+    // frame/state subscriptions, registered once below) survives a relay
+    // drop/reconnect exactly like a PTY does; only PTY *attachment* is
+    // per-connection. Frame/state forwarders close over the outer `ws`/
+    // `connected` (not the per-connection `socket` local) so they always
+    // target whichever connection is current, the same pattern reportLogin
+    // already uses.
+    const browserDrivers = new Map();
+    // cbs-06: one idle tracker per LIVE browser driver, same lifetime rule as
+    // browserDrivers above (created alongside the driver on browser-open,
+    // torn down the instant the driver reaches ANY terminal state — asleep OR
+    // closed — so a resumed session always gets a fresh tracker too).
+    const browserIdleTrackers = new Map();
+    /** cbs-06: shared by the browser-sleep frame handler AND the idle
+     *  tracker's onIdle callback — both just mean "this driver goes to sleep
+     *  now," differing only in the reason string forwarded to the pane. A
+     *  safe no-op if no driver is open for this session (sleep-of-nothing, or
+     *  a session that already went asleep/closed and was removed from the map
+     *  by its own onState handler below). */
+    function sleepBrowserSession(sessionId, reason) {
+        browserDrivers.get(sessionId)?.sleep(reason);
+    }
+    // pucc-14 login_valid report. Container-level (not per session): the ONE
+    // shared login on the volume. `lastLoginValid` persists across reconnects so
+    // the poll only re-emits on a genuine change; each fresh connect force-emits
+    // so a restarted relay always relearns the current state.
+    let lastLoginValid = null;
+    let loginPollHandle = null;
+    function reportLogin(force) {
+        if (!opts.checkLoginValid)
+            return;
+        let valid;
+        try {
+            valid = opts.checkLoginValid();
+        }
+        catch {
+            return; // a read blip must never crash the bridge or drop a session
+        }
+        if (!force && valid === lastLoginValid)
+            return;
+        lastLoginValid = valid;
+        // BOOLEAN only — the credential value is never read here or sent.
+        if (ws && connected)
+            send(ws, { t: 'login-status', valid });
+    }
+    function nextDelay() {
+        const ceiling = Math.min(backoff.maxMs, backoff.initialMs * Math.pow(backoff.factor, attempt));
+        return ceiling * backoff.jitter(); // full jitter: uniform in [0, ceiling]
+    }
+    function scheduleReconnect() {
+        if (stopped)
+            return;
+        const delay = nextDelay();
+        attempt += 1;
+        opts.onReconnectScheduled?.(delay);
+        reconnectHandle = scheduleTimeout(() => connect(), delay);
+    }
+    function connect() {
+        if (stopped)
+            return;
+        const socket = wsFactory(opts.relayUrl);
+        ws = socket;
+        // Per-connection routing state. Recreated on every reconnect; the
+        // SessionManager (and its PTYs) is untouched across drops.
+        const handles = new Map();
+        // pucc-int-03: per-session activity observation state (parser + coalescing
+        // buffer). Keyed by sessionId, lives for the connection; a fresh connection
+        // starts clean. NEVER on the browser-forwarding path — see feedActivity.
+        const activity = new Map();
+        const attachTo = (sessionId) => {
+            const handle = opts.sessions.attach(sessionId, (frame) => {
+                if (frame.t === 'data') {
+                    // Browser forwarding FIRST and unaltered (the compliance-critical
+                    // stream). The activity tap is a strictly-additional read of the same
+                    // bytes — wrapped so nothing it does can disturb the pane.
+                    send(socket, { t: 'data', sessionId, data: frame.data });
+                    feedActivity(sessionId, frame.data);
+                }
+                else if (frame.t === 'takeover') {
+                    send(socket, { t: 'takeover', sessionId });
+                }
+            });
+            handles.set(sessionId, handle);
+            return handle;
+        };
+        // ── pucc-int-03: read-only PTY activity tap ──────────────────────────────
+        const flushActivity = (sessionId, st) => {
+            if (st.pendingPaths.size === 0 && st.pendingThinking === undefined)
+                return;
+            st.lastEmit = now();
+            const filePaths = [...st.pendingPaths];
+            const thinking = st.pendingThinking;
+            st.pendingPaths.clear();
+            st.pendingThinking = undefined;
+            // A separate `activity` frame — the relay intercepts it and never forwards
+            // it to the pane, so the browser stream is unaffected.
+            send(socket, {
+                t: 'activity',
+                sessionId,
+                ...(filePaths.length ? { filePaths } : {}),
+                ...(thinking !== undefined ? { thinking } : {}),
+            });
+        };
+        const feedActivity = (sessionId, data) => {
+            if (activityEnabled === false)
+                return;
+            try {
+                let st = activity.get(sessionId);
+                if (!st) {
+                    st = { parser: new activityParser_1.ActivityParser(), pendingPaths: new Set(), pendingThinking: undefined, lastEmit: 0, timer: null };
+                    activity.set(sessionId, st);
+                }
+                const signals = st.parser.push(data);
+                if (signals.length === 0)
+                    return;
+                for (const s of signals) {
+                    for (const p of s.filePaths)
+                        st.pendingPaths.add(p);
+                    if (s.thinking !== undefined)
+                        st.pendingThinking = s.thinking;
+                }
+                // Coalesce/throttle: emit at most once per throttle window per session.
+                const elapsed = now() - st.lastEmit;
+                if (elapsed >= activityThrottleMs) {
+                    flushActivity(sessionId, st);
+                }
+                else if (st.timer === null) {
+                    st.timer = scheduleTimeout(() => {
+                        const cur = activity.get(sessionId);
+                        if (cur) {
+                            cur.timer = null;
+                            flushActivity(sessionId, cur);
+                        }
+                    }, activityThrottleMs - elapsed);
+                }
+            }
+            catch {
+                // The observation tap must NEVER break the terminal (ADR-0032). Swallow.
+            }
+        };
+        const dropActivity = (sessionId) => {
+            const st = activity.get(sessionId);
+            if (st?.timer != null)
+                cancelTimeout(st.timer);
+            activity.delete(sessionId);
+        };
+        socket.on('open', () => {
+            send(socket, { v: PROTOCOL_VERSION, relayToken: opts.relayToken });
+            connected = true;
+            attempt = 0;
+            opts.onConnect?.();
+            // Force-emit the current login validity on every (re)connect so the relay
+            // — and any restarted relay — always has a fresh boolean.
+            reportLogin(true);
+        });
+        socket.on('message', (raw) => {
+            let frame;
+            try {
+                frame = JSON.parse(String(raw));
+            }
+            catch {
+                send(socket, { t: 'error', message: 'invalid frame' });
+                return;
+            }
+            if (!frame || !('t' in frame)) {
+                send(socket, { t: 'error', message: 'invalid frame' });
+                return;
+            }
+            try {
+                switch (frame.t) {
+                    case 'open': {
+                        // Capture into locals so the async .then closures below keep the
+                        // discriminated-union narrowing TS would otherwise drop.
+                        const { cols, rows, workspaceId, repoUrl, autonomous, connectToken, gitCredential } = frame;
+                        // pucc-14 multiplex: the RELAY owns the session id (== agentId) and
+                        // stamps it on the open + every later frame. Honor it so the PTY is
+                        // registered under exactly that id and container→pane frames demux
+                        // to the right pane across N concurrent sessions. Absent (legacy /
+                        // local) → SessionManager mints a random id, unchanged.
+                        const relaySessionId = frame.sessionId;
+                        const injectedEnv = frame.env;
+                        const openSession = (cwd, env) => {
+                            const sessionId = opts.sessions.open({ cols, rows, cwd, env, id: relaySessionId });
+                            attachTo(sessionId);
+                            send(socket, {
+                                t: 'opened',
+                                sessionId,
+                                ...(workspaceId ? { workspaceId } : {}),
+                                ...(cwd ? { cwd } : {}),
+                            });
+                        };
+                        if (workspaceId) {
+                            // pucc-04/14 contract: every workspace-scoped terminal carries its
+                            // workspace id, the workspace-bound Connect Token (MCP), the git
+                            // credential, and its autonomous toggle in the PTY env — so the
+                            // wenrwa MCP tools + git creds resolve per-workspace inside the
+                            // shared container. autolaunch.sh reads HT_AUTONOMOUS from the
+                            // PTY's own env (claude vs claude --dangerously-skip-permissions),
+                            // NOT a machine-wide var.
+                            const env = assembleSessionEnv({ workspaceId, autonomous, connectToken, gitCredential, env: injectedEnv });
+                            if (opts.resolveWorkspaceCwd) {
+                                opts
+                                    .resolveWorkspaceCwd({ workspaceId, repoUrl })
+                                    .then((cwd) => openSession(cwd ?? undefined, env))
+                                    .catch(() => openSession(undefined, env));
+                            }
+                            else {
+                                openSession(undefined, env);
+                            }
+                        }
+                        else {
+                            openSession();
+                        }
+                        break;
+                    }
+                    case 'attach': {
+                        const handle = attachTo(frame.sessionId);
+                        send(socket, { t: 'replay', sessionId: frame.sessionId, data: handle.replay });
+                        break;
+                    }
+                    case 'input':
+                        handles.get(frame.sessionId)?.write(frame.data);
+                        break;
+                    case 'resize':
+                        handles.get(frame.sessionId)?.resize(frame.cols, frame.rows);
+                        break;
+                    case 'detach':
+                        handles.get(frame.sessionId)?.detach();
+                        handles.delete(frame.sessionId);
+                        break;
+                    case 'close':
+                        handles.delete(frame.sessionId);
+                        dropActivity(frame.sessionId);
+                        opts.sessions.close(frame.sessionId);
+                        break;
+                    case 'install-bundle': {
+                        // pucc-int-04: write the forged crew `.claude` bundle into the
+                        // workspace checkout. No PTY, no crew engine — Claude Code reads the
+                        // files natively next run. The relay has already overridden
+                        // `workspaceId` with the token's authoritative value.
+                        if (!opts.installBundle) {
+                            send(socket, { t: 'error', message: 'install-bundle unsupported (no workspace checkouts)' });
+                            break;
+                        }
+                        const result = opts.installBundle({ workspaceId: frame.workspaceId, files: frame.files ?? {} });
+                        send(socket, {
+                            t: 'bundle-installed',
+                            workspaceId: frame.workspaceId,
+                            ...(frame.sessionId ? { sessionId: frame.sessionId } : {}),
+                            written: result?.written ?? [],
+                            skipped: result?.skipped ?? [],
+                        });
+                        break;
+                    }
+                    case 'context-manifest': {
+                        // pucc-int-01: write the arena-pushed file context into the
+                        // workspace's CLAUDE.md (a fenced managed region). No PTY, no
+                        // keystrokes — Claude Code reads the file natively (ADR-0028). The
+                        // relay has already overridden `workspaceId` with the token's value.
+                        if (!opts.writeContext) {
+                            send(socket, { t: 'error', message: 'context-manifest unsupported (no workspace checkouts)' });
+                            break;
+                        }
+                        const result = opts.writeContext({ workspaceId: frame.workspaceId, content: frame.content ?? '' });
+                        send(socket, {
+                            t: 'context-written',
+                            workspaceId: frame.workspaceId,
+                            ...(frame.sessionId ? { sessionId: frame.sessionId } : {}),
+                            ...(result && typeof result === 'object' ? { action: result.action } : {}),
+                        });
+                        break;
+                    }
+                    case 'browser-open': {
+                        // cbs-02: a headless Chromium session, driven over CDP. This
+                        // branch NEVER touches opts.sessions / SessionManager — a
+                        // browser session is not a PTY (PRD: "must never touch the PTY
+                        // session manager or spawn a shell").
+                        if (!opts.createBrowserDriver) {
+                            send(socket, { t: 'error', message: 'browser-open unsupported (no browser driver)' });
+                            break;
+                        }
+                        const sessionId = frame.sessionId;
+                        const url = frame.url;
+                        const existing = browserDrivers.get(sessionId);
+                        if (existing) {
+                            // "browser-open on an open session = navigate" (PRD decision)
+                            // — only ever true while the driver is actually live. A
+                            // driver that reached asleep OR closed is ALWAYS removed from
+                            // browserDrivers by its own onState handler below (cbs-06:
+                            // "a stopped driver must be replaced, not navigated"), so
+                            // `existing` here can never be a stopped driver.
+                            existing.navigate(url).catch((err) => {
+                                send(socket, { t: 'error', message: err instanceof Error ? err.message : 'browser navigate failed' });
+                            });
+                            break;
+                        }
+                        const driver = opts.createBrowserDriver({ sessionId });
+                        browserDrivers.set(sessionId, driver);
+                        // cbs-06: an idle tracker rides alongside the driver for its
+                        // whole live span. onIdle is wired to the SAME sleepBrowserSession
+                        // helper the browser-sleep frame uses, just with a different
+                        // reason string — the driver/pane see one uniform "went to
+                        // sleep" path either way.
+                        const idleTracker = opts.createBrowserIdleTracker?.({
+                            sessionId,
+                            onIdle: () => sleepBrowserSession(sessionId, 'idle-timeout'),
+                        }) ?? null;
+                        if (idleTracker) {
+                            browserIdleTrackers.set(sessionId, idleTracker);
+                            idleTracker.start();
+                        }
+                        // Registered ONCE per driver lifetime (not per connection) — see
+                        // the browserDrivers comment above for why these close over the
+                        // outer `ws`/`connected` rather than this connection's `socket`.
+                        driver.onFrame((f) => {
+                            if (ws && connected) {
+                                send(ws, { t: 'browser-frame', sessionId, seq: f.seq, data: f.data, w: f.w, h: f.h });
+                            }
+                            // cbs-06: the cbs-02 interim self-ack-on-send policy is GONE.
+                            // True end-to-end backpressure: the pacer is acked ONLY by a
+                            // real `browser-frame-ack` from the pane (see that case
+                            // below), or by the disconnect-time ack-flush in onDown (so a
+                            // gone pane can never wedge the pacer forever).
+                        });
+                        driver.onState((s) => {
+                            const stateFrame = { t: 'browser-state', sessionId, state: s.state };
+                            if (s.url !== undefined)
+                                stateFrame.url = s.url;
+                            if (s.title !== undefined)
+                                stateFrame.title = s.title;
+                            if (s.reason !== undefined)
+                                stateFrame.reason = s.reason;
+                            if (ws && connected)
+                                send(ws, stateFrame);
+                            if (s.state === 'closed' || s.state === 'asleep') {
+                                // cbs-06: ANY terminal state — sleep, idle-timeout, or a
+                                // crash-close — retires this driver instance for good; the
+                                // next browser-open for this sessionId always creates a
+                                // fresh one (see the `existing` branch above).
+                                browserDrivers.delete(sessionId);
+                                browserIdleTrackers.get(sessionId)?.stop();
+                                browserIdleTrackers.delete(sessionId);
+                            }
+                        });
+                        driver.start(url).catch((err) => {
+                            send(socket, { t: 'error', message: err instanceof Error ? err.message : 'browser start failed' });
+                            browserDrivers.delete(sessionId);
+                            browserIdleTrackers.get(sessionId)?.stop();
+                            browserIdleTrackers.delete(sessionId);
+                        });
+                        break;
+                    }
+                    case 'browser-input':
+                        // Never paced/dropped — dispatched straight through in wire
+                        // order (browserFrames.ts's drop rule). A frame for a session
+                        // with no open driver is a safe no-op.
+                        browserDrivers.get(frame.sessionId)?.input(frame.event);
+                        browserIdleTrackers.get(frame.sessionId)?.recordInput(); // cbs-06
+                        break;
+                    case 'browser-frame-ack':
+                        // cbs-06: the real pane ack — the ONLY thing that unblocks the
+                        // driver's keep-newest pacer for the next frame now (see
+                        // browserDriver.ackFrame() / framePacer.ts). Also the "viewer"
+                        // liveness signal for the idle timer. A frame for a session with
+                        // no open driver is a safe no-op.
+                        browserDrivers.get(frame.sessionId)?.ackFrame();
+                        browserIdleTrackers.get(frame.sessionId)?.recordAck();
+                        break;
+                    case 'browser-sleep':
+                        // cbs-06: the pane's explicit 💤 — immediate, reason 'sleep'.
+                        // Safe no-op for an unknown/never-opened session and for a
+                        // session already asleep (its driver was already removed from
+                        // the map by the first sleep's onState handler above).
+                        sleepBrowserSession(frame.sessionId, 'sleep');
+                        break;
+                    default:
+                        send(socket, { t: 'error', message: 'unknown frame type' });
+                }
+            }
+            catch (err) {
+                send(socket, { t: 'error', message: err instanceof Error ? err.message : 'relay client error' });
+            }
+        });
+        const onDown = (info) => {
+            connected = false;
+            // Detach (not close) every live handle: the sessions/PTYs survive the
+            // drop in the SessionManager, scrollback keeps accumulating, and the
+            // next `attach` after re-pairing gets a fresh replay.
+            for (const handle of handles.values())
+                handle.detach();
+            handles.clear();
+            // Cancel any pending activity flush timers; the per-connection state is
+            // discarded and a fresh connection starts clean.
+            for (const st of activity.values())
+                if (st.timer != null)
+                    cancelTimeout(st.timer);
+            activity.clear();
+            // cbs-06: a disconnect means no more `browser-frame-ack` frames can
+            // arrive for any in-flight `browser-frame` until the pane reconnects.
+            // Without this, a frame delivered right before the drop would leave
+            // the driver's pacer wedged (awaiting an ack that can now never come)
+            // for the rest of the session. Ack-flushing every open driver here
+            // unblocks the pacer immediately so a returning pane gets frames
+            // again; it's a safe no-op for any driver with nothing in flight
+            // (framePacer.ack() is a no-op when idle). Browser drivers themselves
+            // are untouched — they survive a relay drop exactly like a PTY does.
+            for (const driver of browserDrivers.values())
+                driver.ackFrame();
+            opts.onDisconnect?.(info);
+            scheduleReconnect();
+        };
+        socket.on('close', (code, reason) => onDown({ code, reason: reason ? String(reason) : undefined }));
+        // 'ws' always follows a connection-level 'error' with a 'close'; this
+        // listener exists only so an unhandled 'error' event never crashes the
+        // process (EventEmitter throws on unlistened 'error').
+        socket.on('error', () => { });
+    }
+    connect();
+    // pucc-14: poll the on-volume login and emit `login-status` on change. Runs
+    // independently of the socket lifecycle; reportLogin no-ops while disconnected
+    // and the next connect force-emits, so a change observed while down is still
+    // reported once the link is back.
+    if (opts.checkLoginValid) {
+        loginPollHandle = scheduleInterval(() => reportLogin(false), opts.loginPollMs ?? 30_000);
+        loginPollHandle?.unref?.();
+    }
+    return {
+        close() {
+            stopped = true;
+            if (reconnectHandle !== null)
+                cancelTimeout(reconnectHandle);
+            if (loginPollHandle !== null)
+                cancelInterval(loginPollHandle);
+            ws?.close();
+        },
+        isConnected: () => connected,
+    };
+}

package/dist/bridge/repoCheckout.d.ts

@@ -22,3 +22,34 @@ export interface CheckoutResult {
 }
 export declare function parseRepoFullName(repoUrl: string): string | null;
 export declare function ensureRepoCheckout(repoUrl: string, deps: RepoCheckoutDeps): Promise<CheckoutResult>;
+/**
+ * pucc-03 — model B multi-repo layout (ADR-0031 decision 2).
+ *
+ * One container holds MANY workspaces' repos, keyed by workspaceId under
+ * `<reposBaseDir>/<workspaceId>` (e.g. /data/repos/<workspaceId>) rather than
+ * by owner/repo. This is deliberately distinct from `ensureRepoCheckout`
+ * (local BYO bridge, keyed by owner/repo under the user's home): here the
+ * workspaceId is the stable identity a terminal is opened against, and the
+ * same workspace always maps to the same checkout regardless of repo renames.
+ *
+ * Clone-on-demand: the FIRST terminal opened for a workspace clones its repo;
+ * every subsequent terminal reuses the existing checkout (idempotent — the
+ * `.git` presence check, not a bare-dir check, so a half-created dir doesn't
+ * masquerade as a clone). This is the clean seam for clone-on-demand: the
+ * entrypoint runs once at container boot and cannot know which workspaces will
+ * be opened, so the bridge (which sees each `open`) owns it — see relayClient.
+ */
+export interface WorkspaceRepoDeps {
+    /** Root that holds every workspace's checkout, e.g. /data/repos. */
+    reposBaseDir: string;
+    exists: (path: string) => boolean;
+    mkdir: (path: string) => void;
+    run: (cmd: string, args: string[]) => Promise<{
+        stdout: string;
+        code: number;
+    }>;
+}
+export declare function ensureWorkspaceRepo(opts: {
+    workspaceId: string;
+    repoUrl?: string;
+}, deps: WorkspaceRepoDeps): Promise<CheckoutResult>;

package/dist/bridge/repoCheckout.js

@@ -11,6 +11,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseRepoFullName = parseRepoFullName;
 exports.ensureRepoCheckout = ensureRepoCheckout;
+exports.ensureWorkspaceRepo = ensureWorkspaceRepo;
 function parseRepoFullName(repoUrl) {
     const m = repoUrl.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/?#].*)?$/) ||
         repoUrl.match(/^([\w.-]+)\/([\w.-]+)$/);
@@ -32,3 +33,20 @@ async function ensureRepoCheckout(repoUrl, deps) {
         return { action: 'failed' };
     }
 }
+async function ensureWorkspaceRepo(opts, deps) {
+    const path = `${deps.reposBaseDir}/${opts.workspaceId}`;
+    // Reuse an existing checkout — never re-clone over a workspace already set up.
+    if (deps.exists(`${path}/.git`))
+        return { path, action: 'existing' };
+    // No checkout yet and no url to clone from → the terminal falls back to home.
+    if (!opts.repoUrl)
+        return { action: 'failed' };
+    try {
+        deps.mkdir(deps.reposBaseDir);
+        await deps.run('git', ['clone', opts.repoUrl, path]);
+        return { path, action: 'cloned' };
+    }
+    catch {
+        return { action: 'failed' };
+    }
+}

package/dist/bridge/server.d.ts

@@ -1,4 +1,7 @@
 import { SessionManager } from './sessionManager';
+import { ValidatePathResult } from './localPathValidation';
+import { PickFolderResult } from './folderPicker';
+import { LocalAddCoreResult } from './localAdd';
 export interface BridgeServerOpts {
     sessionToken: string;
     allowedOrigin: string;
@@ -8,6 +11,36 @@ export interface BridgeServerOpts {
     /** Workspace-scoped terminals: resolve a repo URL to a local checkout dir
      *  (cloned on first use). Absent/null result → shell opens in $HOME. */
     resolveCwd?: (repoUrl: string) => Promise<string | null>;
+    /** lws-03: the registered local workspaces to advertise on /discovery, so
+     *  the arena create-modal can live-detect `wen-market local add` without a
+     *  daemon restart. A GETTER (not a static array) — server.ts calls it on
+     *  every /discovery request, so callers should back it with a fresh
+     *  folderRegistry.loadFolderRegistry() read (or an in-memory cache kept
+     *  current by the `local` commands) to reflect registry changes live. */
+    getLocalWorkspaces?: () => Array<{
+        workspaceId: string;
+        name: string;
+        path: string;
+    }>;
+    /** 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. */
+    getDeviceName?: () => string | null;
+    /** lws-05 — POST /local/validate-path (create-modal typed-path fallback,
+     *  PRD D3c). No session-token gate: read-only, loopback + origin-pinned
+     *  like /discovery. */
+    validatePath?: (absPath: string) => Promise<ValidatePathResult>;
+    /** lws-05 — POST /local/pick-folder (PRD D3b). server.ts enforces "one
+     *  picker at a time" — a second concurrent call gets 409 without invoking
+     *  this again. */
+    pickFolder?: () => Promise<PickFolderResult>;
+    /** lws-05 — POST /local/add (PRD D3b/D3c attach paths, mirroring `wen-market
+     *  local add`). Session-token gated (unlike validate-path/pick-folder) since
+     *  it spends the bridge's PAT to create a workspace. */
+    addLocalWorkspace?: (params: {
+        path: string;
+        name?: string;
+    }) => Promise<LocalAddCoreResult>;
 }
 export interface BridgeServerHandle {
     port: number;