janissary 0.5.0

package/dist/harness/recorder.js

@@ -0,0 +1,89 @@
+import { createWriteStream } from 'node:fs';
+import { messageBus } from '../bus.js';
+import { ensureRecordingDirectory, harnessRecordingPath } from './recording-file.js';
+// The terminal name the PTY is actually spawned with (`src/pty.ts`); asciicast players read it for
+// correct rendering.
+const TERM = 'xterm-256color';
+// Records one harness PTY's byte stream to a replayable asciicast v2 `.cast` file. It observes the
+// same `pty` bus events as `HarnessScreenReader` (its sibling observer of the same bytes) and, like
+// it, is owned/disposed by `HarnessManager`. The file is created lazily on the first `data` event —
+// a harness that exits before producing output leaves no empty file. Uses a single long-lived
+// append stream (not per-event `appendFileSync`) so a burst of PTY output never blocks `bus.emit`.
+export class HarnessRecorder {
+    id;
+    label;
+    program;
+    cols;
+    rows;
+    subscription;
+    stream;
+    startedAt = Date.now();
+    disposed = false;
+    failed = false;
+    constructor(id, label, program, cols, rows) {
+        this.id = id;
+        this.label = label;
+        this.program = program;
+        this.cols = cols;
+        this.rows = rows;
+        this.subscription = messageBus.on('pty', ['data', 'exit', 'resize'], (event) => {
+            if (event.id !== this.id)
+                return;
+            if (event.type === 'data')
+                this.onData(event.data);
+            else if (event.type === 'resize')
+                this.onResize(event.cols, event.rows);
+            else
+                this.dispose();
+        });
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.subscription.unsubscribe();
+        this.stream?.end();
+        this.stream = undefined;
+    }
+    onData(data) {
+        if (this.disposed || this.failed)
+            return;
+        if (!this.stream)
+            this.open();
+        this.writeEvent('o', data);
+    }
+    // Track the latest dimensions always; emit an `"r"` event only once the file is open. A resize
+    // arriving before the first output just updates the pending header dimensions.
+    onResize(cols, rows) {
+        this.cols = cols;
+        this.rows = rows;
+        if (this.disposed || this.failed || !this.stream)
+            return;
+        this.writeEvent('r', `${cols}x${rows}`);
+    }
+    // Lazily open the append stream and write the asciicast v2 header line.
+    open() {
+        ensureRecordingDirectory();
+        const stream = createWriteStream(harnessRecordingPath(this.label, this.startedAt), { flags: 'a' });
+        // A Node stream's async `'error'` event escapes the bus's per-listener try/catch and would
+        // crash the process if unhandled — disable the recorder instead.
+        stream.on('error', () => { this.failed = true; });
+        this.stream = stream;
+        const header = {
+            version: 2,
+            width: this.cols,
+            height: this.rows,
+            timestamp: Math.floor(this.startedAt / 1000),
+            command: this.program,
+            title: this.label,
+            env: { TERM },
+        };
+        stream.write(JSON.stringify(header) + '\n');
+    }
+    writeEvent(code, data) {
+        if (this.failed || !this.stream)
+            return;
+        const elapsed = Math.round(((Date.now() - this.startedAt) / 1000) * 1e6) / 1e6;
+        this.stream.write(JSON.stringify([elapsed, code, data]) + '\n');
+    }
+}

package/dist/harness/recording-file.js

@@ -0,0 +1,25 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import path from 'node:path';
+let recordingDirectory = '';
+export function initHarnessRecordingDirectory(projectDirectory) {
+    recordingDirectory = path.join(projectDirectory, '.janissary', 'recordings');
+}
+export function ensureRecordingDirectory() {
+    mkdirSync(recordingDirectory, { recursive: true });
+}
+// The absolute `.cast` path for a session started at `startedAt`. The label is sanitized rather
+// than rejected (the tab exists, so its label is legitimate even with filename-hostile characters),
+// and the ISO timestamp's `:`/`.` are replaced with `-`, mirroring `writeCaptureFile`.
+export function harnessRecordingPath(label, startedAt) {
+    const safeLabel = label.replaceAll(/[^\w-]/g, '-');
+    const timestamp = new Date(startedAt).toISOString().replaceAll(/[:.]/g, '-');
+    return path.join(recordingDirectory, `${safeLabel}-${timestamp}.cast`);
+}
+export function clearHarnessRecordingDirectory() {
+    if (!recordingDirectory)
+        return;
+    try {
+        rmSync(recordingDirectory, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+}

package/dist/harness/screen.js

@@ -0,0 +1,79 @@
+import xterm from '@xterm/headless';
+import { messageBus } from '../bus.js';
+// `@xterm/headless` ships a CommonJS bundle whose named exports Node's ESM loader cannot detect
+// statically — the module namespace it synthesizes holds only `default`. So `import { Terminal }`
+// type-checks but throws SyntaxError under Node, while `import Terminal` binds the whole
+// `module.exports` object (not the class) and fails as "default is not a constructor". Take the
+// class off the default import, which Node sets to `module.exports`, and keep the named import
+// type-only so it erases at compile time.
+const { Terminal: HeadlessTerminal } = xterm;
+// Delay between a PTY byte arriving and the screen being read: long enough for a burst of output
+// to settle into a coherent frame, short enough that the capture reflects "now".
+const CAPTURE_DELAY_MS = 1000;
+// Mirrors one harness PTY into a headless terminal so its on-screen text can be read server-side.
+// Captures are throttled on activity: the first `data` event schedules a read 1s later, further
+// events in that window neither reschedule nor extend it, and an idle PTY schedules nothing at
+// all — so an unchanged screen is never re-captured. Only the latest capture is kept.
+export class HarnessScreenReader {
+    id;
+    onCapture;
+    term;
+    subscription;
+    pending;
+    capture;
+    title;
+    disposed = false;
+    constructor(id, cols, rows, onCapture) {
+        this.id = id;
+        this.onCapture = onCapture;
+        // allowProposedApi: the headless build gates the `buffer` read API behind it.
+        this.term = new HeadlessTerminal({ cols, rows, scrollback: 0, allowProposedApi: true });
+        // The terminal parses OSC 0/2 title sequences itself; retain the latest so each capture can
+        // carry the title alongside the rendered text (harness busy/ready detection reads it).
+        this.term.onTitleChange((title) => { this.title = title; });
+        this.subscription = messageBus.on('pty', ['data', 'exit', 'resize'], (event) => {
+            if (event.id !== this.id)
+                return;
+            if (event.type === 'data')
+                this.onData(event.data);
+            else if (event.type === 'resize')
+                this.term.resize(event.cols, event.rows);
+            else
+                this.dispose();
+        });
+    }
+    // The most recent capture, or undefined if the PTY has never been quiet 1s after output.
+    latestCapture() { return this.capture; }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.pending !== undefined)
+            clearTimeout(this.pending);
+        this.pending = undefined;
+        this.subscription.unsubscribe();
+        this.term.dispose();
+    }
+    onData(data) {
+        this.term.write(data);
+        if (this.pending !== undefined)
+            return;
+        this.pending = setTimeout(() => {
+            this.pending = undefined;
+            // xterm parses write() input asynchronously; read the buffer only after the queue drains.
+            this.term.write('', () => { if (!this.disposed)
+                this.captureNow(); });
+        }, CAPTURE_DELAY_MS);
+    }
+    captureNow() {
+        const buffer = this.term.buffer.active;
+        const lines = [];
+        for (let i = 0; i < buffer.length; i++) {
+            lines.push(buffer.getLine(i)?.translateToString(true) ?? '');
+        }
+        while (lines.length > 0 && lines.at(-1) === '')
+            lines.pop();
+        this.capture = { text: lines.join('\n'), capturedAt: Date.now(), title: this.title };
+        this.onCapture?.(this.capture);
+    }
+}

package/dist/harness-capture-file.js

@@ -0,0 +1,28 @@
+import { mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+let captureDirectory = '';
+export function initHarnessCaptureDirectory(projectDirectory) {
+    captureDirectory = path.join(projectDirectory, '.janissary', 'captures');
+}
+export function ensureCaptureDirectory() {
+    mkdirSync(captureDirectory, { recursive: true });
+}
+// Write a screen capture for the tab labeled `label` to `<label>-<capturedAt-iso>.txt` and return
+// the absolute path. The label is sanitized rather than rejected — the tab exists, so its label is
+// legitimate even when it holds filename-hostile characters (`/`, `.`).
+export function writeCaptureFile(label, capturedAt, text) {
+    const safeLabel = label.replaceAll(/[^\w-]/g, '-');
+    const timestamp = new Date(capturedAt).toISOString().replaceAll(/[:.]/g, '-');
+    const file = path.join(captureDirectory, `${safeLabel}-${timestamp}.txt`);
+    ensureCaptureDirectory();
+    writeFileSync(file, text);
+    return file;
+}
+export function clearCaptureDirectory() {
+    if (!captureDirectory)
+        return;
+    try {
+        rmSync(captureDirectory, { recursive: true, force: true });
+    }
+    catch { /* ignore */ }
+}

package/dist/harness-manager.js

@@ -0,0 +1,112 @@
+import { makeHarnessTab, distinctColor, uniqueLabel } from './tab.js';
+import { parseHarnessCommand, HARNESS_COMMANDS, buildHarnessCommand } from './harness.js';
+import { HarnessScreenReader } from './harness-screen.js';
+import { writeCaptureFile } from './harness-capture-file.js';
+import { messageBus } from './bus.js';
+import { sandboxNotice } from './sandbox.js';
+// Owns harness command handling: launching a harness `<name>` as a PTY-backed tab (optionally in a
+// fresh `--workspace` git clone, and optionally under a custom `as <label>`) and naming it uniquely.
+// The controller owns the shared tab and PTY state; this module owns the harness-specific decisions
+// and wiring.
+export class HarnessManager {
+    managers;
+    screenReaders = new Map();
+    constructor(managers) {
+        this.managers = managers;
+        messageBus.on('pty', 'exit', (event) => {
+            if (event.type !== 'exit')
+                return;
+            this.screenReaders.get(event.id)?.dispose();
+            this.screenReaders.delete(event.id);
+        });
+    }
+    // Handle a `harness <name> [as <label>] [-w] [--offline]` command. Returns an error message to
+    // surface in the creator's transcript, or undefined once the harness tab has been opened.
+    run(input) {
+        const parsed = parseHarnessCommand(input);
+        if ('error' in parsed)
+            return parsed.error;
+        if ('capture' in parsed)
+            return this.capture(input, parsed.label);
+        return this.open(parsed.name, parsed.workspace, parsed.offline, parsed.label);
+    }
+    // Handle `harness capture <name>`: write the target tab's latest in-memory screen capture to a
+    // file under .janissary/captures/ and open it in a normal editor tab. Returns an error message
+    // to surface in the invoking tab's transcript, or undefined on success.
+    capture(input, label) {
+        const tab = this.managers.tab.tabs.find((t) => t.label === label);
+        if (!tab)
+            return `No tab labeled "${label}".`;
+        if (!tab.harness)
+            return `"${label}" is not a harness tab.`;
+        const latest = this.screenReaders.get(tab.harness.ptyId)?.latestCapture();
+        if (!latest)
+            return `No capture available for "${label}" yet.`;
+        const file = writeCaptureFile(label, latest.capturedAt, latest.text);
+        this.managers.openFile.edit(input, file, this.managers.tab.cur().label);
+        return undefined;
+    }
+    // Open (and focus) a harness tab running `name`, labeled `label` if given (otherwise `name`).
+    // With `workspace`, the harness starts in a fresh clone of the `origin` remote of the repo
+    // detected from cwd; otherwise it inherits the creator's cwd.
+    open(name, workspace, offline, label_) {
+        const creator = this.managers.tab.cur();
+        const label = uniqueLabel(this.managers.tab.tabs, label_ ?? name);
+        const resolved = this.resolveCwd(workspace, label, this.managers.tab.cwdOf(creator.label) ?? process.cwd());
+        if (typeof resolved !== 'string' && 'error' in resolved)
+            return resolved.error;
+        const cwd = typeof resolved === 'string' ? resolved : resolved.dir;
+        const workspaceDir = typeof resolved === 'string' ? undefined : resolved.dir;
+        const dotColor = distinctColor(this.managers.tab.tabs.map((t) => t.dotColor));
+        const group = creator?.group ?? 1;
+        const groupColor = creator?.groupColor ?? dotColor;
+        this.spawnTab(name, label, cwd, workspaceDir, offline, group, groupColor, dotColor);
+        return undefined;
+    }
+    // Open a harness tab for a profile entry: unlike `open()`, the group/color come from the
+    // profile launch (not the creator tab) and the starting directory comes from the entry's own
+    // `cwd`/`workspace` (falling back to the issuing tab's cwd when the entry has neither). Returns
+    // an error to report and skip on, or undefined once the tab is open. Never persisted — harness
+    // tabs have no agent state.
+    openFromProfile(entry, label, group, groupColor) {
+        const unique = uniqueLabel(this.managers.tab.tabs, label);
+        const resolved = this.resolveCwd(!!entry.workspace, unique, entry.cwd ?? process.cwd());
+        if (typeof resolved !== 'string' && 'error' in resolved)
+            return resolved.error;
+        const cwd = typeof resolved === 'string' ? resolved : resolved.dir;
+        const workspaceDir = typeof resolved === 'string' ? undefined : resolved.dir;
+        const dotColor = distinctColor(this.managers.tab.tabs.map((t) => t.dotColor), entry.dotColor);
+        this.spawnTab(entry.harness, unique, cwd, workspaceDir, false, group, groupColor, dotColor, entry.model);
+        return undefined;
+    }
+    // Shared core: create the harness tab, focus it, and spawn its PTY. `model`, when given, is
+    // passed to the harness binary via `buildHarnessCommand`.
+    spawnTab(name, label, cwd, workspaceDir, offline, group, groupColor, dotColor, model) {
+        const program = HARNESS_COMMANDS[name];
+        const harness = { name, program, ptyId: '', status: 'running' };
+        const tab = makeHarnessTab(label, dotColor, this.managers.tab.tabs.length + 1, group, groupColor, harness, workspaceDir);
+        tab.offline = offline;
+        this.managers.tab.insertTabInGroup(tab);
+        this.managers.tab.addBusy(label);
+        this.managers.tab.activeTab = this.managers.tab.findIndex(tab.label);
+        const id = this.managers.pty.spawn(label, program, buildHarnessCommand(name, model), cwd, workspaceDir, offline);
+        const dims = this.managers.pty.spawnDimensions();
+        this.screenReaders.set(id, new HarnessScreenReader(id, dims.cols, dims.rows));
+        const liveTab = this.managers.tab.tabs.find((t) => t.label === label);
+        if (liveTab?.harness)
+            liveTab.harness.ptyId = id;
+        const notice = workspaceDir ? sandboxNotice() : undefined;
+        if (notice)
+            this.managers.tab.append(label, { input: '', output: notice });
+        messageBus.emit('state', { type: 'dirty' });
+    }
+    // The harness's starting directory: a new workspace clone (with `workspace`) or `fallbackCwd`.
+    // Returns the directory, or an `{ error }` to surface when there's no repo or the clone fails.
+    // A workspace clone is returned as `{ dir }` (not a bare string) so the caller can tell it apart
+    // from the fallback cwd and record it on the tab for cleanup on close.
+    resolveCwd(workspace, label, fallbackCwd) {
+        if (!workspace)
+            return fallbackCwd;
+        return this.managers.workspace.create(label);
+    }
+}

package/dist/harness-models.js

@@ -0,0 +1,8 @@
+import catalog from '../harness-models.json' with { type: 'json' };
+const models = catalog;
+export function modelsFor(harness) {
+    return models[harness] ?? [];
+}
+export function isKnownModel(harness, model) {
+    return modelsFor(harness).includes(model);
+}

package/dist/harness-screen.js

@@ -0,0 +1,72 @@
+import xterm from '@xterm/headless';
+import { messageBus } from './bus.js';
+// `@xterm/headless` ships a CommonJS bundle whose named exports Node's ESM loader cannot detect
+// statically — the module namespace it synthesizes holds only `default`. So `import { Terminal }`
+// type-checks but throws SyntaxError under Node, while `import Terminal` binds the whole
+// `module.exports` object (not the class) and fails as "default is not a constructor". Take the
+// class off the default import, which Node sets to `module.exports`, and keep the named import
+// type-only so it erases at compile time.
+const { Terminal: HeadlessTerminal } = xterm;
+// Delay between a PTY byte arriving and the screen being read: long enough for a burst of output
+// to settle into a coherent frame, short enough that the capture reflects "now".
+const CAPTURE_DELAY_MS = 1000;
+// Mirrors one harness PTY into a headless terminal so its on-screen text can be read server-side.
+// Captures are throttled on activity: the first `data` event schedules a read 1s later, further
+// events in that window neither reschedule nor extend it, and an idle PTY schedules nothing at
+// all — so an unchanged screen is never re-captured. Only the latest capture is kept.
+export class HarnessScreenReader {
+    id;
+    term;
+    subscription;
+    pending;
+    capture;
+    disposed = false;
+    constructor(id, cols, rows) {
+        this.id = id;
+        // allowProposedApi: the headless build gates the `buffer` read API behind it.
+        this.term = new HeadlessTerminal({ cols, rows, scrollback: 0, allowProposedApi: true });
+        this.subscription = messageBus.on('pty', ['data', 'exit', 'resize'], (event) => {
+            if (event.id !== this.id)
+                return;
+            if (event.type === 'data')
+                this.onData(event.data);
+            else if (event.type === 'resize')
+                this.term.resize(event.cols, event.rows);
+            else
+                this.dispose();
+        });
+    }
+    // The most recent capture, or undefined if the PTY has never been quiet 1s after output.
+    latestCapture() { return this.capture; }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.pending !== undefined)
+            clearTimeout(this.pending);
+        this.pending = undefined;
+        this.subscription.unsubscribe();
+        this.term.dispose();
+    }
+    onData(data) {
+        this.term.write(data);
+        if (this.pending !== undefined)
+            return;
+        this.pending = setTimeout(() => {
+            this.pending = undefined;
+            // xterm parses write() input asynchronously; read the buffer only after the queue drains.
+            this.term.write('', () => { if (!this.disposed)
+                this.captureNow(); });
+        }, CAPTURE_DELAY_MS);
+    }
+    captureNow() {
+        const buffer = this.term.buffer.active;
+        const lines = [];
+        for (let i = 0; i < buffer.length; i++) {
+            lines.push(buffer.getLine(i)?.translateToString(true) ?? '');
+        }
+        while (lines.length > 0 && lines.at(-1) === '')
+            lines.pop();
+        this.capture = { text: lines.join('\n'), capturedAt: Date.now() };
+    }
+}

package/dist/harness.js

@@ -0,0 +1,54 @@
+// The embeddable AI coding harnesses, mapped to the binary that launches each. In the web app a
+// harness runs in a PTY rendered as an inline terminal card (see src/server/controller.ts).
+export const HARNESS_COMMANDS = {
+    claude: 'claude',
+    opencode: 'opencode',
+    codex: 'codex',
+};
+export const HARNESS_NAMES = Object.keys(HARNESS_COMMANDS);
+/**
+ * Parse a `harness <name> [as <label>] [-w|--workspace] [--offline]` command, validating the
+ * harness name against the known set. `as <label>` gives the new tab a custom label instead of
+ * the harness name (still de-duplicated against existing tab labels). `--offline` adds a
+ * network-deny rule to the tab's sandbox profile (only meaningful alongside `-w`/`--workspace`).
+ * `harness capture <name>` is the other form: `<name>` targets an existing harness tab by label
+ * (`capture` can never collide with a harness name — it is not a HARNESS_COMMANDS key).
+ */
+export function parseHarnessCommand(input) {
+    const rest = input.replace(/^harness\b\s*/i, '').trim();
+    if (!rest)
+        return { error: `Usage: harness <${HARNESS_NAMES.join('|')}> [as <label>] [-w].` };
+    const tokens = rest.split(/\s+/);
+    if (tokens[0].toLowerCase() === 'capture') {
+        const label = tokens[1];
+        if (!label)
+            return { error: 'Usage: harness capture <name>.' };
+        return { capture: true, label };
+    }
+    const name = tokens[0].toLowerCase();
+    if (HARNESS_COMMANDS[name] === undefined) {
+        return { error: `Unknown harness "${name}". Choose from: ${HARNESS_NAMES.join(', ')}.` };
+    }
+    const rest_ = tokens.slice(1);
+    const workspace = rest_.some((t) => t === '-w' || t === '--workspace');
+    const offline = rest_.some((t) => t.toLowerCase() === '--offline');
+    const asIndex = rest_.findIndex((t) => t.toLowerCase() === 'as');
+    if (asIndex === -1)
+        return { name, workspace, offline };
+    const label = rest_[asIndex + 1];
+    if (!label)
+        return { error: `Usage: harness <${HARNESS_NAMES.join('|')}> as <label>.` };
+    return { name, workspace, offline, label };
+}
+// Single-quote a value for embedding in a `shell -lc '<command>'` string, escaping any embedded
+// single quotes (`'` → `'\''`).
+function shellQuote(value) {
+    return `'${value.replaceAll("'", String.raw `'\''`)}'`;
+}
+// Build the shell command string that launches a harness binary, optionally with a model flag.
+// `buildHarnessCommand('opencode', 'opencode-go/deepseek-v4-pro')` →
+// `opencode --model 'opencode-go/deepseek-v4-pro'`.
+export function buildHarnessCommand(name, model) {
+    const program = HARNESS_COMMANDS[name];
+    return model ? `${program} --model ${shellQuote(model)}` : program;
+}

package/dist/index.js

@@ -0,0 +1,163 @@
+import { createServer } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { WebSocketServer, WebSocket } from 'ws';
+import { Controller } from './controller.js';
+import { makeToken, originAllowed, tokenFromReq as tokenFromRequest, tokenMatches } from './security.js';
+import { handle } from './message-handler.js';
+import { buildStateEvent } from './state-event.js';
+// Applied to every HTTP response: defence-in-depth for the XSS path and token leak.
+const SECURITY_HEADERS = {
+    'Referrer-Policy': 'no-referrer',
+    'Content-Security-Policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self'; frame-src https: http:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'",
+};
+const MIME = {
+    '.html': 'text/html; charset=utf-8', '.js': 'text/javascript', '.css': 'text/css',
+    '.json': 'application/json', '.svg': 'image/svg+xml', '.ico': 'image/x-icon',
+    '.woff2': 'font/woff2', '.map': 'application/json',
+    // Image types served via the `/open/<id>` route (opened files).
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif',
+    '.webp': 'image/webp', '.bmp': 'image/bmp', '.avif': 'image/avif',
+    // Markdown files served via the `/open/<id>` route.
+    '.md': 'text/markdown; charset=utf-8', '.markdown': 'text/markdown; charset=utf-8',
+    // Text types with their own registered MIME, served via the `/open/<id>` route (editor opener).
+    '.mjs': 'text/javascript', '.cjs': 'text/javascript', '.xml': 'application/xml',
+    '.csv': 'text/csv; charset=utf-8',
+    // The rest of the editor opener's plain-text extensions all serve as text/plain.
+    ...Object.fromEntries([
+        '.txt', '.text', '.log', '.yaml', '.yml', '.toml', '.ini', '.conf', '.cfg', '.env',
+        '.ts', '.tsx', '.jsx', '.py', '.rb', '.go', '.rs', '.c', '.h', '.cpp', '.hpp', '.java',
+        '.sh', '.bash', '.zsh', '.sql',
+    ].map((extension) => [extension, 'text/plain; charset=utf-8'])),
+};
+export async function startServer(options) {
+    const token = options.token ?? makeToken();
+    const host = options.host ?? '127.0.0.1';
+    const clients = new Set();
+    let closed = false;
+    let exitTimer;
+    const broadcast = (event) => {
+        const s = JSON.stringify(event);
+        for (const c of clients)
+            if (c.readyState === WebSocket.OPEN)
+                c.send(s);
+    };
+    // Reassigned below once `close` exists, so the `quit` command can shut the server down cleanly.
+    let requestExit = () => process.exit(0);
+    const controller = new Controller({
+        emitState: () => broadcast(buildStateEvent(controller)),
+        sendPty: (id, data) => broadcast({ t: 'pty', id, data }),
+        sendPtyExit: (id, exitCode) => broadcast({ t: 'pty-exit', id, exitCode }),
+        exit: () => requestExit(),
+    }, options.projectDir);
+    if (options.relaunch)
+        controller.rehydrate();
+    const serveStatic = async (request, res) => {
+        if (!originAllowed(request)) {
+            res.writeHead(403).end('forbidden');
+            return;
+        }
+        const urlPath = new URL(request.url ?? '/', 'http://localhost').pathname;
+        // A file explicitly opened in the app (`open <file>`). Guarded by the session token and served
+        // only from the controller's allow-list — an arbitrary local path is never reachable.
+        if (urlPath.startsWith('/open/')) {
+            if (!tokenMatches(token, tokenFromRequest(request))) {
+                res.writeHead(403).end('forbidden');
+                return;
+            }
+            const id = decodeURIComponent(urlPath.slice('/open/'.length));
+            const filePath = controller.openFilePath(id);
+            if (!filePath) {
+                res.writeHead(404).end('not found');
+                return;
+            }
+            let bytes;
+            try {
+                bytes = await readFile(filePath);
+            }
+            catch {
+                bytes = Buffer.alloc(0);
+            }
+            res.writeHead(200, { ...SECURITY_HEADERS, 'content-type': MIME[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream' });
+            res.end(bytes);
+            return;
+        }
+        // Resolve within webDir; fall back to index.html for SPA routes / unknown assets.
+        const rel = path.normalize(urlPath).replace(/^(\.\.[/\\])+/, '').replace(/^\/+/, '');
+        let file = path.join(options.webDir, rel || 'index.html');
+        if (!file.startsWith(options.webDir))
+            file = path.join(options.webDir, 'index.html');
+        let body;
+        try {
+            body = await readFile(file);
+        }
+        catch {
+            try {
+                body = await readFile(path.join(options.webDir, 'index.html'));
+                file = 'index.html';
+            }
+            catch {
+                res.writeHead(404).end('not found');
+                return;
+            }
+        }
+        res.writeHead(200, { ...SECURITY_HEADERS, 'content-type': MIME[path.extname(file)] ?? 'application/octet-stream' });
+        res.end(body);
+    };
+    const http = createServer((request, res) => { void serveStatic(request, res); });
+    const wss = new WebSocketServer({ noServer: true });
+    http.on('upgrade', (request, socket, head) => {
+        if (!originAllowed(request) || !tokenMatches(token, tokenFromRequest(request))) {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(request, socket, head, (ws) => wss.emit('connection', ws, request));
+    });
+    wss.on('connection', (ws) => {
+        clients.add(ws);
+        ws.on('message', (raw) => {
+            let message;
+            try {
+                message = JSON.parse(raw.toString());
+            }
+            catch {
+                return;
+            }
+            try {
+                handle(controller, message, (event) => ws.send(JSON.stringify(event)));
+            }
+            catch (error) {
+                ws.send(JSON.stringify({ t: 'rpc-reply', id: message.id, error: error instanceof Error ? error.message : String(error) }));
+            }
+        });
+        ws.on('close', () => {
+            clients.delete(ws);
+            if (clients.size === 0 && !closed) {
+                broadcast({ t: 'bye' });
+                exitTimer = setTimeout(() => { void close().then(() => process.exit(0)); }, 100);
+            }
+        });
+    });
+    const port = await new Promise((resolve, reject) => {
+        http.on('error', reject);
+        http.listen(options.port ?? 0, host, () => {
+            const addr = http.address();
+            resolve(typeof addr === 'object' && addr ? addr.port : 0);
+        });
+    });
+    const close = () => new Promise((resolve) => {
+        closed = true;
+        if (exitTimer)
+            clearTimeout(exitTimer);
+        controller.shutdown();
+        for (const c of clients)
+            c.close();
+        wss.close(() => http.close(() => resolve()));
+    });
+    requestExit = () => {
+        // Ask connected windows to close themselves, then stop the server and process.
+        broadcast({ t: 'bye' });
+        setTimeout(() => { void close().then(() => process.exit(0)); }, 100);
+    };
+    return { url: `http://${host}:${port}/?token=${token}`, port, token, close, shutdown: () => requestExit() };
+}