@wenrwa/marketplace-cli 0.4.3 → 0.4.5

package/dist/__tests__/bridge-relay-client.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/bridge-relay-client.test.js

@@ -0,0 +1,283 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ws_1 = require("ws");
+const relayClient_1 = require("../bridge/relayClient");
+const sessionManager_1 = require("../bridge/sessionManager");
+// ── Fake PTY (no real shells in CI) ──────────────────────────────────
+class FakePty {
+    written = [];
+    resizes = [];
+    killed = false;
+    dataCb = null;
+    write(data) { this.written.push(data); }
+    resize(cols, rows) { this.resizes.push({ cols, rows }); }
+    kill() { this.killed = true; }
+    onData(cb) { this.dataCb = cb; }
+    onExit(_cb) { }
+    emitData(d) { this.dataCb?.(d); }
+}
+const makeFactory = () => {
+    const ptys = [];
+    const factory = {
+        spawn: () => {
+            const p = new FakePty();
+            ptys.push(p);
+            return p;
+        },
+    };
+    return { factory, ptys };
+};
+/** Collects parsed frames and lets tests await the next one (mirrors bridge-server.test.ts). */
+function frameQueue(ws) {
+    const frames = [];
+    const waiters = [];
+    ws.on('message', (raw) => {
+        const f = JSON.parse(String(raw));
+        const w = waiters.shift();
+        if (w)
+            w(f);
+        else
+            frames.push(f);
+    });
+    return {
+        next: () => frames.length > 0
+            ? Promise.resolve(frames.shift())
+            : new Promise((resolve) => waiters.push(resolve)),
+    };
+}
+/** A loopback ws server standing in for the platform relay. */
+function startFakeRelay() {
+    return new Promise((resolve) => {
+        const wss = new ws_1.WebSocketServer({ port: 0, host: '127.0.0.1' });
+        const queue = [];
+        const waiters = [];
+        wss.on('connection', (ws) => {
+            const w = waiters.shift();
+            if (w)
+                w(ws);
+            else
+                queue.push(ws);
+        });
+        wss.on('listening', () => {
+            const addr = wss.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            resolve({
+                wss,
+                port,
+                nextConnection: () => queue.length > 0 ? Promise.resolve(queue.shift()) : new Promise((r) => waiters.push(r)),
+            });
+        });
+    });
+}
+function closeRelay(wss) {
+    return new Promise((resolve, reject) => {
+        for (const client of wss.clients)
+            client.terminate();
+        wss.close((err) => (err ? reject(err) : resolve()));
+    });
+}
+describe('relay client — dial-out handshake', () => {
+    it('connects to the relay URL and sends the v1 auth frame first', async () => {
+        const relay = await startFakeRelay();
+        const { factory } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'relay-token-abc',
+            sessions,
+        });
+        const serverSideWs = await relay.nextConnection();
+        const q = frameQueue(serverSideWs);
+        const authFrame = await q.next();
+        expect(authFrame).toEqual({ v: 1, relayToken: 'relay-token-abc' });
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+});
+describe('relay client — frame service through the SessionManager', () => {
+    it('open -> opened; input reaches the PTY; PTY data streams back over the single socket', async () => {
+        const relay = await startFakeRelay();
+        const { factory, ptys } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+        });
+        const ws = await relay.nextConnection();
+        const q = frameQueue(ws);
+        await q.next(); // auth frame
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24 }));
+        const opened = await q.next();
+        expect(opened.t).toBe('opened');
+        expect(opened.sessionId).toBeTruthy();
+        ws.send(JSON.stringify({ t: 'input', sessionId: opened.sessionId, data: 'ls\r' }));
+        await new Promise((r) => setTimeout(r, 20));
+        expect(ptys[0].written).toEqual(['ls\r']);
+        ptys[0].emitData('result');
+        const data = await q.next();
+        expect(data).toMatchObject({ t: 'data', sessionId: opened.sessionId, data: 'result' });
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+    it('second attach takes over: prior sink gets takeover, new one gets replay', async () => {
+        const relay = await startFakeRelay();
+        const { factory, ptys } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+        });
+        const ws = await relay.nextConnection();
+        const q = frameQueue(ws);
+        await q.next(); // auth
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24 }));
+        const opened = await q.next();
+        ptys[0].emitData('history');
+        await q.next(); // 'history' data frame
+        ws.send(JSON.stringify({ t: 'attach', sessionId: opened.sessionId }));
+        const [takeover, replay] = [await q.next(), await q.next()];
+        // Order isn't guaranteed between takeover-to-old-sink and replay-to-new
+        // sink over the SAME socket, so match by type.
+        const byType = (t) => [takeover, replay].find((f) => f.t === t);
+        expect(byType('takeover')).toMatchObject({ t: 'takeover', sessionId: opened.sessionId });
+        expect(byType('replay')).toMatchObject({ t: 'replay', sessionId: opened.sessionId, data: 'history' });
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+    it('multiplexes multiple concurrent sessions over the one outbound socket', async () => {
+        const relay = await startFakeRelay();
+        const { factory, ptys } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+        });
+        const ws = await relay.nextConnection();
+        const q = frameQueue(ws);
+        await q.next(); // auth
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24 }));
+        const openedA = await q.next();
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24 }));
+        const openedB = await q.next();
+        expect(openedA.sessionId).not.toBe(openedB.sessionId);
+        ws.send(JSON.stringify({ t: 'input', sessionId: openedA.sessionId, data: 'to-a' }));
+        ws.send(JSON.stringify({ t: 'input', sessionId: openedB.sessionId, data: 'to-b' }));
+        await new Promise((r) => setTimeout(r, 20));
+        expect(ptys[0].written).toEqual(['to-a']);
+        expect(ptys[1].written).toEqual(['to-b']);
+        ws.send(JSON.stringify({ t: 'resize', sessionId: openedB.sessionId, cols: 100, rows: 40 }));
+        await new Promise((r) => setTimeout(r, 20));
+        expect(ptys[1].resizes).toEqual([{ cols: 100, rows: 40 }]);
+        ws.send(JSON.stringify({ t: 'close', sessionId: openedA.sessionId }));
+        await new Promise((r) => setTimeout(r, 20));
+        expect(ptys[0].killed).toBe(true);
+        expect(sessions.list()).toEqual([openedB.sessionId]);
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+});
+describe('relay client — reconnect with backoff + jitter', () => {
+    it('on drop, schedules a reconnect using the computed backoff delay (injectable timer)', async () => {
+        const relay = await startFakeRelay();
+        const { factory } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const scheduled = [];
+        const setTimeoutFn = (cb, ms) => {
+            scheduled.push({ cb, ms });
+            return scheduled.length; // opaque handle
+        };
+        const clearTimeoutFn = () => { };
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+            backoff: { initialMs: 100, maxMs: 1000, factor: 2, jitter: () => 1 }, // deterministic: full ceiling
+            setTimeoutFn,
+            clearTimeoutFn,
+        });
+        const ws = await relay.nextConnection(); // already open by the time 'connection' fires
+        // Drop the connection from the relay side.
+        ws.terminate();
+        await new Promise((r) => setTimeout(r, 30));
+        expect(scheduled.length).toBe(1);
+        expect(scheduled[0].ms).toBe(100); // attempt 0: 100 * 2^0 * jitter(1) = 100
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+    it('backoff grows exponentially per attempt, capped at maxMs', async () => {
+        // A relay that never accepts a connection (nothing listens on this port)
+        // means every attempt fails before 'open' — so attempt count never
+        // resets, and we can observe pure exponential growth without racing a
+        // real handshake's success-resets-backoff behavior.
+        const probe = await startFakeRelay();
+        const deadPort = probe.port;
+        await closeRelay(probe.wss);
+        const { factory } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const scheduled = [];
+        const setTimeoutFn = (cb, ms) => {
+            scheduled.push({ cb, ms });
+            return scheduled.length;
+        };
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${deadPort}`,
+            relayToken: 'tok',
+            sessions,
+            backoff: { initialMs: 100, maxMs: 350, factor: 2, jitter: () => 1 },
+            setTimeoutFn,
+            clearTimeoutFn: () => { },
+        });
+        await new Promise((r) => setTimeout(r, 50));
+        expect(scheduled[0]?.ms).toBe(100); // 100 * 2^0
+        scheduled[0].cb();
+        await new Promise((r) => setTimeout(r, 50));
+        expect(scheduled[1]?.ms).toBe(200); // 100 * 2^1
+        scheduled[1].cb();
+        await new Promise((r) => setTimeout(r, 50));
+        expect(scheduled[2]?.ms).toBe(350); // 100 * 2^2 = 400, capped at 350
+        handle.close();
+    });
+    it('reconnects and re-pairs: PTY survives the drop, replay reflects everything that happened while down', async () => {
+        const relay = await startFakeRelay();
+        const { factory, ptys } = makeFactory();
+        const sessions = new sessionManager_1.SessionManager(factory);
+        const scheduled = [];
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+            backoff: { initialMs: 1, jitter: () => 0.01 },
+            setTimeoutFn: (cb) => {
+                scheduled.push(cb);
+                return scheduled.length;
+            },
+            clearTimeoutFn: () => { },
+        });
+        const ws1 = await relay.nextConnection();
+        const q1 = frameQueue(ws1);
+        await q1.next(); // auth
+        ws1.send(JSON.stringify({ t: 'open', cols: 80, rows: 24 }));
+        const opened = await q1.next();
+        // Drop the relay connection — the PTY must NOT be killed.
+        ws1.terminate();
+        await new Promise((r) => setTimeout(r, 20));
+        expect(ptys[0].killed).toBe(false);
+        expect(sessions.list()).toEqual([opened.sessionId]);
+        // Session produces output while the relay link is down.
+        ptys[0].emitData('while-down');
+        // Fire the scheduled reconnect (simulates backoff timer elapsing).
+        expect(scheduled.length).toBe(1);
+        scheduled[0]();
+        const ws2 = await relay.nextConnection();
+        const q2 = frameQueue(ws2);
+        await q2.next(); // fresh auth frame on the new socket
+        ws2.send(JSON.stringify({ t: 'attach', sessionId: opened.sessionId }));
+        const replay = await q2.next();
+        expect(replay).toMatchObject({ t: 'replay', sessionId: opened.sessionId, data: 'while-down' });
+        handle.close();
+        await closeRelay(relay.wss);
+    });
+});

package/dist/__tests__/bridge-relay-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/bridge-relay-mode.test.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bridge_1 = require("../commands/bridge");
+describe('resolveRelayMode — CLI/env wiring for `wen-market bridge --relay`', () => {
+    it('no --relay flag and no RELAY_URL env → local mode', () => {
+        expect((0, bridge_1.resolveRelayMode)({}, {})).toEqual({ mode: 'local' });
+    });
+    it('--relay without --relay-token → a clear startup error, no env fallback', () => {
+        const result = (0, bridge_1.resolveRelayMode)({ relay: 'wss://relay.hiveop.io/agent' }, {});
+        expect(result.mode).toBe('relay-error');
+        expect(result.message).toMatch(/relay-token/i);
+    });
+    it('--relay with --relay-token → relay mode with both values', () => {
+        const result = (0, bridge_1.resolveRelayMode)({ relay: 'wss://relay.hiveop.io/agent', relayToken: 'rt_abc123' }, {});
+        expect(result).toEqual({
+            mode: 'relay',
+            relayUrl: 'wss://relay.hiveop.io/agent',
+            relayToken: 'rt_abc123',
+        });
+    });
+    it('RELAY_URL + RELAY_TOKEN env vars (container-friendly) → relay mode, no flags needed', () => {
+        const result = (0, bridge_1.resolveRelayMode)({}, { RELAY_URL: 'wss://relay.internal/x', RELAY_TOKEN: 'rt_env' });
+        expect(result).toEqual({ mode: 'relay', relayUrl: 'wss://relay.internal/x', relayToken: 'rt_env' });
+    });
+    it('RELAY_URL env with no token anywhere → clear startup error', () => {
+        const result = (0, bridge_1.resolveRelayMode)({}, { RELAY_URL: 'wss://relay.internal/x' });
+        expect(result.mode).toBe('relay-error');
+    });
+    it('flag values win over env vars when both present', () => {
+        const result = (0, bridge_1.resolveRelayMode)({ relay: 'wss://flag-wins/', relayToken: 'flag-token' }, { RELAY_URL: 'wss://env-loses/', RELAY_TOKEN: 'env-token' });
+        expect(result).toEqual({ mode: 'relay', relayUrl: 'wss://flag-wins/', relayToken: 'flag-token' });
+    });
+});

package/dist/__tests__/bridge-repo-checkout.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/bridge-repo-checkout.test.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const repoCheckout_1 = require("../bridge/repoCheckout");
+const BASE = '/Users/t/wenrwa-workspaces';
+const makeDeps = (existing = [], cloneFails = false) => {
+    const runs = [];
+    return {
+        runs,
+        deps: {
+            baseDir: BASE,
+            exists: (p) => existing.includes(p),
+            mkdir: (_p) => { },
+            run: async (cmd, args) => {
+                runs.push([cmd, ...args]);
+                if (cloneFails)
+                    throw new Error('clone failed');
+                return { stdout: '', code: 0 };
+            },
+        },
+    };
+};
+describe('parseRepoFullName', () => {
+    it('handles https, trailing .git, and bare owner/repo', () => {
+        expect((0, repoCheckout_1.parseRepoFullName)('https://github.com/BunnyDAO/CBP')).toBe('BunnyDAO/CBP');
+        expect((0, repoCheckout_1.parseRepoFullName)('https://github.com/BunnyDAO/CBP.git')).toBe('BunnyDAO/CBP');
+        expect((0, repoCheckout_1.parseRepoFullName)('BunnyDAO/CBP')).toBe('BunnyDAO/CBP');
+        expect((0, repoCheckout_1.parseRepoFullName)('not a repo url')).toBeNull();
+    });
+});
+describe('ensureRepoCheckout', () => {
+    it('reuses an existing checkout without running git', async () => {
+        const { deps, runs } = makeDeps([`${BASE}/BunnyDAO/CBP`]);
+        const result = await (0, repoCheckout_1.ensureRepoCheckout)('https://github.com/BunnyDAO/CBP', deps);
+        expect(result).toEqual({ path: `${BASE}/BunnyDAO/CBP`, action: 'existing' });
+        expect(runs).toHaveLength(0);
+    });
+    it('clones a missing repo into the workspace base dir', async () => {
+        const { deps, runs } = makeDeps();
+        const result = await (0, repoCheckout_1.ensureRepoCheckout)('https://github.com/BunnyDAO/CBP.git', deps);
+        expect(result).toEqual({ path: `${BASE}/BunnyDAO/CBP`, action: 'cloned' });
+        expect(runs[0].join(' ')).toBe(`git clone https://github.com/BunnyDAO/CBP.git ${BASE}/BunnyDAO/CBP`);
+    });
+    it('reports failure without throwing when the clone fails (no local git auth, etc.)', async () => {
+        const { deps } = makeDeps([], true);
+        const result = await (0, repoCheckout_1.ensureRepoCheckout)('https://github.com/Private/Repo', deps);
+        expect(result.action).toBe('failed');
+    });
+    it('rejects unparseable repo urls', async () => {
+        const { deps } = makeDeps();
+        const result = await (0, repoCheckout_1.ensureRepoCheckout)('garbage', deps);
+        expect(result.action).toBe('failed');
+    });
+});

package/dist/__tests__/bridge-server.test.js

@@ -140,6 +140,27 @@ describe('bridge WebSocket server', () => {
         });
         expect(bad.status).toBe(403);
     });
+    it('threads repoUrl through resolveCwd into the PTY spawn and the opened frame', async () => {
+        await handle.close();
+        const cwds = [];
+        const factory = { spawn: (o) => { cwds.push(o.cwd); const p = new FakePty(); ptys.push(p); return p; } };
+        handle = await (0, server_1.startBridgeServer)({
+            sessionToken: TOKEN,
+            allowedOrigin: ORIGIN,
+            sessions: new sessionManager_1.SessionManager(factory),
+            resolveCwd: async (repoUrl) => (repoUrl.includes('CBP') ? '/tmp/wenrwa-workspaces/BunnyDAO/CBP' : null),
+        });
+        const { ws, q } = await openAndAuth(handle.port);
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24, repoUrl: 'https://github.com/BunnyDAO/CBP' }));
+        const opened = await q.next();
+        expect(opened.cwd).toBe('/tmp/wenrwa-workspaces/BunnyDAO/CBP');
+        expect(cwds[0]).toBe('/tmp/wenrwa-workspaces/BunnyDAO/CBP');
+        ws.send(JSON.stringify({ t: 'open', cols: 80, rows: 24, repoUrl: 'https://github.com/Other/Repo' }));
+        const fallback = await q.next();
+        expect(fallback.cwd).toBeUndefined();
+        expect(fallback.note).toContain('home directory');
+        ws.close();
+    });
     it('unauthenticated frames are rejected', async () => {
         const ws = connect(handle.port);
         await new Promise((r) => ws.on('open', r));

package/dist/bridge/realPty.js

@@ -68,12 +68,12 @@ function realPtyFactory() {
     const pty = require('node-pty');
     const shell = process.env.SHELL || (os.platform() === 'win32' ? 'powershell.exe' : '/bin/bash');
     return {
-        spawn: ({ cols, rows }) => {
+        spawn: ({ cols, rows, cwd }) => {
             const proc = pty.spawn(shell, [], {
                 name: 'xterm-256color',
                 cols,
                 rows,
-                cwd: os.homedir(),
+                cwd: cwd || os.homedir(),
                 env: process.env,
             });
             return {

package/dist/bridge/relayClient.d.ts

@@ -0,0 +1,42 @@
+import { SessionManager } from './sessionManager';
+/** Minimal surface relayClient needs from a socket — lets tests inject fakes if ever needed. */
+export interface WebSocketLike {
+    readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: 'open' | 'message' | 'close' | 'error', cb: (...args: any[]) => void): void;
+}
+export interface BackoffOpts {
+    /** First retry delay in ms (before jitter). Default 250. */
+    initialMs?: number;
+    /** Cap on the backoff ceiling. Default 10_000. */
+    maxMs?: number;
+    /** Multiplier per attempt. Default 2. */
+    factor?: number;
+    /** Returns a value in [0, 1); overridable for deterministic tests. Default Math.random. */
+    jitter?: () => number;
+}
+export interface RelayClientOpts {
+    relayUrl: string;
+    relayToken: string;
+    sessions: SessionManager;
+    /** Injectable for tests: defaults to `new WebSocket(url)` from `ws`. */
+    wsFactory?: (url: string) => WebSocketLike;
+    backoff?: BackoffOpts;
+    /** Injectable timer so backoff tests never wait on a real clock. */
+    setTimeoutFn?: (cb: () => void, ms: number) => unknown;
+    clearTimeoutFn?: (handle: unknown) => void;
+    /** Test/observability hooks. */
+    onConnect?: () => void;
+    onDisconnect?: (info: {
+        code?: number;
+        reason?: string;
+    }) => void;
+    onReconnectScheduled?: (delayMs: number) => void;
+}
+export interface RelayClientHandle {
+    /** Stop reconnecting and close the current socket. Sessions are untouched — they live in SessionManager. */
+    close(): void;
+    isConnected(): boolean;
+}
+export declare function startRelayClient(opts: RelayClientOpts): RelayClientHandle;

package/dist/bridge/relayClient.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 PROTOCOL_VERSION = 1;
+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));
+    let stopped = false;
+    let ws = null;
+    let connected = false;
+    let attempt = 0;
+    let reconnectHandle = null;
+    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();
+        const attachTo = (sessionId) => {
+            const handle = opts.sessions.attach(sessionId, (frame) => {
+                if (frame.t === 'data')
+                    send(socket, { t: 'data', sessionId, data: frame.data });
+                else if (frame.t === 'takeover')
+                    send(socket, { t: 'takeover', sessionId });
+            });
+            handles.set(sessionId, handle);
+            return handle;
+        };
+        socket.on('open', () => {
+            send(socket, { v: PROTOCOL_VERSION, relayToken: opts.relayToken });
+            connected = true;
+            attempt = 0;
+            opts.onConnect?.();
+        });
+        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': {
+                        const sessionId = opts.sessions.open({ cols: frame.cols, rows: frame.rows });
+                        attachTo(sessionId);
+                        send(socket, { t: 'opened', sessionId });
+                        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);
+                        opts.sessions.close(frame.sessionId);
+                        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();
+            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();
+    return {
+        close() {
+            stopped = true;
+            if (reconnectHandle !== null)
+                cancelTimeout(reconnectHandle);
+            ws?.close();
+        },
+        isConnected: () => connected,
+    };
+}

package/dist/bridge/repoCheckout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * bct UX round 2 (2026-07-30) — workspace-scoped terminals.
+ *
+ * The arena's mental model is workspace = repo, so the Terminal pane sends
+ * the workspace's GitHub URL with `open`, and the bridge lands the shell in
+ * a local checkout of that repo (cloning on first use with the USER'S own
+ * git credentials — the platform never touches repo auth). Checkouts live
+ * under ~/wenrwa-workspaces/<owner>/<repo>.
+ */
+export interface RepoCheckoutDeps {
+    baseDir: string;
+    exists: (path: string) => boolean;
+    mkdir: (path: string) => void;
+    run: (cmd: string, args: string[]) => Promise<{
+        stdout: string;
+        code: number;
+    }>;
+}
+export interface CheckoutResult {
+    path?: string;
+    action: 'existing' | 'cloned' | 'failed';
+}
+export declare function parseRepoFullName(repoUrl: string): string | null;
+export declare function ensureRepoCheckout(repoUrl: string, deps: RepoCheckoutDeps): Promise<CheckoutResult>;

package/dist/bridge/repoCheckout.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * bct UX round 2 (2026-07-30) — workspace-scoped terminals.
+ *
+ * The arena's mental model is workspace = repo, so the Terminal pane sends
+ * the workspace's GitHub URL with `open`, and the bridge lands the shell in
+ * a local checkout of that repo (cloning on first use with the USER'S own
+ * git credentials — the platform never touches repo auth). Checkouts live
+ * under ~/wenrwa-workspaces/<owner>/<repo>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseRepoFullName = parseRepoFullName;
+exports.ensureRepoCheckout = ensureRepoCheckout;
+function parseRepoFullName(repoUrl) {
+    const m = repoUrl.match(/github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/?#].*)?$/) ||
+        repoUrl.match(/^([\w.-]+)\/([\w.-]+)$/);
+    return m ? `${m[1]}/${m[2]}` : null;
+}
+async function ensureRepoCheckout(repoUrl, deps) {
+    const fullName = parseRepoFullName(repoUrl);
+    if (!fullName)
+        return { action: 'failed' };
+    const path = `${deps.baseDir}/${fullName}`;
+    if (deps.exists(path))
+        return { path, action: 'existing' };
+    try {
+        deps.mkdir(path.slice(0, path.lastIndexOf('/')));
+        await deps.run('git', ['clone', repoUrl, path]);
+        return { path, action: 'cloned' };
+    }
+    catch {
+        return { action: 'failed' };
+    }
+}

package/dist/bridge/server.d.ts

@@ -5,6 +5,9 @@ export interface BridgeServerOpts {
     sessions: SessionManager;
     /** 0 (default) = ephemeral port. */
     port?: number;
+    /** 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>;
 }
 export interface BridgeServerHandle {
     port: number;

package/dist/bridge/server.js

@@ -137,9 +137,19 @@ function startBridgeServer(opts) {
             try {
                 switch (frame.t) {
                     case 'open': {
-                        const sessionId = opts.sessions.open({ cols: frame.cols, rows: frame.rows });
-                        attachTo(sessionId);
-                        send(ws, { t: 'opened', sessionId });
+                        const openSession = (cwd, note) => {
+                            const sessionId = opts.sessions.open({ cols: frame.cols, rows: frame.rows, cwd });
+                            attachTo(sessionId);
+                            send(ws, { t: 'opened', sessionId, ...(cwd ? { cwd } : {}), ...(note ? { note } : {}) });
+                        };
+                        if (frame.repoUrl && opts.resolveCwd) {
+                            opts.resolveCwd(frame.repoUrl)
+                                .then((cwd) => openSession(cwd ?? undefined, cwd ? undefined : 'repo checkout unavailable — opened in home directory'))
+                                .catch(() => openSession(undefined, 'repo checkout failed — opened in home directory'));
+                        }
+                        else {
+                            openSession();
+                        }
                         break;
                     }
                     case 'attach': {

package/dist/bridge/sessionManager.d.ts

@@ -9,6 +9,7 @@ export interface PtyFactory {
     spawn(opts: {
         cols: number;
         rows: number;
+        cwd?: string;
     }): PtyLike;
 }
 export type SinkFrame = {
@@ -35,6 +36,7 @@ export declare class SessionManager {
     open(opts: {
         cols: number;
         rows: number;
+        cwd?: string;
     }): string;
     attach(sessionId: string, sink: Sink): AttachmentHandle;
     close(sessionId: string): void;

package/dist/commands/bridge.d.ts

@@ -1,3 +1,18 @@
 import { Command } from 'commander';
 export declare const DEFAULT_BRIDGE_PORT = 8377;
+export type RelayCliOpts = {
+    relay?: string;
+    relayToken?: string;
+};
+export type RelayModeResolution = {
+    mode: 'local';
+} | {
+    mode: 'relay';
+    relayUrl: string;
+    relayToken: string;
+} | {
+    mode: 'relay-error';
+    message: string;
+};
+export declare function resolveRelayMode(opts: RelayCliOpts, env?: Record<string, string | undefined>): RelayModeResolution;
 export declare const bridgeCommand: Command;

package/dist/commands/bridge.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.bridgeCommand = exports.DEFAULT_BRIDGE_PORT = void 0;
+exports.resolveRelayMode = resolveRelayMode;
 /**
  * bct-05 — `wen-market bridge`: the local Terminal Bridge.
  *
@@ -53,10 +54,12 @@ const commander_1 = require("commander");
 const chalk_1 = __importDefault(require("chalk"));
 const sessionManager_1 = require("../bridge/sessionManager");
 const server_1 = require("../bridge/server");
+const relayClient_1 = require("../bridge/relayClient");
 const realPty_1 = require("../bridge/realPty");
 const config_1 = require("../bridge/config");
 const mcpRegister_1 = require("../bridge/mcpRegister");
 const autostart_1 = require("../bridge/autostart");
+const repoCheckout_1 = require("../bridge/repoCheckout");
 const config_2 = require("../utils/config");
 exports.DEFAULT_BRIDGE_PORT = 8377;
 const DEFAULT_ORIGIN = 'https://app.hiveop.io';
@@ -66,6 +69,19 @@ const DEFAULT_BRIDGE_API_URL = 'https://api.wenrwa.com/api/v1';
 function bridgeApiUrl() {
     return process.env.MARKETPLACE_API_URL || (0, config_2.loadConfig)()?.apiUrl || DEFAULT_BRIDGE_API_URL;
 }
+function resolveRelayMode(opts, env = process.env) {
+    const relayUrl = opts.relay || env.RELAY_URL;
+    if (!relayUrl)
+        return { mode: 'local' };
+    const relayToken = opts.relayToken || env.RELAY_TOKEN;
+    if (!relayToken) {
+        return {
+            mode: 'relay-error',
+            message: 'Relay mode requires a token: pass --relay-token <t> or set RELAY_TOKEN.',
+        };
+    }
+    return { mode: 'relay', relayUrl, relayToken };
+}
 const execRunner = (cmd, args) => new Promise((resolve, reject) => {
     (0, child_process_1.execFile)(cmd, args, (err, stdout) => {
         if (err && !stdout)
@@ -89,7 +105,31 @@ exports.bridgeCommand = new commander_1.Command('bridge')
     .option('--token <connectToken>', 'Connect Token from arena settings (stored on first run, never logged)')
     .option('--port <port>', 'port to listen on (loopback only)', String(exports.DEFAULT_BRIDGE_PORT))
     .option('--origin <origin>', 'allowed browser origin', process.env.WENRWA_BRIDGE_ORIGIN || DEFAULT_ORIGIN)
+    .option('--relay <url>', 'ht-05: dial out to this platform relay (wss://…) instead of listening locally — container-agent mode')
+    .option('--relay-token <token>', 'relay auth token (or set RELAY_TOKEN) — required with --relay')
     .action(async (opts) => {
+    // ht-05: relay mode dials OUT to the platform relay instead of listening
+    // on localhost. It skips the Connect Token / MCP registration / discovery
+    // file entirely — the container image handles claude/MCP config (ht-06).
+    const relayMode = resolveRelayMode(opts);
+    if (relayMode.mode === 'relay-error') {
+        console.error(chalk_1.default.red(relayMode.message));
+        process.exit(1);
+        return;
+    }
+    if (relayMode.mode === 'relay') {
+        const sessions = new sessionManager_1.SessionManager((0, realPty_1.realPtyFactory)());
+        (0, relayClient_1.startRelayClient)({
+            relayUrl: relayMode.relayUrl,
+            relayToken: relayMode.relayToken,
+            sessions,
+            onConnect: () => console.log(chalk_1.default.cyan(`Terminal Bridge dialed in to relay (${relayMode.relayUrl})`)),
+            onDisconnect: () => console.log(chalk_1.default.yellow('Relay connection dropped — reconnecting…')),
+        });
+        console.log(chalk_1.default.dim('Relay mode: serving terminal sessions to the platform relay. Ctrl+C stops the bridge.'));
+        return;
+    }
+    // ---- local mode (byte-identical to pre-ht-05 behavior) ----
     // 1. Connect Token: flag on first run, config thereafter.
     if (opts.token) {
         if (!opts.token.startsWith('wm_ct_')) {
@@ -120,11 +160,25 @@ exports.bridgeCommand = new commander_1.Command('bridge')
         console.log(chalk_1.default.yellow('! claude binary not found — bridge will run, but install Claude Code for MCP world-wiring'));
     // 3. Serve.
     const sessionToken = crypto.randomBytes(16).toString('hex');
+    const workspacesBase = `${os.homedir()}/wenrwa-workspaces`;
     const handle = await (0, server_1.startBridgeServer)({
         sessionToken,
         allowedOrigin: opts.origin,
         sessions: new sessionManager_1.SessionManager((0, realPty_1.realPtyFactory)()),
         port: Number(opts.port),
+        // Workspace-scoped shells: the pane sends the workspace's GitHub URL;
+        // we land the PTY in a local checkout (user's own git credentials).
+        resolveCwd: async (repoUrl) => {
+            const result = await (0, repoCheckout_1.ensureRepoCheckout)(repoUrl, {
+                baseDir: workspacesBase,
+                exists: (p) => fs.existsSync(p),
+                mkdir: (p) => fs.mkdirSync(p, { recursive: true }),
+                run: execRunner,
+            });
+            if (result.action === 'cloned')
+                console.log(chalk_1.default.green(`✓ Cloned ${repoUrl} → ${result.path}`));
+            return result.path ?? null;
+        },
     });
     (0, config_1.writeDiscoveryFile)({ port: handle.port, sessionToken });
     fs.appendFileSync((0, config_1.bridgeLogPath)(), `${new Date().toISOString()} bridge up on ${handle.address}:${handle.port}\n`);

package/dist/index.js

@@ -15,11 +15,13 @@ const repo_1 = require("./commands/repo");
 const prompts_1 = require("./commands/prompts");
 const credits_1 = require("./commands/credits");
 const bridge_1 = require("./commands/bridge");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { version } = require('../package.json');
 const program = new commander_1.Command();
 program
     .name('wen-market')
     .description('Wenrwa Agent Marketplace CLI')
-    .version('0.3.0');
+    .version(version);
 program.addCommand(auth_1.authCommand);
 program.addCommand(workspace_1.workspaceCommand);
 program.addCommand(bounty_1.bountyCommand);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wenrwa/marketplace-cli",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "CLI tool for the Wenrwa Agent Marketplace — monitor bounties, agents, workspaces, and treasury from your terminal",
   "author": "Wenrwa <dev@wenrwa.com>",
   "license": "MIT",