@wenrwa/marketplace-cli 0.7.0 → 0.7.2

package/dist/__tests__/bridge-attach-file.test.d.ts

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

package/dist/__tests__/bridge-attach-file.test.js

@@ -0,0 +1,194 @@
+"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 });
+/**
+ * Terminal attach — `attach-file` saves an image next to the session's agent
+ * and answers `file-attached` with its absolute path. Both lanes: the local
+ * loopback server and the relay client (hosted container) share one handler,
+ * and both are exercised here end to end against a REAL temp folder so the
+ * bytes on disk are compared with the bytes sent.
+ */
+const ws_1 = __importStar(require("ws"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const server_1 = require("../bridge/server");
+const relayClient_1 = require("../bridge/relayClient");
+const sessionManager_1 = require("../bridge/sessionManager");
+const attachmentWriter_1 = require("../bridge/attachmentWriter");
+class FakePty {
+    written = [];
+    write(d) { this.written.push(d); }
+    resize() { }
+    kill() { }
+    onData() { }
+    onExit() { }
+}
+// A real (tiny) PNG: signature + IHDR + IDAT + IEND for a 1x1 pixel, plus
+// every byte value so a lossy encoding would be caught.
+const PNG_1PX = Buffer.from('89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000d4944415478da63f8cfc0f01f0005000201a5f3b4d60000000049454e44ae426082', 'hex');
+const PNG = Buffer.concat([PNG_1PX, Buffer.from(Array.from({ length: 256 }, (_, i) => i))]);
+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 ? Promise.resolve(frames.shift()) : new Promise((r) => waiters.push(r))) };
+}
+let tmp;
+beforeEach(() => { tmp = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'attach-'))); });
+afterEach(() => { fs.rmSync(tmp, { recursive: true, force: true }); });
+describe('attachmentWriter — pure rules', () => {
+    it('sniffs the type from magic bytes, never the name', () => {
+        expect((0, attachmentWriter_1.sniffImageExt)(PNG)).toBe('png');
+        expect((0, attachmentWriter_1.sniffImageExt)(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0, 0]))).toBe('jpg');
+        expect((0, attachmentWriter_1.sniffImageExt)(Buffer.from('GIF89a......'))).toBe('gif');
+        expect((0, attachmentWriter_1.sniffImageExt)(Buffer.concat([Buffer.from('RIFF'), Buffer.alloc(4), Buffer.from('WEBPVP8 ')]))).toBe('webp');
+        expect((0, attachmentWriter_1.sniffImageExt)(Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>'))).toBeNull();
+        expect((0, attachmentWriter_1.sniffImageExt)(Buffer.from('%PDF-1.7'))).toBeNull();
+    });
+    it('makes a stem that needs no escaping and cannot traverse', () => {
+        expect((0, attachmentWriter_1.safeAttachmentStem)('Screenshot 2026-10-04 at 9.41.12 AM.png')).toBe('Screenshot-2026-10-04-at-9.41.12-AM');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('../../etc/passwd')).toBe('passwd');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('..\\..\\x.png')).toBe('x');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('.hidden.png')).toBe('hidden');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('日本語.png')).toBe('image');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('')).toBe('image');
+        expect((0, attachmentWriter_1.safeAttachmentStem)('a'.repeat(90) + '.png')).toHaveLength(40);
+    });
+    it('writes byte-identical bytes under .hiveop/attachments with a self-ignoring .gitignore', () => {
+        const r = (0, attachmentWriter_1.writeAttachment)({ root: tmp, name: 'shot one.png', dataBase64: PNG.toString('base64') });
+        expect(r.ok).toBe(true);
+        if (!r.ok)
+            return;
+        expect(path.dirname(r.path)).toBe(path.join(tmp, attachmentWriter_1.ATTACHMENTS_DIR));
+        expect(path.basename(r.path)).toMatch(/^\d{8}-\d{6}-[0-9a-f]{4}-shot-one\.png$/);
+        expect(fs.readFileSync(r.path).equals(PNG)).toBe(true);
+        expect(fs.readFileSync(path.join(tmp, attachmentWriter_1.ATTACHMENTS_DIR, '.gitignore'), 'utf8')).toBe('*\n');
+        // No temp files left behind.
+        expect(fs.readdirSync(path.join(tmp, attachmentWriter_1.ATTACHMENTS_DIR)).filter((f) => f.endsWith('.tmp'))).toEqual([]);
+    });
+    it('names the extension from the bytes even when the name lies', () => {
+        const r = (0, attachmentWriter_1.writeAttachment)({ root: tmp, name: 'photo.jpg', dataBase64: PNG.toString('base64') });
+        expect(r.ok && r.path.endsWith('-photo.png')).toBe(true);
+    });
+    it('refuses non-images and oversize files without writing anything', () => {
+        expect((0, attachmentWriter_1.writeAttachment)({ root: tmp, name: 'x.png', dataBase64: Buffer.from('not an image').toString('base64') }))
+            .toEqual({ ok: false, reason: 'not-image' });
+        const big = Buffer.concat([PNG_1PX, Buffer.alloc(attachmentWriter_1.MAX_ATTACHMENT_BYTES)]);
+        expect((0, attachmentWriter_1.writeAttachment)({ root: tmp, name: 'x.png', dataBase64: big.toString('base64') }))
+            .toEqual({ ok: false, reason: 'too-large' });
+        expect(fs.existsSync(path.join(tmp, '.hiveop'))).toBe(false);
+    });
+    it('refuses to follow a planted .hiveop symlink out of the project', () => {
+        const outside = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'outside-')));
+        try {
+            fs.mkdirSync(path.join(outside, 'attachments'));
+            fs.symlinkSync(outside, path.join(tmp, '.hiveop'));
+            expect((0, attachmentWriter_1.writeAttachment)({ root: tmp, name: 'x.png', dataBase64: PNG.toString('base64') }))
+                .toEqual({ ok: false, reason: 'error' });
+            expect(fs.readdirSync(path.join(outside, 'attachments'))).toEqual([]);
+        }
+        finally {
+            fs.rmSync(outside, { recursive: true, force: true });
+        }
+    });
+    it('refuses an unknown session (the session decides the folder, not the frame)', () => {
+        const sessions = { list: () => ['a'], cwdOf: () => tmp };
+        expect((0, attachmentWriter_1.handleAttachFrame)({ rid: 'r', sessionId: 'b', data: PNG.toString('base64') }, sessions))
+            .toEqual({ t: 'file-attached', rid: 'r', sessionId: 'b', ok: false, reason: 'no-session' });
+    });
+});
+describe('local bridge server — attach-file frame', () => {
+    let handle;
+    let sessions;
+    let ptys;
+    beforeEach(async () => {
+        ptys = [];
+        const factory = { spawn: () => { const p = new FakePty(); ptys.push(p); return p; } };
+        sessions = new sessionManager_1.SessionManager(factory);
+        handle = await (0, server_1.startBridgeServer)({ sessionToken: 'tok', allowedOrigin: 'https://app.hiveop.io', sessions });
+    });
+    afterEach(async () => { await handle.close(); });
+    it('writes next to the session and replies with the absolute path; nothing reaches the PTY', async () => {
+        const sessionId = sessions.open({ cols: 80, rows: 24, cwd: tmp, id: 'agent-1' });
+        const ws = new ws_1.default(`ws://127.0.0.1:${handle.port}`, { headers: { origin: 'https://app.hiveop.io' } });
+        await new Promise((r) => ws.on('open', r));
+        const q = frameQueue(ws);
+        ws.send(JSON.stringify({ v: 1, token: 'tok' }));
+        ws.send(JSON.stringify({ t: 'attach-file', rid: 'r1', sessionId, name: 'Screen Shot.png', data: PNG.toString('base64') }));
+        const reply = await q.next();
+        expect(reply).toMatchObject({ t: 'file-attached', rid: 'r1', sessionId, ok: true, bytes: PNG.length });
+        expect(reply.path.startsWith(path.join(tmp, attachmentWriter_1.ATTACHMENTS_DIR) + path.sep)).toBe(true);
+        expect(fs.readFileSync(reply.path).equals(PNG)).toBe(true);
+        expect(ptys[0].written).toEqual([]);
+        ws.close();
+    });
+    it('advertises the terminal-attach capability in /discovery', async () => {
+        const res = await fetch(`http://127.0.0.1:${handle.port}/discovery`, { headers: { origin: 'https://app.hiveop.io' } });
+        const body = await res.json();
+        expect(body.capabilities).toContain('terminal-attach');
+    });
+});
+describe('relay client (hosted container) — attach-file frame', () => {
+    it('writes next to the relay session and echoes rid + sessionId for demux', async () => {
+        const wss = new ws_1.WebSocketServer({ port: 0, host: '127.0.0.1' });
+        await new Promise((r) => wss.on('listening', r));
+        const port = wss.address().port;
+        const conn = new Promise((r) => wss.on('connection', r));
+        const sessions = new sessionManager_1.SessionManager({ spawn: () => new FakePty() });
+        sessions.open({ cols: 80, rows: 24, cwd: tmp, id: 'agent-H' });
+        const client = (0, relayClient_1.startRelayClient)({ relayUrl: `ws://127.0.0.1:${port}`, relayToken: 'tok', sessions });
+        const ws = await conn;
+        const q = frameQueue(ws);
+        await q.next(); // auth
+        ws.send(JSON.stringify({ t: 'attach-file', rid: 'h1', sessionId: 'agent-H', name: 'x.png', data: PNG.toString('base64') }));
+        const reply = await q.next();
+        expect(reply).toMatchObject({ t: 'file-attached', rid: 'h1', sessionId: 'agent-H', ok: true });
+        expect(fs.readFileSync(reply.path).equals(PNG)).toBe(true);
+        ws.send(JSON.stringify({ t: 'attach-file', rid: 'h2', sessionId: 'agent-H', name: 'x.txt', data: Buffer.from('hello').toString('base64') }));
+        expect(await q.next()).toMatchObject({ t: 'file-attached', rid: 'h2', ok: false, reason: 'not-image' });
+        client.close();
+        for (const c of wss.clients)
+            c.terminate();
+        await new Promise((r) => wss.close(r));
+    });
+});

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

@@ -62,7 +62,10 @@ class FakeBrowserDriver {
     }
     async back() { }
     async forward() { }
-    async reload() { }
+    reloadCalls = 0;
+    async reload() {
+        this.reloadCalls += 1;
+    }
     onFrame(cb) {
         this.frameCb = cb;
     }
@@ -1120,3 +1123,80 @@ describe('relay client — browser no-consumer sweep (cbs-14)', () => {
         await closeRelay(relay.wss);
     });
 });
+describe('relay client — browser tabs (cvt-07)', () => {
+    async function boot(extra = {}) {
+        const relay = await startFakeRelay();
+        const sessions = new sessionManager_1.SessionManager(makeFactory());
+        const drivers = {};
+        let clock = 1_000;
+        const handle = (0, relayClient_1.startRelayClient)({
+            relayUrl: `ws://127.0.0.1:${relay.port}`,
+            relayToken: 'tok',
+            sessions,
+            nowFn: () => clock,
+            createBrowserDriver: ({ sessionId }) => {
+                const d = new FakeBrowserDriver();
+                drivers[sessionId] = d;
+                return d;
+            },
+            ...extra,
+        });
+        const ws = await relay.nextConnection();
+        const q = frameQueue(ws);
+        const auth = await q.next();
+        const settle = () => new Promise((r) => setTimeout(r, 20));
+        const open = async (sessionId, url) => {
+            ws.send(JSON.stringify({ t: 'browser-open', sessionId, url }));
+            await settle();
+        };
+        return {
+            relay, handle, ws, q, auth, drivers, open, settle,
+            advance: (ms) => { clock += ms; },
+            done: async () => { handle.close(); await closeRelay(relay.wss); },
+        };
+    }
+    it('advertises its capabilities in the auth frame (and nothing when it has none)', async () => {
+        const withCaps = await boot({ capabilities: ['browser-tabs'] });
+        expect(withCaps.auth).toEqual({ v: 1, relayToken: 'tok', caps: ['browser-tabs'] });
+        await withCaps.done();
+        const without = await boot();
+        expect(without.auth).toEqual({ v: 1, relayToken: 'tok' });
+        await without.done();
+    });
+    it('two pane sessions are two independent tabs: reload and close reach only their own', async () => {
+        const t = await boot();
+        await t.open('browser:c1:pane-a', 'https://a.example');
+        await t.open('browser:c1:pane-b', 'https://b.example');
+        const a = t.drivers['browser:c1:pane-a'];
+        const b = t.drivers['browser:c1:pane-b'];
+        expect(a.startCalls).toEqual(['https://a.example']);
+        expect(b.startCalls).toEqual(['https://b.example']);
+        t.ws.send(JSON.stringify({ t: 'browser-reload', sessionId: 'browser:c1:pane-a' }));
+        await t.settle();
+        expect(a.reloadCalls).toBe(1);
+        expect(b.reloadCalls).toBe(0);
+        t.ws.send(JSON.stringify({ t: 'browser-close', sessionId: 'browser:c1:pane-b' }));
+        await t.settle();
+        expect(b.stopCalls).toBe(1);
+        expect(a.stopCalls).toBe(0);
+        await t.done();
+    });
+    it('at the tab cap, opening one more puts the stalest tab to sleep (tab-evicted)', async () => {
+        const t = await boot({ maxBrowserTabs: 2 });
+        await t.open('browser:c1:p1', 'https://one.example');
+        t.advance(1_000);
+        await t.open('browser:c1:p2', 'https://two.example');
+        t.advance(1_000);
+        // p1 is being watched (an ack) — p2 is now the stalest.
+        t.ws.send(JSON.stringify({ t: 'browser-frame-ack', sessionId: 'browser:c1:p1', seq: 1 }));
+        await t.settle();
+        t.advance(1_000);
+        await t.open('browser:c1:p3', 'https://three.example');
+        expect(t.drivers['browser:c1:p2'].sleepCalls).toEqual(['tab-evicted']);
+        expect(t.drivers['browser:c1:p1'].sleepCalls).toEqual([]);
+        expect(t.drivers['browser:c1:p3'].startCalls).toEqual(['https://three.example']);
+        const evicted = await t.q.next();
+        expect(evicted).toEqual({ t: 'browser-state', sessionId: 'browser:c1:p2', state: 'asleep', reason: 'tab-evicted' });
+        await t.done();
+    });
+});

package/dist/__tests__/bridge-browser-tabs.test.d.ts

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

package/dist/__tests__/bridge-browser-tabs.test.js

@@ -0,0 +1,206 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * cvt-07 — each cloud Browser pane is its own TAB in the box's one browser.
+ *
+ * Two drivers sharing one browserHost.ts against a faked multi-target CDP
+ * endpoint that behaves like Chromium's flattened sessions: every page target
+ * gets its own CDP session id, screencast frames carry that session id, and a
+ * navigation/reload repaints ONLY the target it was sent to.
+ *
+ * docs/prd/canvas-tools.md (module 7) + issues/cvt-07-cloud-browser-tabs.md.
+ */
+const browserDriver_1 = require("../bridge/browserDriver");
+const browserHost_1 = require("../bridge/browserHost");
+class FakeChildProcess {
+    killCount = 0;
+    stderr = { on: () => { } };
+    exitHandlers = [];
+    on(event, cb) {
+        if (event === 'exit')
+            this.exitHandlers.push(cb);
+    }
+    kill() {
+        this.killCount += 1;
+    }
+    emitExit(code, signal = null) {
+        for (const cb of this.exitHandlers)
+            cb(code, signal);
+    }
+}
+/** A fake Chromium DevTools endpoint with real per-target state: which URL
+ *  each page shows, and which CDP session drives which target. */
+class FakeChromium {
+    sent = [];
+    pages = new Map([['page-initial', { url: 'about:blank' }]]);
+    sessions = new Map(); // cdp session id -> target id
+    nextTarget = 1;
+    nextSession = 1;
+    onMessage = null;
+    onCloseCb = null;
+    transport = {
+        send: (data) => {
+            const msg = JSON.parse(data);
+            this.sent.push(msg);
+            const result = this.handle(msg);
+            queueMicrotask(() => this.onMessage?.(JSON.stringify({ id: msg.id, result })));
+        },
+        close: () => {
+            queueMicrotask(() => this.onCloseCb?.(undefined));
+        },
+        on: (event, cb) => {
+            if (event === 'message')
+                this.onMessage = cb;
+            else if (event === 'close')
+                this.onCloseCb = cb;
+        },
+    };
+    handle(msg) {
+        const target = msg.sessionId ? this.sessions.get(msg.sessionId) : undefined;
+        switch (msg.method) {
+            case 'Target.getTargets':
+                return { targetInfos: [...this.pages.keys()].map((targetId) => ({ targetId, type: 'page' })) };
+            case 'Target.createTarget': {
+                const targetId = `page-${this.nextTarget++}`;
+                this.pages.set(targetId, { url: msg.params.url });
+                return { targetId };
+            }
+            case 'Target.attachToTarget': {
+                const sessionId = `cdp-${this.nextSession++}`;
+                this.sessions.set(sessionId, msg.params.targetId);
+                return { sessionId };
+            }
+            case 'Target.closeTarget':
+                this.pages.delete(msg.params.targetId);
+                return { success: true };
+            case 'Page.navigate':
+                if (target)
+                    this.pages.get(target).url = msg.params.url;
+                if (msg.sessionId)
+                    this.repaint(msg.sessionId);
+                return { frameId: 'f' };
+            case 'Page.reload':
+                if (msg.sessionId)
+                    this.repaint(msg.sessionId);
+                return {};
+            case 'Page.captureScreenshot':
+                return { data: `shot:${target ? this.pages.get(target)?.url : '?'}` };
+            default:
+                return {};
+        }
+    }
+    /** Chromium repaints the target a command was sent to — and only it. */
+    repaint(cdpSessionId) {
+        const target = this.sessions.get(cdpSessionId);
+        const url = this.pages.get(target)?.url;
+        queueMicrotask(() => this.onMessage?.(JSON.stringify({
+            method: 'Page.screencastFrame',
+            sessionId: cdpSessionId,
+            params: { sessionId: 1, data: `paint:${url}`, metadata: { deviceWidth: 1280, deviceHeight: 800 } },
+        })));
+    }
+    calls(method) {
+        return this.sent.filter((m) => m.method === method);
+    }
+}
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+function setup() {
+    const chromium = new FakeChromium();
+    const proc = new FakeChildProcess();
+    let launches = 0;
+    const launchChromiumFn = () => {
+        launches += 1;
+        return { proc, wsUrl: Promise.resolve('ws://fake-devtools') };
+    };
+    const host = (0, browserHost_1.createBrowserHost)({ launchChromiumFn, wsFactory: () => chromium.transport });
+    const noTimer = { setIntervalFn: () => 'h', clearIntervalFn: () => { } };
+    const tab = () => {
+        const driver = (0, browserDriver_1.createBrowserDriver)({ host, ...noTimer });
+        const frames = [];
+        driver.onFrame((f) => {
+            frames.push(f);
+            driver.ackFrame();
+        });
+        return { driver, frames };
+    };
+    return { chromium, proc, host, tab, launches: () => launches };
+}
+describe('browser tabs (cvt-07)', () => {
+    it('two panes share ONE Chromium and each gets its own page target', async () => {
+        const { chromium, host, tab, launches } = setup();
+        const a = tab();
+        const b = tab();
+        await Promise.all([a.driver.start('https://a.example'), b.driver.start('https://b.example')]);
+        expect(launches()).toBe(1);
+        expect(host.leaseCount).toBe(2);
+        // The first tab claims Chromium's launch page; the second creates its own.
+        expect(chromium.calls('Target.createTarget')).toHaveLength(1);
+        expect([...chromium.pages.values()].map((p) => p.url).sort()).toEqual(['https://a.example', 'https://b.example']);
+    });
+    it('navigates independently: each pane only ever sees its own site', async () => {
+        const { tab } = setup();
+        const a = tab();
+        const b = tab();
+        await a.driver.start('https://a.example');
+        await b.driver.start('https://b.example');
+        await flush();
+        await a.driver.navigate('https://a.example/next');
+        await flush();
+        expect(a.frames.map((f) => f.data).every((d) => d.includes('a.example'))).toBe(true);
+        expect(b.frames.map((f) => f.data).every((d) => d.includes('b.example'))).toBe(true);
+        expect(a.frames.some((f) => f.data.includes('a.example/next'))).toBe(true);
+    });
+    it('reloading one pane emits no frames for the other', async () => {
+        const { chromium, tab } = setup();
+        const a = tab();
+        const b = tab();
+        await a.driver.start('https://a.example');
+        await b.driver.start('https://b.example');
+        await flush();
+        const aBefore = a.frames.length;
+        const bBefore = b.frames.length;
+        await a.driver.reload();
+        await flush();
+        expect(a.frames.length).toBeGreaterThan(aBefore);
+        expect(b.frames.length).toBe(bBefore);
+        // The reload went to A's CDP session only.
+        const reloads = chromium.calls('Page.reload');
+        expect(reloads).toHaveLength(1);
+        expect(chromium.sessions.get(reloads[0].sessionId)).not.toBe(chromium.sessions.get(chromium.calls('Page.navigate').find((n) => n.params.url === 'https://b.example').sessionId));
+    });
+    it('closing a pane closes only its tab; the last tab closed kills Chromium', async () => {
+        const { chromium, proc, host, tab } = setup();
+        const a = tab();
+        const b = tab();
+        const bStates = [];
+        b.driver.onState((s) => bStates.push(s.state));
+        await a.driver.start('https://a.example');
+        await b.driver.start('https://b.example');
+        a.driver.sleep('closed-by-pane');
+        await flush();
+        expect(proc.killCount).toBe(0);
+        expect(host.leaseCount).toBe(1);
+        expect([...chromium.pages.values()].map((p) => p.url)).toEqual(['https://b.example']);
+        expect(bStates).not.toContain('asleep');
+        expect(bStates).not.toContain('closed');
+        b.driver.stop();
+        expect(proc.killCount).toBe(1);
+        expect(host.leaseCount).toBe(0);
+    });
+    it('a Chromium crash closes every tab, and the next pane relaunches it', async () => {
+        const { proc, tab, launches } = setup();
+        const a = tab();
+        const b = tab();
+        const states = [];
+        a.driver.onState((s) => states.push(`a:${s.state}`));
+        b.driver.onState((s) => states.push(`b:${s.state}`));
+        await a.driver.start('https://a.example');
+        await b.driver.start('https://b.example');
+        proc.emitExit(1);
+        expect(states).toContain('a:closed');
+        expect(states).toContain('b:closed');
+        const c = tab();
+        await c.driver.start('https://c.example');
+        expect(launches()).toBe(2);
+    });
+});

package/dist/bridge/attachmentWriter.d.ts

@@ -0,0 +1,54 @@
+export declare const ATTACHMENTS_DIR: string;
+export declare const MAX_ATTACHMENT_BYTES: number;
+export type ImageExt = 'png' | 'jpg' | 'gif' | 'webp';
+export type AttachmentReason = 'not-image' | 'too-large' | 'no-session' | 'error';
+export type AttachmentResult = {
+    ok: true;
+    path: string;
+    bytes: number;
+} | {
+    ok: false;
+    reason: AttachmentReason;
+};
+/** The image type, read from the bytes themselves — never from the name. */
+export declare function sniffImageExt(buf: Buffer): ImageExt | null;
+/**
+ * A filename stem that is safe on every filesystem AND needs no shell
+ * escaping in a prompt: letters, digits, dot, dash, underscore only; no
+ * leading dot; at most 40 chars; never empty.
+ */
+export declare function safeAttachmentStem(name: string): string;
+export interface AttachmentDeps {
+    mkdirp: (dir: string) => void;
+    exists: (p: string) => boolean;
+    realpath: (p: string) => string;
+    /** Real impl: temp file + rename, so Claude never reads half an image. */
+    writeFileAtomic: (p: string, data: Buffer) => void;
+    now: () => Date;
+    random: () => string;
+}
+export declare const realAttachmentDeps: AttachmentDeps;
+/** Write one image under `<root>/.hiveop/attachments/` and return its absolute path. */
+export declare function writeAttachment(input: {
+    root: string;
+    name: string;
+    dataBase64: string;
+}, deps?: AttachmentDeps): AttachmentResult;
+/** Where a session's attachments go: its project folder, else the bridge user's home. */
+export declare function attachmentRootFor(sessions: {
+    list(): string[];
+    cwdOf(id: string): string | undefined;
+}, sessionId: unknown): string | null;
+/**
+ * The whole `attach-file` frame → `file-attached` reply, shared verbatim by
+ * the local server and the relay client so the two lanes cannot drift.
+ */
+export declare function handleAttachFrame(frame: {
+    rid?: unknown;
+    sessionId?: unknown;
+    name?: unknown;
+    data?: unknown;
+}, sessions: {
+    list(): string[];
+    cwdOf(id: string): string | undefined;
+}, deps?: AttachmentDeps): Record<string, unknown>;

package/dist/bridge/attachmentWriter.js

@@ -0,0 +1,172 @@
+"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.realAttachmentDeps = exports.MAX_ATTACHMENT_BYTES = exports.ATTACHMENTS_DIR = void 0;
+exports.sniffImageExt = sniffImageExt;
+exports.safeAttachmentStem = safeAttachmentStem;
+exports.writeAttachment = writeAttachment;
+exports.attachmentRootFor = attachmentRootFor;
+exports.handleAttachFrame = handleAttachFrame;
+/**
+ * Terminal attach — save a screenshot NEXT TO the agent that will read it.
+ *
+ * Claude Code attaches an image when that image's file path lands in its
+ * prompt. So the browser ships the image bytes over the pane's own socket
+ * (`attach-file` frame — the local bridge's loopback WS, or the relay into the
+ * hosted container; same frame, same handler, both lanes) and this module
+ * writes them into the SESSION's project folder:
+ *
+ *     <session cwd>/.hiveop/attachments/<stamp>-<rand>-<safe-name>.<ext>
+ *
+ * Why there:
+ *   - `.hiveop/` is already the bridge-owned dir inside a checkout
+ *     (`.hiveop/context.md`), excluded from the tree scanner/watcher and from
+ *     the checkout inventory's "unsaved work" count — no new convention.
+ *   - It is inside Claude's cwd, so a follow-up Read of the file needs no
+ *     out-of-project permission prompt on either lane.
+ *   - The attachments dir carries its OWN `.gitignore` (`*`), so an agent's
+ *     `git add -A` never commits screenshots — without editing the user's
+ *     .gitignore.
+ *
+ * The browser's name and type are hints only: the extension comes from the
+ * file's magic bytes, and anything that is not png/jpeg/gif/webp is refused.
+ * The session — never the frame — decides the folder, so a pane can only
+ * write next to a session it may already address.
+ */
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const crypto = __importStar(require("crypto"));
+exports.ATTACHMENTS_DIR = path.join('.hiveop', 'attachments');
+exports.MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/** The image type, read from the bytes themselves — never from the name. */
+function sniffImageExt(buf) {
+    if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])))
+        return 'png';
+    if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff)
+        return 'jpg';
+    if (buf.length >= 6 && (buf.subarray(0, 6).toString('latin1') === 'GIF87a' || buf.subarray(0, 6).toString('latin1') === 'GIF89a'))
+        return 'gif';
+    if (buf.length >= 12 && buf.subarray(0, 4).toString('latin1') === 'RIFF' && buf.subarray(8, 12).toString('latin1') === 'WEBP')
+        return 'webp';
+    return null;
+}
+/**
+ * A filename stem that is safe on every filesystem AND needs no shell
+ * escaping in a prompt: letters, digits, dot, dash, underscore only; no
+ * leading dot; at most 40 chars; never empty.
+ */
+function safeAttachmentStem(name) {
+    const base = String(name ?? '').split(/[\\/]/).pop() ?? '';
+    const stem = base.replace(/\.[A-Za-z0-9]{1,5}$/, '');
+    const cleaned = stem
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/-{2,}/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, 40)
+        .replace(/[-.]+$/g, '');
+    return cleaned || 'image';
+}
+function stamp(now) {
+    const p = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}${p(now.getMonth() + 1)}${p(now.getDate())}-${p(now.getHours())}${p(now.getMinutes())}${p(now.getSeconds())}`;
+}
+exports.realAttachmentDeps = {
+    mkdirp: (dir) => fs.mkdirSync(dir, { recursive: true }),
+    exists: (p) => fs.existsSync(p),
+    realpath: (p) => fs.realpathSync(p),
+    writeFileAtomic: (p, data) => {
+        const tmp = `${p}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+        fs.writeFileSync(tmp, data);
+        fs.renameSync(tmp, p);
+    },
+    now: () => new Date(),
+    random: () => crypto.randomBytes(2).toString('hex'),
+};
+/** Write one image under `<root>/.hiveop/attachments/` and return its absolute path. */
+function writeAttachment(input, deps = exports.realAttachmentDeps) {
+    const b64 = typeof input.dataBase64 === 'string' ? input.dataBase64 : '';
+    // Checked on the ENCODED length first, so an oversized frame is refused
+    // without allocating its decoded buffer.
+    if (b64.length > Math.ceil(exports.MAX_ATTACHMENT_BYTES / 3) * 4 + 4)
+        return { ok: false, reason: 'too-large' };
+    const data = Buffer.from(b64, 'base64');
+    if (data.length > exports.MAX_ATTACHMENT_BYTES)
+        return { ok: false, reason: 'too-large' };
+    const ext = sniffImageExt(data);
+    if (!ext)
+        return { ok: false, reason: 'not-image' };
+    try {
+        const root = deps.realpath(input.root);
+        const dir = path.join(root, exports.ATTACHMENTS_DIR);
+        deps.mkdirp(dir);
+        // A checkout's `.hiveop` could be a symlink planted by the repo — refuse
+        // to follow it anywhere outside the project.
+        const realDir = deps.realpath(dir);
+        if (realDir !== dir && !realDir.startsWith(root + path.sep))
+            return { ok: false, reason: 'error' };
+        const ignore = path.join(realDir, '.gitignore');
+        if (!deps.exists(ignore))
+            deps.writeFileAtomic(ignore, Buffer.from('*\n'));
+        const file = path.join(realDir, `${stamp(deps.now())}-${deps.random()}-${safeAttachmentStem(input.name)}.${ext}`);
+        deps.writeFileAtomic(file, data);
+        return { ok: true, path: file, bytes: data.length };
+    }
+    catch {
+        return { ok: false, reason: 'error' };
+    }
+}
+/** Where a session's attachments go: its project folder, else the bridge user's home. */
+function attachmentRootFor(sessions, sessionId) {
+    if (typeof sessionId !== 'string' || !sessions.list().includes(sessionId))
+        return null;
+    return sessions.cwdOf(sessionId) ?? os.homedir();
+}
+/**
+ * The whole `attach-file` frame → `file-attached` reply, shared verbatim by
+ * the local server and the relay client so the two lanes cannot drift.
+ */
+function handleAttachFrame(frame, sessions, deps = exports.realAttachmentDeps) {
+    const head = {
+        t: 'file-attached',
+        rid: frame.rid,
+        ...(typeof frame.sessionId === 'string' ? { sessionId: frame.sessionId } : {}),
+    };
+    const root = attachmentRootFor(sessions, frame.sessionId);
+    if (!root)
+        return { ...head, ok: false, reason: 'no-session' };
+    const result = writeAttachment({ root, name: typeof frame.name === 'string' ? frame.name : 'image', dataBase64: typeof frame.data === 'string' ? frame.data : '' }, deps);
+    return result.ok ? { ...head, ok: true, path: result.path, bytes: result.bytes } : { ...head, ok: false, reason: result.reason };
+}

package/dist/bridge/browserDriver.d.ts

@@ -37,6 +37,7 @@
  */
 import { ChromiumLaunchHandle } from './chromiumLauncher';
 import { CdpTransportLike } from './cdpClient';
+import type { BrowserHost } from './browserHost';
 import { BrowserInputEvent, BrowserSessionState } from './browserFrames';
 /** container -> pane screencast frame, minus the wire envelope (`t`,
  *  `sessionId`) — the driver doesn't know the relay session id; the caller
@@ -228,6 +229,13 @@ export interface BrowserDriverOpts {
      *  log line (frames delivered, screencast vs capture split, drops) every
      *  N frames processed, never per-frame. Default 50. */
     summaryFrameInterval?: number;
+    /** cvt-07: the box's shared Chromium (browserHost.ts). When set, this
+     *  driver is ONE TAB in that process — it leases the browser connection,
+     *  creates (or claims the spare) page target, and on stop()/sleep() closes
+     *  only its own target; the host kills Chromium when the last tab goes.
+     *  Absent → the pre-cvt-07 behaviour: this driver launches and owns its
+     *  own Chromium (launchChromiumFn/wsFactory above). */
+    host?: BrowserHost;
 }
 /** Default real transport: wraps a `ws` WebSocket connected to the
  *  Chromium DevTools endpoint. Never exercised by tests (they inject

package/dist/bridge/browserDriver.js

@@ -137,6 +137,9 @@ function createBrowserDriver(opts = {}) {
     const summaryFrameInterval = opts.summaryFrameInterval ?? 50;
     let cdp = null;
     let childProc = null;
+    // cvt-07: set only in shared-host (tab) mode — see BrowserDriverOpts.host.
+    let hostLease = null;
+    const unsubscribers = [];
     let pageTargetId = null;
     let targetSessionId = null;
     let seq = 0;
@@ -238,6 +241,19 @@ function createBrowserDriver(opts = {}) {
         if (stopped)
             return;
         stopped = true;
+        // cvt-07: a tab never closes the shared connection or kills the shared
+        // process — it closes its own target and hands its lease back (the host
+        // kills Chromium when the last lease goes).
+        if (opts.host) {
+            for (const off of unsubscribers.splice(0))
+                off();
+            const lease = hostLease;
+            if (lease && pageTargetId) {
+                void lease.cdp.send('Target.closeTarget', { targetId: pageTargetId }).catch(() => { });
+            }
+            lease?.release();
+            return;
+        }
         try {
             cdp?.close();
         }
@@ -299,28 +315,55 @@ function createBrowserDriver(opts = {}) {
     }
     async function start(url) {
         emitState({ state: 'opening' });
-        const { proc, wsUrl } = launchChromiumFn({ chromiumPath, userDataDir, width, height });
-        childProc = proc;
-        proc.on('exit', (code, signal) => {
-            handleClosed(`chromium-exit code=${code ?? 'null'} signal=${signal ?? 'null'}`);
-        });
-        proc.on('error', (err) => {
-            handleClosed(`chromium-error ${err instanceof Error ? err.message : String(err)}`);
-        });
-        const browserWsUrl = await wsUrl;
-        const transport = wsFactory(browserWsUrl);
-        const client = (0, cdpClient_1.createCdpClient)(transport);
-        cdp = client;
-        client.onClose((info) => {
-            handleClosed(info?.reason ? `cdp-closed:${info.reason}` : 'cdp-closed');
-        });
-        client.onEvent('Target.targetInfoChanged', (params) => {
+        let client;
+        if (opts.host) {
+            // cvt-07: one tab in the box's shared Chromium.
+            const lease = await opts.host.acquire();
+            if (stopped) {
+                // stop()/sleep() landed while the lease was being acquired.
+                lease.release();
+                return;
+            }
+            hostLease = lease;
+            client = lease.cdp;
+            cdp = client;
+            lease.onClosed((reason) => handleClosed(reason));
+        }
+        else {
+            const { proc, wsUrl } = launchChromiumFn({ chromiumPath, userDataDir, width, height });
+            childProc = proc;
+            proc.on('exit', (code, signal) => {
+                handleClosed(`chromium-exit code=${code ?? 'null'} signal=${signal ?? 'null'}`);
+            });
+            proc.on('error', (err) => {
+                handleClosed(`chromium-error ${err instanceof Error ? err.message : String(err)}`);
+            });
+            const browserWsUrl = await wsUrl;
+            const transport = wsFactory(browserWsUrl);
+            client = (0, cdpClient_1.createCdpClient)(transport);
+            cdp = client;
+            client.onClose((info) => {
+                handleClosed(info?.reason ? `cdp-closed:${info.reason}` : 'cdp-closed');
+            });
+        }
+        unsubscribers.push(client.onEvent('Target.targetInfoChanged', (params) => {
             const info = params.targetInfo;
             if (!info || !pageTargetId || info.targetId !== pageTargetId)
                 return;
             emitState({ state: 'open', url: info.url, title: info.title });
-        });
-        client.onEvent('Page.screencastFrame', (params) => {
+        }));
+        // cvt-07: the tab itself went away (crash, window.close()) — only THIS
+        // tab is terminal; its siblings in the shared browser are untouched.
+        unsubscribers.push(client.onEvent('Target.detachedFromTarget', (params) => {
+            if (targetSessionId && params.sessionId === targetSessionId)
+                handleClosed('target-detached');
+        }));
+        unsubscribers.push(client.onEvent('Page.screencastFrame', (params, cdpSessionId) => {
+            // cvt-07: on a shared connection every tab's screencast arrives here —
+            // only this tab's frames are ours. (A frame without a session id can
+            // only come from a non-flattened, single-tab connection.)
+            if (cdpSessionId && cdpSessionId !== targetSessionId)
+                return;
             // cbs-14: defensive — Page.stopScreencast (sent by pause()) should
             // already suppress these at the source, but a frame already in
             // flight when we asked Chromium to stop is possible; drop it rather
@@ -346,21 +389,35 @@ function createBrowserDriver(opts = {}) {
                 w: metadata.deviceWidth ?? width,
                 h: metadata.deviceHeight ?? height,
             });
-        });
-        const { targetInfos } = await client.send('Target.getTargets');
-        const existingPage = targetInfos.find((t) => t.type === 'page');
-        if (existingPage) {
-            pageTargetId = existingPage.targetId;
+        }));
+        if (hostLease) {
+            // cvt-07: the first tab claims the page Chromium launched with; every
+            // other tab gets a target of its own.
+            const spare = await hostLease.takeSparePage();
+            pageTargetId = spare ?? (await client.send('Target.createTarget', { url: 'about:blank' })).targetId;
         }
         else {
-            const created = await client.send('Target.createTarget', { url: 'about:blank' });
-            pageTargetId = created.targetId;
+            const { targetInfos } = await client.send('Target.getTargets');
+            const existingPage = targetInfos.find((t) => t.type === 'page');
+            if (existingPage) {
+                pageTargetId = existingPage.targetId;
+            }
+            else {
+                const created = await client.send('Target.createTarget', { url: 'about:blank' });
+                pageTargetId = created.targetId;
+            }
         }
         const attached = await client.send('Target.attachToTarget', {
             targetId: pageTargetId,
             flatten: true,
         });
         targetSessionId = attached.sessionId;
+        if (stopped && hostLease) {
+            // cvt-07: closed while the tab was still being created — teardown()
+            // ran before the target existed, so close it here or it leaks.
+            void client.send('Target.closeTarget', { targetId: pageTargetId }).catch(() => { });
+            return;
+        }
         await client.send('Page.enable', {}, targetSessionId);
         // The launcher's --hide-scrollbars only governs the REAL window; the
         // moment we emulate a viewport (setDeviceMetricsOverride, below/resize)

package/dist/bridge/browserHost.d.ts

@@ -0,0 +1,54 @@
+/**
+ * cvt-07 — the box's ONE headless Chromium, shared by every Browser pane.
+ *
+ * (docs/prd/canvas-tools.md module 7, issues/cvt-07-cloud-browser-tabs.md)
+ * Before cvt-07 each browser driver launched its own Chromium, and the arena
+ * only ever opened one session per box (`browser:<containerId>`), so two
+ * cloud Browser panes fought over one page. Now every Browser pane is its own
+ * relay session (`browser:<containerId>:<paneId>`) and its own TAB (CDP page
+ * target) in this one process: same box, same cost, one profile.
+ *
+ * This module owns only the PROCESS + the browser-level CDP connection,
+ * reference-counted by lease:
+ *   - the first acquire() launches Chromium and connects; concurrent
+ *     acquires during the launch share it;
+ *   - each lease may claim the spare `about:blank` page Chromium starts with
+ *     (so the first tab doesn't leave an idle extra renderer behind);
+ *   - the last release() kills Chromium (exactly what a single driver's
+ *     stop()/sleep() did before — no orphaned process, no idle memory);
+ *   - a Chromium exit / CDP close tells EVERY live lease (each tab goes to
+ *     its terminal state), and the next acquire() relaunches.
+ * Targets, screencasts and input stay in browserDriver.ts — one driver per tab.
+ */
+import { ChromiumLaunchHandle } from './chromiumLauncher';
+import { CdpClient, CdpTransportLike } from './cdpClient';
+export interface BrowserHostLease {
+    cdp: CdpClient;
+    /** Claims the page target Chromium opened at launch, once, for the first
+     *  tab that asks. Null when it is already taken (or there is none) — the
+     *  caller then creates its own target. */
+    takeSparePage(): Promise<string | null>;
+    /** Fires once if the shared process/connection dies under this lease. */
+    onClosed(cb: (reason: string) => void): void;
+    /** Gives the lease back. The last release kills Chromium. Idempotent. */
+    release(): void;
+}
+export interface BrowserHost {
+    acquire(): Promise<BrowserHostLease>;
+    /** Live leases (== open tabs). For tests and the summary log. */
+    readonly leaseCount: number;
+}
+export interface BrowserHostOpts {
+    chromiumPath?: string;
+    userDataDir?: string;
+    width?: number;
+    height?: number;
+    launchChromiumFn?: (opts: {
+        chromiumPath?: string;
+        userDataDir?: string;
+        width?: number;
+        height?: number;
+    }) => ChromiumLaunchHandle;
+    wsFactory: (url: string) => CdpTransportLike;
+}
+export declare function createBrowserHost(opts: BrowserHostOpts): BrowserHost;

package/dist/bridge/browserHost.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserHost = createBrowserHost;
+/**
+ * cvt-07 — the box's ONE headless Chromium, shared by every Browser pane.
+ *
+ * (docs/prd/canvas-tools.md module 7, issues/cvt-07-cloud-browser-tabs.md)
+ * Before cvt-07 each browser driver launched its own Chromium, and the arena
+ * only ever opened one session per box (`browser:<containerId>`), so two
+ * cloud Browser panes fought over one page. Now every Browser pane is its own
+ * relay session (`browser:<containerId>:<paneId>`) and its own TAB (CDP page
+ * target) in this one process: same box, same cost, one profile.
+ *
+ * This module owns only the PROCESS + the browser-level CDP connection,
+ * reference-counted by lease:
+ *   - the first acquire() launches Chromium and connects; concurrent
+ *     acquires during the launch share it;
+ *   - each lease may claim the spare `about:blank` page Chromium starts with
+ *     (so the first tab doesn't leave an idle extra renderer behind);
+ *   - the last release() kills Chromium (exactly what a single driver's
+ *     stop()/sleep() did before — no orphaned process, no idle memory);
+ *   - a Chromium exit / CDP close tells EVERY live lease (each tab goes to
+ *     its terminal state), and the next acquire() relaunches.
+ * Targets, screencasts and input stay in browserDriver.ts — one driver per tab.
+ */
+const chromiumLauncher_1 = require("./chromiumLauncher");
+const cdpClient_1 = require("./cdpClient");
+function createBrowserHost(opts) {
+    const launchChromiumFn = opts.launchChromiumFn ?? chromiumLauncher_1.launchChromium;
+    let running = null;
+    let launching = null;
+    const die = (r, reason) => {
+        if (r.dead)
+            return;
+        r.dead = true;
+        if (running === r)
+            running = null;
+        const leases = [...r.leases];
+        r.leases.clear();
+        for (const l of leases) {
+            l.released = true;
+            for (const cb of l.closedCbs)
+                cb(reason);
+        }
+    };
+    const kill = (r) => {
+        if (r.dead)
+            return;
+        r.dead = true;
+        if (running === r)
+            running = null;
+        try {
+            r.cdp.close();
+        }
+        catch { /* best-effort */ }
+        try {
+            r.proc.kill();
+        }
+        catch { /* best-effort */ }
+    };
+    async function launch() {
+        const { proc, wsUrl } = launchChromiumFn({
+            chromiumPath: opts.chromiumPath,
+            userDataDir: opts.userDataDir,
+            width: opts.width,
+            height: opts.height,
+        });
+        // Registered before awaiting wsUrl so an exit during startup is seen.
+        let r = null;
+        let earlyExit = null;
+        proc.on('exit', (code, signal) => {
+            const reason = `chromium-exit code=${code ?? 'null'} signal=${signal ?? 'null'}`;
+            if (r)
+                die(r, reason);
+            else
+                earlyExit = reason;
+        });
+        proc.on('error', (err) => {
+            const reason = `chromium-error ${err instanceof Error ? err.message : String(err)}`;
+            if (r)
+                die(r, reason);
+            else
+                earlyExit = reason;
+        });
+        const url = await wsUrl;
+        if (earlyExit)
+            throw new Error(earlyExit);
+        const cdp = (0, cdpClient_1.createCdpClient)(opts.wsFactory(url));
+        r = { proc, cdp, spareTaken: false, leases: new Set(), dead: false };
+        const self = r;
+        cdp.onClose((info) => die(self, info?.reason ? `cdp-closed:${info.reason}` : 'cdp-closed'));
+        return r;
+    }
+    async function acquire() {
+        let r = running && !running.dead ? running : null;
+        if (!r) {
+            if (!launching) {
+                launching = launch().finally(() => { launching = null; });
+            }
+            r = await launching;
+            if (r.dead)
+                throw new Error('chromium exited during launch');
+            running = r;
+        }
+        const rec = { closedCbs: [], released: false };
+        r.leases.add(rec);
+        const owner = r;
+        return {
+            cdp: owner.cdp,
+            async takeSparePage() {
+                if (owner.spareTaken || owner.dead)
+                    return null;
+                owner.spareTaken = true;
+                const { targetInfos } = await owner.cdp.send('Target.getTargets');
+                return targetInfos.find((t) => t.type === 'page')?.targetId ?? null;
+            },
+            onClosed(cb) {
+                rec.closedCbs.push(cb);
+            },
+            release() {
+                if (rec.released)
+                    return;
+                rec.released = true;
+                owner.leases.delete(rec);
+                if (owner.leases.size === 0)
+                    kill(owner);
+            },
+        };
+    }
+    return {
+        acquire,
+        get leaseCount() {
+            return running && !running.dead ? running.leases.size : 0;
+        },
+    };
+}

package/dist/bridge/relayClient.d.ts

@@ -27,6 +27,14 @@ export declare const SESSION_NOT_RELAY_OWNED = "SESSION_NOT_RELAY_OWNED";
  * terminal it did not start — the test names each one for the same reason.
  */
 export declare const SESSION_ADDRESSED_FRAMES: ReadonlySet<string>;
+/** cvt-07: what this bridge advertises in its auth frame. `browser-tabs` = a
+ *  distinct browser sessionId is a distinct TAB in one shared Chromium, and
+ *  `browser-close`/`browser-reload` are understood. The relay keeps old
+ *  images (no caps) on the single default session. */
+export declare const BRIDGE_CAP_BROWSER_TABS = "browser-tabs";
+/** cvt-07: max live browser tabs per box — the arena's Browser-pane cap (4
+ *  per canvas). A fifth open evicts the tab nobody has looked at longest. */
+export declare const DEFAULT_MAX_BROWSER_TABS = 4;
 /** pucc-04 workspace-scoped git credential, resolved + injected by the relay. */
 export interface InjectedGitCredential {
     token: string;
@@ -594,6 +602,11 @@ export interface RelayClientOpts {
      *  idempotent pause() calls — see browserDriver.pause()'s doc comment),
      *  so a short cadence costs nothing. Default 5_000ms. */
     browserConsumerCheckIntervalMs?: number;
+    /** cvt-07: capabilities advertised to the relay in the auth frame (e.g.
+     *  BRIDGE_CAP_BROWSER_TABS). Absent → none (the pre-cvt-07 auth frame). */
+    capabilities?: readonly string[];
+    /** cvt-07: max live browser tabs (default DEFAULT_MAX_BROWSER_TABS). */
+    maxBrowserTabs?: number;
     /** Test/observability hooks. */
     onConnect?: () => void;
     /**

package/dist/bridge/relayClient.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_ADDRESSED_FRAMES = exports.SESSION_NOT_RELAY_OWNED = exports.LAUNCH_COMMAND_MISSING = void 0;
+exports.DEFAULT_MAX_BROWSER_TABS = exports.BRIDGE_CAP_BROWSER_TABS = exports.SESSION_ADDRESSED_FRAMES = exports.SESSION_NOT_RELAY_OWNED = exports.LAUNCH_COMMAND_MISSING = void 0;
 exports.assembleSessionEnv = assembleSessionEnv;
 exports.formatHealthLine = formatHealthLine;
 exports.formatDisconnectLine = formatDisconnectLine;
@@ -110,6 +110,7 @@ const diskPreflight_1 = require("./diskPreflight");
 // hcs-05's checkoutReclaim executor for the actual delete. See
 // checkoutParkAndRemove.ts's doc comment for the full safety design.
 const checkoutParkAndRemove_1 = require("./checkoutParkAndRemove");
+const attachmentWriter_1 = require("./attachmentWriter");
 const PROTOCOL_VERSION = 1;
 /**
  * fcct-27 — typed refusal when `resolveLaunch` names a binary this machine does
@@ -133,7 +134,18 @@ exports.SESSION_NOT_RELAY_OWNED = 'SESSION_NOT_RELAY_OWNED';
 exports.SESSION_ADDRESSED_FRAMES = new Set([
     'attach', 'input', 'peek', 'resize', 'detach', 'close', 'read-handoff',
     'browser-input', 'browser-frame-ack', 'browser-resize', 'browser-sleep',
+    // Terminal attach writes next to a session — same consent boundary.
+    'attach-file',
+    'browser-close', 'browser-reload',
 ]);
+/** cvt-07: what this bridge advertises in its auth frame. `browser-tabs` = a
+ *  distinct browser sessionId is a distinct TAB in one shared Chromium, and
+ *  `browser-close`/`browser-reload` are understood. The relay keeps old
+ *  images (no caps) on the single default session. */
+exports.BRIDGE_CAP_BROWSER_TABS = 'browser-tabs';
+/** cvt-07: max live browser tabs per box — the arena's Browser-pane cap (4
+ *  per canvas). A fifth open evicts the tab nobody has looked at longest. */
+exports.DEFAULT_MAX_BROWSER_TABS = 4;
 /**
  * pucc-14 — assemble the per-session PTY env for a workspace-scoped `open`.
  *
@@ -504,6 +516,29 @@ function startRelayClient(opts) {
     function sleepBrowserSession(sessionId, reason) {
         browserDrivers.get(sessionId)?.sleep(reason);
     }
+    /** cvt-07: before opening one more tab at the cap, put the tab with the
+     *  stalest consumer signal to sleep (its pane shows asleep + Wake). */
+    function evictBrowserTabIfFull() {
+        const max = opts.maxBrowserTabs ?? exports.DEFAULT_MAX_BROWSER_TABS;
+        while (browserDrivers.size >= max) {
+            let victim = null;
+            let oldest = Infinity;
+            for (const sid of browserDrivers.keys()) {
+                const at = browserLastConsumerAt.get(sid) ?? -Infinity;
+                if (at < oldest) {
+                    oldest = at;
+                    victim = sid;
+                }
+            }
+            if (!victim)
+                return;
+            sleepBrowserSession(victim, 'tab-evicted');
+            // A driver whose sleep didn't retire it synchronously must not wedge
+            // this loop.
+            if (browserDrivers.has(victim))
+                browserDrivers.delete(victim);
+        }
+    }
     // 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
@@ -834,7 +869,11 @@ function startRelayClient(opts) {
         };
         socket.on('pong', markLinkAlive);
         socket.on('open', () => {
-            send(socket, { v: PROTOCOL_VERSION, relayToken: opts.relayToken });
+            send(socket, {
+                v: PROTOCOL_VERSION,
+                relayToken: opts.relayToken,
+                ...(opts.capabilities?.length ? { caps: [...opts.capabilities] } : {}),
+            });
             connected = true;
             startHeartbeat();
             // twr-06: `attempt` reset + `onConnect` moved OFF this handler — the
@@ -1501,6 +1540,10 @@ function startRelayClient(opts) {
                         });
                         break;
                     }
+                    case 'attach-file':
+                        // Terminal attach — shared verbatim with the local server.
+                        send(socket, (0, attachmentWriter_1.handleAttachFrame)(frame, opts.sessions));
+                        break;
                     case 'read-transcript': {
                         // wte-10 (docs/prd/work-this-epic.md D8): read ONE Claude Code
                         // agent's session transcript, live. Server-initiated (no pane,
@@ -1588,6 +1631,7 @@ function startRelayClient(opts) {
                             }
                             break;
                         }
+                        evictBrowserTabIfFull(); // cvt-07
                         const driver = opts.createBrowserDriver({ sessionId });
                         browserDrivers.set(sessionId, driver);
                         browserDriverUrls.set(sessionId, url);
@@ -1721,6 +1765,21 @@ function startRelayClient(opts) {
                         // the map by the first sleep's onState handler above).
                         sleepBrowserSession(frame.sessionId, 'sleep');
                         break;
+                    case 'browser-close':
+                        // cvt-07: the pane was closed — close its tab (stop(): terminal
+                        // 'closed', and in shared-host mode only this target goes; the
+                        // host kills Chromium when the last tab closes). Safe no-op for
+                        // an unknown session.
+                        browserDrivers.get(frame.sessionId)?.stop();
+                        break;
+                    case 'browser-reload':
+                        // cvt-07: reload exactly this tab. A live consumer asked, so it
+                        // also counts as one (and un-pauses capture to show the result).
+                        if (browserLastConsumerAt.has(frame.sessionId))
+                            browserLastConsumerAt.set(frame.sessionId, now());
+                        browserDrivers.get(frame.sessionId)?.resume().catch(() => { });
+                        browserDrivers.get(frame.sessionId)?.reload().catch(() => { });
+                        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.js

@@ -62,6 +62,7 @@ const sessionAnchor_1 = require("./sessionAnchor");
 // tchp-30 — per-session own-touch tracker (see its doc comment). Fed from
 // the SAME activity records fcct-24's tail already parses below.
 const sessionTouchTracker_1 = require("./sessionTouchTracker");
+const attachmentWriter_1 = require("./attachmentWriter");
 const PROTOCOL_VERSION = 1;
 function send(ws, frame) {
     if (ws.readyState === ws_1.WebSocket.OPEN)
@@ -389,6 +390,8 @@ function startBridgeServer(opts) {
                 // of failing at save time.
                 capabilities: [
                     ...(opts.writeLocalFile ? ['local-file-write'] : []),
+                    // Terminal attach — this bridge answers `attach-file` frames.
+                    'terminal-attach',
                 ],
             });
             return;
@@ -930,6 +933,11 @@ function startBridgeServer(opts) {
                         });
                         break;
                     }
+                    case 'attach-file':
+                        // Terminal attach — a FILE write next to the session, never PTY
+                        // input. Shared handler with relayClient.ts (both lanes).
+                        send(ws, (0, attachmentWriter_1.handleAttachFrame)(frame, opts.sessions));
+                        break;
                     default:
                         send(ws, { t: 'error', message: 'unknown frame type' });
                 }

package/dist/commands/bridge.js

@@ -63,6 +63,7 @@ const sessionManager_1 = require("../bridge/sessionManager");
 const server_1 = require("../bridge/server");
 const relayClient_1 = require("../bridge/relayClient");
 const browserDriver_1 = require("../bridge/browserDriver");
+const browserHost_1 = require("../bridge/browserHost");
 const browserIdle_1 = require("../bridge/browserIdle");
 const loginStatus_1 = require("../bridge/loginStatus");
 const realPty_1 = require("../bridge/realPty");
@@ -571,6 +572,8 @@ exports.bridgeCommand = new commander_1.Command('bridge')
             // does not).
             rm: rmCheckoutDir,
         });
+        // cvt-07: the box's one shared Chromium, created lazily by the first tab.
+        let browserHost;
         (0, relayClient_1.startRelayClient)({
             relayUrl: relayMode.relayUrl,
             relayToken: relayMode.relayToken,
@@ -866,10 +869,18 @@ exports.bridgeCommand = new commander_1.Command('bridge')
             // either way. An old image without Chromium (or any other launch
             // failure) therefore degrades to "that one browser session failed to
             // open" — never a bridge crash, never a broken terminal pane.
+            //
+            // cvt-07: every browser session is a TAB in ONE shared Chromium
+            // (browserHost.ts) — one process, one profile, launched by the first
+            // tab and killed when the last one closes. Advertised to the relay as
+            // BRIDGE_CAP_BROWSER_TABS below so it may give each Browser pane its
+            // own session.
             createBrowserDriver: () => {
                 const { chromiumPath, userDataDir } = buildBrowserDriverOptions();
-                return (0, browserDriver_1.createBrowserDriver)({ chromiumPath, userDataDir });
+                browserHost ??= (0, browserHost_1.createBrowserHost)({ chromiumPath, userDataDir, wsFactory: (u) => (0, browserDriver_1.createDefaultTransport)(u) });
+                return (0, browserDriver_1.createBrowserDriver)({ chromiumPath, userDataDir, host: browserHost });
             },
+            capabilities: [relayClient_1.BRIDGE_CAP_BROWSER_TABS],
             // bws-08 — the companion port forwarder (docs/prd/
             // browser-with-sound-in-the-container.md D10). Constructed ONCE,
             // same injection posture as createBrowserDriver above: relayClient.ts

package/package.json

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