@deepseek-insight/dsi 0.10.2 → 0.11.1

package/README.md

@@ -79,20 +79,64 @@ One "floor" is a pair: **DSH** (the harness host) and **DSI** (the page you watc
 
 | What | Default | How to move it | Plain meaning |
 |---|---|---|---|
-| DSH host | `3080` | `--port <n>` | the harness brain of the floor |
-| DSI page | `5174` | `PORT=<n>` env var | the page you open in the browser |
-| Browser brain | `9515` | `DSI_MCP_PORT=<n>` env var | the MCP endpoint agents use to drive the glass browser |
+| DSH host | `3080` | `--port <n>` or `DSH_PORT=<n>` env var (flag wins) | the harness brain of the floor |
+| DSI page | `5174` | `DSI_PORT=<n>` env var | the page you open in the browser |
+| Browser brain | `9515` | `GLASS_PORT=<n>` env var | the MCP endpoint agents use to drive the glass browser |
+| Glass chassis | *(this machine)* | `GLASS_CHASSIS_URL=<url>` env var | where Shift+click births its visible window — unset means right here |
 
 **The browser brain.** By default the glass browser's assistant (the MCP brain that lets an agent click and type in the browser) runs as its **own separate helper process** — if it fails, you lose only the glass panel. Adding `--playwright-mcp` moves that brain **inside the DSI page server**: one less background process and a faster start, but a brain failure can now touch the page server itself. DSI prints a banner saying so whenever you use the flag — drop the flag to go back to the helper process.
 
 **Example — a second, self-contained floor beside a live one** (nothing on the running floor is touched):
 
 ```bash
-PORT=5176 DSI_MCP_PORT=19515 npx @deepseek-insight/dsi@latest dsh --sync --playwright-mcp --port 3081
+DSI_PORT=5176 DSH_PORT=3081 GLASS_PORT=19515 npx @deepseek-insight/dsi@latest dsh --sync --playwright-mcp
 # Page: http://localhost:5176 · host: 3081 · brain: http://127.0.0.1:19515/sse
 ```
 
-**Second floors are fully drivable.** At boot, a floor stamps its own addresses (`DSI_UI`, `DSI_MCP_URL`) into everything it starts — so agents in *that* floor's conversations drive *that* floor's glass automatically, and the preset brain entry follows the stamped port. Nothing on the primary floor changes: without a stamp (a bare `dsh web` boot), the brain falls back to `9515` and the drivers probe `5175` → `5174` exactly as before. One conversation = one glass owner; the driver refuses to touch another conversation's glass, and a session busy in the live floor shows `writer-held` if you try to prompt it from the second window (watch it there, prompt it on its own floor).
+**DSI in a VM, Glass on the host.** Run DSI/DSH inside OrbStack (or any VM) while
+the Glass brain stays on your Mac — that is where the headed glass can be seen
+(Shift+Click opens a visible Playwright window, and only the host display can
+show one). The VM floor boots **brain-less** (no brain flag — never spawn a
+second, invisible brain) and exports `GLASS_BRAIN_URL` pointing at the host;
+OrbStack exposes the Mac to its VMs at `host.internal`:
+
+```bash
+# inside the VM — floor lives here, brain dials the host
+DSI_PORT=5171 DSH_PORT=3081 GLASS_BRAIN_URL=http://host.internal:9515/sse npx @deepseek-insight/dsi@latest dsh --sync
+```
+
+```mermaid
+sequenceDiagram
+  participant M as host Mac
+  participant V as VM floor (OrbStack)
+  participant G as Glass brain (host 9515)
+  M->>M: dsi dsh --sync with the brain flag — Glass lives here
+  V->>V: dsi dsh --sync brain-less with GLASS_BRAIN_URL exported
+  V->>G: preset dials the host stamp
+  G->>G: Shift+Click opens a HEADED window on the host display
+  V->>G: tabs, panels, viewport — driven over the wire
+```
+
+```mermaid
+flowchart TD
+  A[floor boots] --> B{GLASS_BRAIN_URL exported?}
+  B -- yes --> C[dial that address — VM floor, host brain]
+  B -- no --> D[dial 127.0.0.1:GLASS_PORT — same machine]
+  C --> E[headed glass opens where the brain runs]
+  D --> E
+```
+
+**Second floors are fully drivable.** At boot, a floor stamps its own addresses (`DSI_UI`, `GLASS_BRAIN_URL`) into everything it starts — so agents in *that* floor's conversations drive *that* floor's glass automatically, and the preset brain entry follows the stamped port. Nothing on the primary floor changes: without a stamp (a bare `dsh web` boot), the brain falls back to `9515` and the drivers probe `5175` → `5174` exactly as before. One conversation = one glass owner; the driver refuses to touch another conversation's glass, and a session busy in the live floor shows `writer-held` if you try to prompt it from the second window (watch it there, prompt it on its own floor).
+
+**Two glass addresses: brain vs chassis.** The glass has two halves and each has its own stamp. The **brain** (`GLASS_BRAIN_URL`) is where *agents* dial in — the MCP endpoint. The **chassis** (`GLASS_CHASSIS_URL`) is where a Shift+click's *visible window* is born. By default both are "this machine" and nothing changes. When DSI runs on a machine with no screen (a VM) but your screens live on the host, stamp the chassis at the host and the window opens where you are looking:
+
+```bash
+# in the VM — the window is born on the host, the panel mirrors it
+node bin/dsi-chassis.mjs --bind 192.168.1.9 --port 9525   # on the HOST: the chassis companion
+DSI_PORT=5171 DSH_PORT=3081 GLASS_CHASSIS_URL=http://192.168.1.9:9525 pnpm dsi dsh --sync
+```
+
+The host-side **companion** (`dsi-chassis`) births each Shift+click glass on a fresh disposable profile — never your real Chrome profile — enforces the same one-conversation-one-glass rule on its side, binds only the address you name (never all interfaces), and bridges CDP back to the floor. When the stamp is set and the companion is down, the panel says so honestly instead of silently falling back to a screenless local launch; unset the stamp and every floor behaves exactly as before.
 
 ## License
 

package/bin/dsi-chassis.mjs

@@ -0,0 +1,371 @@
+#!/usr/bin/env node
+/**
+ * dsi-chassis — the host companion (ADR-0054 D3/D4, spec 2026-11-08 Glass
+ * Chassis Remote CDP task 1.1).
+ *
+ * A small helper that runs on the machine the operator's SCREENS are on.
+ * A floor whose launcher stamped GLASS_CHASSIS_URL at this process asks it
+ * to birth the headed glass THERE, by the house rules:
+ *   - disposable profiles only (the Borrowed Chrome posture — the host's
+ *     real Chrome profile is never mounted, read, or deletable);
+ *   - one conversation = one glass, enforced HERE (ownership survives the
+ *     machine boundary; a busy owner is refused with the writer-held
+ *     contract);
+ *   - it binds ONLY the interface address given via the required --bind
+ *     flag, never 0.0.0.0 (D4);
+ *   - it owns Chrome's debugging port and speaks clean CDP to the floor —
+ *     HTTP endpoints are proxied with the Host header rewritten, JSON
+ *     responses have their webSocketDebuggerUrl rewritten to route back
+ *     through the companion, and websocket upgrades are raw-piped (this
+ *     is the loopback/Host-header hop, ADR fact 7).
+ *
+ * The birth rules (profile naming, owner marker, pid-of-port) come from
+ * src/lib/server/browser/chassis-shared.ts — the SAME module the floor's
+ * registry imports; plain node strips the types natively (Node >= 23.6).
+ *
+ * Wire:
+ *   POST /open   { width, height, ownerSessionId } -> { id, cdpTarget, pid, profileDir }
+ *                  409 { error: 'BUSY' } when ownerSessionId already holds a glass
+ *   POST /close  { id } (or { pid } / { profileDir }) -> { ok }
+ *   GET  /status -> { bind, port, glasses: [...] }
+ *   /cdp/<id>/...  CDP bridge (HTTP + websocket upgrade) to that glass
+ *
+ * Run:  node bin/dsi-chassis.mjs --bind 192.168.1.9 [--port 9560]
+ */
+import { createServer, request as httpRequest } from 'node:http';
+import { connect as netConnect } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, rmSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+import {
+	disposableProfilePath,
+	pidOfPort,
+	writeOwnerMarker
+} from '../src/lib/server/browser/chassis-shared.ts';
+
+/** The companion's disposable root — the same default the floor config
+ *  ships (insight-config). The companion runs on the host and answers to
+ *  the Borrowed Chrome posture, so deletes are GUARDED to this root. */
+const PROFILE_ROOT = join(homedir(), '.dsi', 'browser-profiles');
+
+/** D4 — the bind verdict. Pure: `--bind` is REQUIRED and 0.0.0.0 (and the
+ *  IPv6 all-interfaces '::') are refused. The stamp already names the
+ *  exact interface; bind-all buys nothing and invites every device. */
+export function resolveBind(bind) {
+	if (bind === undefined || bind === '') {
+		return { ok: false, error: 'dsi-chassis: --bind <addr> is required (the private interface from the GLASS_CHASSIS_URL stamp); refusing to guess' };
+	}
+	if (bind === '0.0.0.0' || bind === '::' || bind === '[::]') {
+		return { ok: false, error: 'dsi-chassis: refusing 0.0.0.0 — bind the ONE private interface from the stamp (ADR-0054 D4)' };
+	}
+	return { ok: true, addr: bind };
+}
+
+/** CLI arg parsing — pure, so the pins drive it directly. */
+export function parseArgs(argv) {
+	const out = { bind: undefined, port: undefined };
+	for (let i = 0; i < argv.length; i += 1) {
+		const a = argv[i];
+		if (a === '--bind') { out.bind = argv[i + 1]; i += 1; }
+		else if (a.startsWith('--bind=')) out.bind = a.slice('--bind='.length);
+		else if (a === '--port') { out.port = Number(argv[i + 1]); i += 1; }
+		else if (a.startsWith('--port=')) out.port = Number(a.slice('--port='.length));
+	}
+	return out;
+}
+
+/** A free port for Chrome's debugging listener — net probe, no lsof
+ *  dependency, same behavior on macOS and Linux hosts. */
+async function freeChassisPort(preferred) {
+	const { createServer: probeServer } = await import('node:net');
+	const tryBind = (port) =>
+		new Promise((resolve) => {
+			const s = probeServer();
+			s.once('error', () => resolve(false));
+			s.once('listening', () => s.close(() => resolve(true)));
+			s.listen(port, '127.0.0.1');
+		});
+	if (preferred && (await tryBind(preferred))) return preferred;
+	for (let p = 9520; p < 9620; p += 1) if (await tryBind(p)) return p;
+	throw new Error('dsi-chassis: no free debugging port in 9520..9619');
+}
+
+/** The REAL launcher: headed Chromium on a disposable profile via the
+ *  repo's pinned playwright-core, channel 'chrome' with the bundled
+ *  chromium fallback — the same posture registry.open() births with. */
+async function defaultLaunch({ profileDir, args, headless, width, height }) {
+	const { chromium } = await import('playwright-core');
+	const ignoreDefaultArgs = ['--enable-automation', '--mute-audio', '--hide-scrollbars'];
+	// headless honors the floor's plain-click contract (no OS window); only
+	// the Shift+click headed open passes false (ADR-0054 D2 — the chassis
+	// exists so a HEADED glass can be born where the screens are).
+	// Anti-bot parity (registry's PLAIN_IDENTITY posture): a headless birth
+	// must not advertise HeadlessChrome — Google captcha'd the first VM-floor
+	// plain click on 2026-11-08 while the host floor's spoofed glass passed.
+	const identity = headless === true
+		? { userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36' }
+		: {};
+	// Viewport parity (ADR-0041's local contract, carried across the machine
+	// boundary): HEADED is window-driven — viewport null so the page tracks
+	// Browser.setWindowBounds. HEADLESS has no OS window: pin the viewport to
+	// the requested box (no +6/+70 chassis padding — that pads OS title bars,
+	// and a headless glass has none) or the mirror is cut off at the bottom
+	// (live witness 2026-11-08: VM plain click vs host panel box).
+	const viewport = headless === true
+		? { defaultViewport: { width: Number(width) || 730, height: Number(height) || 830 } }
+		: { defaultViewport: null };
+	let context;
+	try {
+		context = await chromium.launchPersistentContext(profileDir, { channel: 'chrome', headless: headless === true, ignoreDefaultArgs, ...identity, ...viewport, args });
+	} catch {
+		context = await chromium.launchPersistentContext(profileDir, { headless: headless === true, ignoreDefaultArgs, ...identity, ...viewport, args });
+	}
+	const port = Number(args.find((a) => a.startsWith('--remote-debugging-port='))?.split('=')[1]);
+	const pid = pidOfPort(port);
+	return {
+		pid,
+		port,
+		close: async () => { await context.close(); }
+	};
+}
+
+/**
+ * Start the companion. `launch` is injectable so the pins can drive the
+ * whole open/close/ownership/bridge contract without a real Chromium.
+ * Returns { server, port, glasses, stop }.
+ */
+export async function startChassisCompanion(opts = {}) {
+	const bindVerdict = resolveBind(opts.bind);
+	if (!bindVerdict.ok) throw new Error(bindVerdict.error);
+	const bind = bindVerdict.ok ? bindVerdict.addr : undefined;
+	const launch = opts.launch ?? defaultLaunch;
+	const portFor = opts.portFor ?? freeChassisPort;
+	// Injectable for the pins (and a VM host may relocate the root); the
+	// default stays the Borrowed Chrome root. Deletes are GUARDED to THIS
+	// root — the guard is a PATH check, never a flag (the borrowed-wipe RCA).
+	const profileRoot = opts.profileRoot ?? PROFILE_ROOT;
+
+	// The ownership registry lives IN this process: one conversation = one
+	// glass, keyed by the requesting floor's ownerSessionId (karpathy edge
+	// case: two floors stamping the same companion each carry their own id).
+	const glasses = new Map(); // id -> glass
+	const byOwner = new Map(); // ownerSessionId -> id
+
+	const server = createServer(async (req, res) => {
+		try {
+			const url = new URL(req.url ?? '/', 'http://' + (req.headers.host ?? bind));
+			// --- the CDP bridge: /cdp/<id>/... proxies to that glass's port ---
+			const cdp = url.pathname.match(/^\/cdp\/([^/]+)(\/.*)$/);
+			if (cdp) {
+				const glass = glasses.get(cdp[1]);
+				if (!glass) { res.statusCode = 404; res.end('unknown glass'); return; }
+				const headers = { ...req.headers, host: '127.0.0.1:' + glass.debugPort };
+				const preq = httpRequest({ host: '127.0.0.1', port: glass.debugPort, path: cdp[2] + url.search, method: req.method, headers }, (pres) => {
+					const ctype = String(pres.headers['content-type'] ?? '');
+					if (ctype.includes('json')) {
+						const chunks = [];
+						pres.on('data', (c) => chunks.push(c));
+						pres.on('end', () => {
+							// Rewrite the advertised debugger urls to route back
+							// through THIS companion — the floor never needs to know
+							// Chrome's loopback port (ADR fact 7, the Host hop).
+							const body = Buffer.concat(chunks).toString('utf8')
+								.split('ws://127.0.0.1:' + glass.debugPort).join('ws://' + (req.headers.host ?? bind + ':' + glass.boundPort) + '/cdp/' + glass.id);
+							const headers = { ...pres.headers };
+							delete headers['transfer-encoding'];
+							res.writeHead(pres.statusCode ?? 200, { ...headers, 'content-length': Buffer.byteLength(body) });
+							res.end(body);
+						});
+						return;
+					}
+					res.writeHead(pres.statusCode ?? 200, pres.headers);
+					pres.pipe(res);
+				});
+				preq.on('error', () => { try { res.statusCode = 502; res.end('cdp bridge down'); } catch { /* gone */ } });
+				req.pipe(preq);
+				return;
+			}
+			if (req.method === 'GET' && url.pathname === '/status') {
+				res.writeHead(200, { 'content-type': 'application/json' });
+				res.end(JSON.stringify({
+					bind,
+					port: glassPort(server),
+					glasses: [...glasses.values()].map((g) => ({ id: g.id, ownerSessionId: g.ownerSessionId, pid: g.pid, profileDir: g.profileDir }))
+				}));
+				return;
+			}
+			if (req.method === 'POST' && url.pathname === '/open') {
+				const chunks = [];
+				for await (const c of req) chunks.push(c);
+				let body;
+				try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { body = {}; }
+				const ownerSessionId = typeof body.ownerSessionId === 'string' ? body.ownerSessionId : '';
+				if (!ownerSessionId) {
+					res.writeHead(400, { 'content-type': 'application/json' });
+					res.end(JSON.stringify({ error: 'BAD_REQUEST', message: 'ownerSessionId is required — ownership is keyed by the requesting conversation' }));
+					return;
+				}
+				// Writer-held, enforced HERE (D3): a busy owner is refused, and
+				// the refusal is HONEST — the floor surfaces it, no fallback.
+				if (byOwner.has(ownerSessionId)) {
+					res.writeHead(409, { 'content-type': 'application/json' });
+					res.end(JSON.stringify({ error: 'BUSY', message: 'writer-held: owner session ' + ownerSessionId + ' already holds a glass on this chassis' }));
+					return;
+				}
+				const id = crypto.randomUUID();
+				const profileDir = disposableProfilePath(profileRoot, id);
+				mkdirSync(profileDir, { recursive: true });
+				writeOwnerMarker(profileDir); // shared birth rule — the sweep contract holds on the host too
+				const debugPort = await portFor(opts.debugPort);
+				const width = Math.max(200, Math.min(1920, Number(body.width) || 730));
+				const height = Math.max(120, Math.min(1080, Number(body.height) || 830));
+				const args = [
+					'--no-first-run',
+					'--remote-debugging-port=' + debugPort,
+					'--disable-dev-shm-usage',
+					'--disable-renderer-backgrounding',
+					'--disable-background-timer-throttling',
+					'--disable-backgrounding-occluded-windows',
+					'--disable-blink-features=AutomationControlled',
+					'--autoplay-policy=no-user-gesture-required',
+					'--window-size=' + (width + 6) + ',' + (height + 70)
+				];
+				const born = await launch({ profileDir, args, headless: body.headless === true, width, height }).catch((e) => {
+					// a failed birth must not leave a profile dir behind (and the
+					// error rides the honest 500 to the floor's panel)
+					try { if (profileDir.startsWith(profileRoot)) rmSync(profileDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+					throw e;
+				});
+				const glass = {
+					id,
+					ownerSessionId,
+					debugPort,
+					pid: born.pid ?? null,
+					profileDir,
+					close: born.close
+				};
+				glasses.set(id, glass);
+				byOwner.set(ownerSessionId, id);
+				res.writeHead(200, { 'content-type': 'application/json' });
+				// The cdpTarget routes THROUGH this companion (the bridge above) —
+				// the floor attaches its relay to this URL, never to Chrome raw.
+				// Root it at the address the floor DIALED (the request's Host
+				// header — same idiom as the ws rewrite in the bridge): `bind`
+				// is often 127.0.0.1, which only means "this machine" to the
+				// HOST — to a remote floor (VM over the OrbStack bridge) it is
+				// the wrong machine and connectOverCDP dials itself (witness
+				// 2026-11-08: ECONNREFUSED 127.0.0.1:9525 from the VM floor).
+				const dialHost = req.headers.host ?? (bind + ':' + glassPort(server));
+				res.end(JSON.stringify({ id, cdpTarget: 'http://' + dialHost + '/cdp/' + id, pid: glass.pid, profileDir }));
+				return;
+			}
+			if (req.method === 'POST' && url.pathname === '/close') {
+				const chunks = [];
+				for await (const c of req) chunks.push(c);
+				let body;
+				try { body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}'); } catch { body = {}; }
+				// Karpathy edge case: the companion may have restarted, so a
+				// glass is closable by id, pid, or profileDir — not id alone.
+				const glass = glasses.get(String(body.id ?? ''))
+					?? [...glasses.values()].find((g) => (body.pid !== undefined && g.pid === body.pid) || (body.profileDir !== undefined && g.profileDir === body.profileDir));
+				if (!glass) {
+					res.writeHead(404, { 'content-type': 'application/json' });
+					res.end(JSON.stringify({ error: 'NO_GLASS', message: 'no such glass on this chassis' }));
+					return;
+				}
+				await releaseGlass(glass);
+				res.writeHead(200, { 'content-type': 'application/json' });
+				res.end(JSON.stringify({ ok: true }));
+				return;
+			}
+			res.statusCode = 404;
+			res.end();
+		} catch (e) {
+			// Honest failure: a birth or close that throws is a 500 with the
+			// reason — the floor's panel surfaces it verbatim (no fallback).
+			try {
+				res.writeHead(500, { 'content-type': 'application/json' });
+				res.end(JSON.stringify({ error: 'CHASSIS_FAILED', message: e instanceof Error ? e.message : String(e) }));
+			} catch { /* client gone */ }
+		}
+	});
+
+	function releaseGlass(glass) {
+		glasses.delete(glass.id);
+		if (byOwner.get(glass.ownerSessionId) === glass.id) byOwner.delete(glass.ownerSessionId);
+		return (async () => {
+			try { await glass.close(); } catch { /* already dead */ }
+			try { if (glass.pid) process.kill(glass.pid, 'SIGKILL'); } catch { /* already dead */ }
+			// Borrowed Chrome: deletes are GUARDED to the disposable root.
+			if (glass.profileDir.startsWith(profileRoot)) rmSync(glass.profileDir, { recursive: true, force: true });
+		})();
+	}
+
+	const upgrade = (req, socket, head) => {
+		const m = (req.url ?? '').match(/^\/cdp\/([^/]+)(\/devtools\/.*)$/);
+		if (!m) { socket.destroy(); return; }
+		const glass = glasses.get(m[1]);
+		if (!glass) { socket.destroy(); return; }
+		// Raw pipe to Chrome's loopback port; the Host header is rewritten —
+		// recent Chrome validates it (ADR fact 7) and the companion is the hop.
+		const headers = [];
+		const raw = req.rawHeaders;
+		for (let i = 0; i < raw.length; i += 2) {
+			headers.push(raw[i] + ': ' + (raw[i].toLowerCase() === 'host' ? '127.0.0.1:' + glass.debugPort : raw[i + 1]));
+		}
+		const upstream = netConnect(glass.debugPort, '127.0.0.1', () => {
+			upstream.write(req.method + ' ' + m[2] + ' HTTP/1.1\r\n' + headers.join('\r\n') + '\r\n\r\n');
+			if (head?.length) upstream.write(head);
+			socket.pipe(upstream);
+			upstream.pipe(socket);
+		});
+		const fail = () => { socket.destroy(); upstream.destroy(); };
+		upstream.on('error', fail);
+		socket.on('error', fail);
+	};
+	server.on('upgrade', upgrade);
+
+	const wanted = opts.port ?? 9560;
+	const boundPort = await new Promise((res, rej) => {
+		server.once('error', rej);
+		server.listen(wanted, bind, () => {
+			const a = server.address();
+			res(typeof a === 'object' && a ? a.port : wanted);
+		});
+	});
+	return {
+		server,
+		port: boundPort,
+		glasses,
+		stop: async () => {
+			server.removeAllListeners('upgrade');
+			for (const g of [...glasses.values()]) await releaseGlass(g);
+			await new Promise((res) => server.close(() => res()));
+		}
+	};
+}
+
+function glassPort(server) {
+	const a = server.address();
+	return typeof a === 'object' && a ? a.port : 0;
+}
+
+// ---- direct run: parse CLI, resolve bind, start, stay up --------------------
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+	const { bind, port } = parseArgs(process.argv.slice(2));
+	const verdict = resolveBind(bind);
+	if (!verdict.ok) {
+		console.error(verdict.error);
+		process.exit(1);
+	}
+	startChassisCompanion({ bind: verdict.addr, port })
+		.then((c) => {
+			console.log('dsi-chassis: listening on ' + verdict.addr + ':' + c.port + ' (stamp me as GLASS_CHASSIS_URL=http://' + verdict.addr + ':' + c.port + ')');
+		})
+		.catch((e) => {
+			console.error('dsi-chassis: ' + (e instanceof Error ? e.message : String(e)));
+			process.exit(1);
+		});
+}

package/bin/dsi.mjs

@@ -83,15 +83,21 @@ const USAGE = [
 	'',
 	'  Ports: `dsi dsh --sync` serves the DSI page on 5174 and opens your',
 	'  browser there. With --dev the Vite dev server takes 5175 instead',
-	'  and the browser follows. Override with PORT=<n>. The HOST half',
+	'  and the browser follows. Override with DSI_PORT=<n>. The HOST half',
 	'  takes 3080 by default; when that port is held by a dsh web you',
 	'  must keep running (another conversation floor), forward',
-	'  --port <n> — it goes to `dsh web` and DSI follows it automatically.',
+	'  --port <n> (or DSH_PORT=<n>; the flag wins) — it goes to `dsh web`',
+	'  and DSI follows it automatically. GLASS_PORT=<n> moves the brain',
+	'  (the glass browser MCP, default 9515). A pre-set GLASS_BRAIN_URL',
+	'  overrides the computed brain address byte-for-byte. On a VM floor,',
+	'  stamp GLASS_CHASSIS_URL=http://<host>:<port> (run `node bin/dsi-chassis.mjs --bind <host>`',
+	'  there) and Shift+click births the visible glass window on THAT',
+	'  machine; unset, the window is born locally exactly as always.',
 	'',
 	'  All commands (flags — see above):',
 	'',
 	'      dsi web [--zai] [--ov] [--dev] [--token <token>]',
-	'                   serve the DSI page alone (PORT env default 5174,',
+	'                   serve the DSI page alone (DSI_PORT env default 5174,',
 	'                   HOST env default 127.0.0.1)',
 	'      dsi dsh --token <token>',
 	'                   store the dsh launch token in ~/.dsi/settings.yaml',
@@ -387,13 +393,26 @@ function setDshAuthToken(token) {
 /** The Stamped Floor (ADR 2026-11-05, D1): every floor announces its own
  *  addresses into the env it gives its children — the UI base (the Floor
  *  Seam D1a seam, finally with a writer) and the brain URL (the preset's
- *  !!js expression reads DSI_MCP_URL with a 9515 bare-boot fallback). The
- *  launcher is the only party that knows both ports at spawn time. */
+ *  !!js expression reads GLASS_BRAIN_URL with a 9515 bare-boot fallback).
+ *  The launcher is the only party that knows both ports at spawn time.
+ *  D2 (ADR 2026-11-08): an operator pre-set GLASS_BRAIN_URL passes through
+ *  byte-for-byte — no validation, no trim; the computed URL is only the
+ *  default.
+ *  GLASS_CHASSIS_URL (ADR-0054, 2026-11-08): the SECOND stamp — where the
+ *  glass WINDOW is born. Same ladder: an operator-exported value passes
+ *  through byte-for-byte; unset stamps nothing and the registry keeps its
+ *  local launch exactly as today (D5). It points at the host companion
+ *  (`node bin/dsi-chassis.mjs --bind <addr>`), not at raw Chrome. */
 function stampedFloorEnv(uiPort) {
-	return {
+	const env = {
 		DSI_UI: 'http://127.0.0.1:' + uiPort,
-		DSI_MCP_URL: 'http://127.0.0.1:' + (process.env.DSI_MCP_PORT ?? 9515) + '/sse'
+		GLASS_BRAIN_URL: process.env.GLASS_BRAIN_URL ?? 'http://127.0.0.1:' + (process.env.GLASS_PORT ?? 9515) + '/sse'
 	};
+	// Unset means NOTHING is stamped (D5): byte-for-byte today's env shape.
+	if (process.env.GLASS_CHASSIS_URL !== undefined) {
+		env.GLASS_CHASSIS_URL = process.env.GLASS_CHASSIS_URL;
+	}
+	return env;
 }
 
 function dshWebVersion() {
@@ -489,7 +508,7 @@ async function runSyncedPair(extraArgs, dev = 'build', execArgv = [], opts = {})
 	// takes 5175 instead (vite.config.ts pins 5174 strictPort, so pair mode
 	// passes 5175 explicitly), giving the two-port dev shape. in-process is
 	// also a vite floor: same 5175.
-	const uiPort = process.env.PORT ?? (mode === 'build' ? '5174' : '5175');
+	const uiPort = process.env.DSI_PORT ?? (mode === 'build' ? '5174' : '5175');
 	// The host half takes --port <n> when forwarded (a 3080 held by a
 	// dsh web this CLI does not own — e.g. another live conversation
 	// floor — is exactly the case the preflight must not kill). The
@@ -506,7 +525,16 @@ async function runSyncedPair(extraArgs, dev = 'build', execArgv = [], opts = {})
 	// bug 2026-10-11: DSH_HOST_PORT=3477 booted the host there while the
 	// page dialed 3080 — the production floor — → "Failed to fetch".)
 	const pluginPort = inProcess && process.env.DSH_HOST_PORT ? parseInt(process.env.DSH_HOST_PORT, 10) : undefined;
-	const hostPort = hostPortFromArgs(extraArgs) ?? pluginPort ?? 3080;
+	// DSH_PORT (2026-11-08 rename): the env form of the forwarded --port flag —
+	// the CLI flag wins when both are set (explicit intent beats ambient env).
+	const envHostPort = /^\d+$/.test(process.env.DSH_PORT ?? '') ? Number(process.env.DSH_PORT) : undefined;
+	const flaggedHostPort = hostPortFromArgs(extraArgs);
+	const hostPort = flaggedHostPort ?? pluginPort ?? envHostPort ?? 3080;
+	// No forwarded flag but DSH_PORT set: forward it to `dsh web` as the flag
+	// it already understands — the host never learns the env name.
+	const hostSpawnArgs = !inProcess && flaggedHostPort === null && envHostPort !== undefined
+		? [...extraArgs, '--port', String(envHostPort)]
+		: extraArgs;
 	const dshBase = hostPort === 3080 ? undefined : `http://127.0.0.1:${hostPort}`;
 	if (inProcess) {
 		await preflightPort(uiPort, 'DSI page');
@@ -516,7 +544,7 @@ async function runSyncedPair(extraArgs, dev = 'build', execArgv = [], opts = {})
 	}
 	// IN-PROCESS: no sync script, no host child — the vite plugin owns the
 	// host lifecycle (vite close hook stops it; one Ctrl-C, no orphan).
-	const host = inProcess ? null : spawn('/bin/sh', [script, ...extraArgs], {
+	const host = inProcess ? null : spawn('/bin/sh', [script, ...hostSpawnArgs], {
 		stdio: 'inherit',
 		env: { ...process.env, DSH_WEB_VERSION: dshWebVersion(), ...stampedFloorEnv(uiPort) }
 	});
@@ -766,7 +794,7 @@ function startDsiDevServer(defaultPort = '5175', dshBase = undefined, mode = 'pa
 	}
 	// --host matches the built server's 127.0.0.1 bind: vite's default
 	// 'localhost' can resolve ::1-only and strand a 127.0.0.1 client.
-	return spawn(process.execPath, [...execArgv, viteBin, 'dev', '--host', process.env.HOST ?? '127.0.0.1', '--port', process.env.PORT ?? defaultPort], {
+	return spawn(process.execPath, [...execArgv, viteBin, 'dev', '--host', process.env.HOST ?? '127.0.0.1', '--port', process.env.DSI_PORT ?? defaultPort], {
 		// D7: inspector flags lead the child argv — node consumes options before
 		// the script path, so `node --inspect vite.js dev` debugs THIS process
 		// (vite + the embedded DSH host share one heap). The spawn execArgv
@@ -785,7 +813,7 @@ function startDsiDevServer(defaultPort = '5175', dshBase = undefined, mode = 'pa
 			DSI_DEV: '1',
 			// D4/D6: the mode rides as env, never past the CLI to the host.
 			...devModeEnv(mode, { playwrightMcp: opts.playwrightMcp === true }),
-			...stampedFloorEnv(process.env.PORT ?? defaultPort),
+			...stampedFloorEnv(process.env.DSI_PORT ?? defaultPort),
 			// The Faithful Bounce (ADR 2026-10-13, D1): the inspector flags are
 			// part of the launch record — stamped so every restorer (the bounce
 			// boot via ps -E, the delayed re-serve via inherited env) can put
@@ -806,7 +834,7 @@ function startDsiServer(defaultPort = '5174', dshBase = undefined, opts = {}) {
 		stdio: 'inherit',
 		env: {
 			...process.env,
-			PORT: process.env.PORT ?? defaultPort,
+			PORT: process.env.DSI_PORT ?? defaultPort,
 			HOST: process.env.HOST ?? '127.0.0.1',
 			// First-start bootstrap seam: the server clones template/.dsi to ~/.dsi
 			// when the operator home is absent (src/lib/server/settings-document.ts).
@@ -815,7 +843,7 @@ function startDsiServer(defaultPort = '5174', dshBase = undefined, opts = {}) {
 			// vite child got it via startDsiDevServer's devModeEnv spread; the
 			// built server was silently dropping it (caught by the live gate).
 			...devModeEnv('build', { playwrightMcp: opts.playwrightMcp === true }),
-			...stampedFloorEnv(process.env.PORT ?? defaultPort),
+			...stampedFloorEnv(process.env.DSI_PORT ?? defaultPort),
 			...(dshBase !== undefined ? { DSH_BASE_URL: dshBase } : {})
 		}
 	});
@@ -909,7 +937,7 @@ if (command === 'web') {
 	// Same browser-follows-the-UI contract as the pair (runSyncedPair): open
 	// the default browser at the serving port — --dev's Vite server takes
 	// 5175, the built server 5174; PORT/HOST overrides apply.
-	openBrowser(`http://${process.env.HOST ?? '127.0.0.1'}:${process.env.PORT ?? (withDev ? '5175' : '5174')}/`);
+	openBrowser(`http://${process.env.HOST ?? '127.0.0.1'}:${process.env.DSI_PORT ?? (withDev ? '5175' : '5174')}/`);
 
 	for (const signal of ['SIGINT', 'SIGTERM']) {
 		process.on(signal, () => {

package/bin/lib/plugin-chain.mjs

@@ -158,16 +158,17 @@ export function parseDevFloorPids(psOutput) {
 /** The port the floor's DSI UI answers on (ADR-0025 Wave 3 gate finding,
  *  2026-10-14): the host-bounce route is a DSI (vite) route, so the bounce
  *  chain must POST the VITE port - the DSH host port only knows the fence
- *  (401) or 404. Resolution order: PORT= in the floor env dump, then
- *  --port N on the vite command line, then the 5175 default the launcher
- *  pins. Pure: both inputs are strings read by dsi.mjs (ps -E and ps -o
- *  command), so unit tests pin all three arms.
+ *  (401) or 404. Resolution order: DSI_PORT= (the 2026-11-08 rename) then
+ *  legacy PORT= in the floor env dump, then --port N on the vite command
+ *  line, then the 5175 default the launcher pins. Pure: both inputs are
+ *  strings read by dsi.mjs (ps -E and ps -o command), so unit tests pin
+ *  all arms.
  *
  * @param {{ floorEnv?: string, command?: string }} params
  * @returns {number} the UI port
  */
 export function floorUiPort({ floorEnv = '', command = '' } = {}) {
-	const envPort = /(?:^|\s)PORT=(\d+)/.exec(floorEnv || '');
+	const envPort = /(?:^|\s)DSI_PORT=(\d+)/.exec(floorEnv || '') || /(?:^|\s)PORT=(\d+)/.exec(floorEnv || '');
 	if (envPort) return Number(envPort[1]);
 	const argPort = /--port\s+(\d+)/.exec(command || '');
 	if (argPort) return Number(argPort[1]);