@pablopunk/webr 0.1.1

package/src/server/runtime/supervisor.ts

@@ -0,0 +1,92 @@
+import { randomUUID } from 'node:crypto';
+import type { TargetAdapter } from './target';
+import type { NativeSnapshot } from '../protocol/native';
+import { retryDelay } from '../../shared/retry';
+const safeReason = (error: unknown, fallback: string) => error instanceof Error && ['connection_not_approved', 'unsupported_herdr_version', 'unsupported_herdr_schema', 'ssh_forward_failed', 'socket_unavailable', 'rpc_timeout', 'events_lost'].includes(error.message) ? error.message : fallback;
+
+export class TargetSupervisor {
+  readonly generation = randomUUID();
+  revision = 0;
+  snapshot?: NativeSnapshot;
+  connected = false;
+  error?: string;
+  freshAt: string | null = null;
+  private dirty = false;
+  private reading = false;
+  private stopped = false;
+  private subscription?: () => void;
+  private timer?: ReturnType<typeof setTimeout>;
+  private health?: ReturnType<typeof setInterval>;
+  private epoch = 0;
+  private subscribedPanes = '';
+  private failures = 0;
+  private lastFailureAt = 0;
+  private waiters = new Set<{ floor: number; resolve: (snapshot: NativeSnapshot) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  constructor(readonly target: TargetAdapter, private publish: () => void, private delay = 25) {}
+  async start() {
+    if (this.stopped) return;
+    const epoch = ++this.epoch;
+    try {
+      const unsubscribe = await this.target.subscribe(() => this.invalidate(), (reason) => this.disconnect(reason));
+      if (this.stopped || epoch !== this.epoch) { unsubscribe(); return; }
+      this.subscription = unsubscribe;
+      this.invalidate();
+      this.health ??= setInterval(() => this.invalidate(), 15_000);
+      this.health.unref();
+    } catch (error) { if (epoch === this.epoch) this.disconnect(safeReason(error, 'target_unavailable')); }
+  }
+  invalidate() {
+    this.dirty = true;
+    if (!this.timer && !this.reading && this.subscription) this.timer = setTimeout(() => { this.timer = undefined; void this.refresh(); }, this.delay);
+  }
+  readFresh(): Promise<NativeSnapshot> {
+    if (!this.subscription || this.stopped) return Promise.reject(new Error('machine_disconnected'));
+    return new Promise((resolve, reject) => {
+      const waiter = { floor: this.revision + (this.reading ? 2 : 1), resolve, reject, timer: setTimeout(() => { this.waiters.delete(waiter); reject(new Error('snapshot_timeout')); }, 15_000) };
+      this.waiters.add(waiter); this.invalidate();
+    });
+  }
+  stop() {
+    this.stopped = true; ++this.epoch;
+    clearTimeout(this.timer); clearInterval(this.health);
+    this.subscription?.(); this.subscription = undefined; this.target.close();
+    this.rejectWaiters();
+  }
+  private async refresh() {
+    if (this.reading || this.stopped || !this.subscription) return;
+    this.reading = true;
+    this.dirty = false;
+    const epoch = this.epoch;
+    try {
+      const snapshot = await this.target.snapshot();
+      if (epoch !== this.epoch || this.stopped) return;
+      this.snapshot = snapshot; this.connected = true; this.error = undefined;
+      if (Date.now() - this.lastFailureAt >= 30_000) this.failures = 0;
+      this.freshAt = new Date().toISOString(); ++this.revision; this.publish();
+      for (const waiter of this.waiters) if (this.revision >= waiter.floor) { this.waiters.delete(waiter); clearTimeout(waiter.timer); waiter.resolve(snapshot); }
+      const paneIds = snapshot.panes.map((pane) => pane.pane_id).sort();
+      const key = JSON.stringify(paneIds);
+      if (key !== this.subscribedPanes) {
+        const subscription = await this.target.subscribe(() => this.invalidate(), (reason) => this.disconnect(reason), paneIds);
+        if (epoch !== this.epoch || this.stopped) { subscription(); return; }
+        this.subscription?.(); this.subscription = subscription; this.subscribedPanes = key; this.dirty = true;
+      }
+    } catch (error) { if (epoch === this.epoch) this.disconnect(safeReason(error, 'snapshot_failed')); }
+    finally {
+      this.reading = false;
+      if (this.dirty && this.hasSubscription()) this.invalidate();
+    }
+  }
+  private hasSubscription() { return !!this.subscription; }
+  private disconnect(reason: string) {
+    if (this.stopped) return;
+    ++this.epoch; this.subscription?.(); this.subscription = undefined;
+    this.subscribedPanes = '';
+    this.connected = false; this.error = reason; this.freshAt = null; ++this.revision; this.publish();
+    this.lastFailureAt = Date.now();
+    this.rejectWaiters();
+    clearTimeout(this.timer);
+    this.timer = setTimeout(() => { this.timer = undefined; void this.start(); }, retryDelay(this.failures++));
+  }
+  private rejectWaiters() { for (const waiter of this.waiters) { clearTimeout(waiter.timer); waiter.reject(new Error('machine_disconnected')); } this.waiters.clear(); }
+}

package/src/server/runtime/target.ts

@@ -0,0 +1,37 @@
+import type { Machine } from '../../lib/machines';
+import type { NativeSnapshot } from '../protocol/native';
+import type { TerminalFrame, TerminalStream } from '../terminal/cli';
+import type { LaunchInput } from '../../shared/runtime';
+import type { WorktreeEntry } from './herdr-actions';
+import type { Icon } from '../transport/icons';
+
+export type TerminalDirection = 'right' | 'down';
+export type LaunchLocation = { projectId: string; localId?: string; logicalId?: string; path: string; workspaceId: string };
+export type TargetAdapter = {
+  id: string; session: string; name: string;
+  fingerprint: string;
+  configVersion: number;
+  enabled?: boolean;
+  locations: LaunchLocation[];
+  writable: boolean;
+  acceptsLocalFiles?: boolean;
+  subscribe(onEvent: () => void, onClose: (reason: string) => void, paneIds?: string[]): Promise<() => void>;
+  snapshot(): Promise<NativeSnapshot>;
+  catalog(projectId?: string): Promise<Machine>;
+  canLaunch?(input: LaunchInput): boolean;
+  icon?(projectId: string): Promise<Icon | undefined>;
+  worktrees?(projectId: string): Promise<WorktreeEntry[]>;
+  openWorktree?(projectId: string, path: string): Promise<void>;
+  createWorkspace?(path: string, label: string, requestId: string): Promise<{ workspaceId: string; tabId: string; terminalId: string }>;
+  openTerminal(terminalId: string, mode: 'control' | 'observe', cols: number, rows: number, takeover: boolean, onFrame: (frame: TerminalFrame) => void, onClose: (reason: string) => void): TerminalStream;
+  create(input: LaunchInput, threadId: string): Promise<{ tabId: string; paneId: string; terminalId: string; workspaceId: string }>;
+  start(input: LaunchInput, paneId: string, threadId: string): Promise<void>;
+  prompt(paneId: string, prompt: string, terminalId: string, threadId: string, input: LaunchInput): Promise<void>;
+  scrollMode?(terminalId: string): Promise<'scrollback' | 'app'>;
+  focusPane?(paneId: string): Promise<void>;
+  discardTab?(tabId: string, removeWorktree: boolean): Promise<void>;
+  renameTab?(tabId: string, label: string, renameWorkspace: boolean): Promise<void>;
+  splitTerminal?(paneId: string, direction: TerminalDirection): Promise<string>;
+  closePane?(paneId: string): Promise<void>;
+  close(): void;
+};

package/src/server/runtime/workspace.ts

@@ -0,0 +1,24 @@
+import { randomUUID } from 'node:crypto';
+import type { MetadataDatabase } from '../storage/database';
+import type { TargetAdapter } from './target';
+
+export async function createWorkspace(database: MetadataDatabase, target: TargetAdapter, key: string, path: string, label: string) {
+  if (!target.createWorkspace) throw new Error('workspace_creation_unavailable');
+  const setting = 'workspace_operation:' + key;
+  const input = JSON.stringify({ fingerprint: target.fingerprint, path, label });
+  const intent = database.sqlite.transaction(() => {
+    const saved = database.getSetting(setting);
+    if (saved) {
+      const operation = JSON.parse(saved);
+      if (operation.input !== input) throw new Error('idempotency_conflict');
+      return { ...operation, created: false };
+    }
+    const operation = { id: randomUUID(), input, state: 'unknown' };
+    database.setSetting(setting, JSON.stringify(operation));
+    return { ...operation, created: true };
+  }).immediate();
+  if (!intent.created) return intent.result ?? { operationId: intent.id, state: intent.state };
+  const result = await target.createWorkspace(path, label, intent.id);
+  database.setSetting(setting, JSON.stringify({ id: intent.id, input, state: 'ready', result }));
+  return result;
+}

package/src/server/storage/database.ts

@@ -0,0 +1,88 @@
+import { NodeSqliteClient } from './node-sqlite-client';
+import { openMigratedDrizzle } from './drizzle-node-sqlite';
+import { and, desc, eq, lte, max } from 'drizzle-orm';
+import type { DeviceSession } from '../auth/sessions';
+import type { AuditEvent } from '../auth/audit';
+import { fileURLToPath } from 'node:url';
+import { randomUUID, createHash } from 'node:crypto';
+import { mkdirSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import * as schema from './schema';
+import type { Thread } from '../../lib/models';
+import type { LaunchInput } from '../../shared/runtime';
+
+const AUDIT_RETENTION = 200;
+
+export class MetadataDatabase {
+  readonly sqlite: NodeSqliteClient;
+  readonly db;
+  constructor(path: string) {
+    if (path !== ':memory:') mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    this.sqlite = new NodeSqliteClient(path);
+    if (path !== ':memory:') chmodSync(path, 0o600);
+    this.sqlite.exec('PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON');
+    this.db = openMigratedDrizzle(this.sqlite, schema, fileURLToPath(new URL('../../../drizzle', import.meta.url)));
+  }
+  close() { this.sqlite.close(); }
+  getSetting(key: string) { return this.db.select().from(schema.settings).where(eq(schema.settings.key, key)).get()?.value; }
+  setSetting(key: string, value: string) { this.db.insert(schema.settings).values({ key, value }).onConflictDoUpdate({ target: schema.settings.key, set: { value } }).run(); }
+  threadRows(machineId?: string, session?: string) {
+    return this.db.select().from(schema.threads).where(machineId ? and(eq(schema.threads.machineId, machineId), session ? eq(schema.threads.session, session) : undefined) : undefined).all();
+  }
+  nextAvatarIndex() { return (this.db.select({ last: max(schema.threads.avatar) }).from(schema.threads).get()?.last ?? -1) + 1; }
+  saveThread(thread: Thread, anchors: string[], alias: string | null = null) {
+    const row = { id: thread.id, machineId: thread.machineId, session: thread.session, alias, metadata: thread, anchors, avatar: thread.avatarIndex };
+    this.db.insert(schema.threads).values(row).onConflictDoUpdate({ target: schema.threads.id, set: row }).run();
+  }
+  deleteThread(id: string) {
+    this.db.transaction(() => {
+      this.db.delete(schema.operations).where(eq(schema.operations.threadId, id)).run();
+      this.db.delete(schema.threads).where(eq(schema.threads.id, id)).run();
+    });
+  }
+  beginLaunch(accountId: string, key: string, input: LaunchInput, thread: Thread) {
+    const hash = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+    return this.db.transaction(() => {
+      const existing = this.db.select().from(schema.operations).where(and(eq(schema.operations.accountId, accountId), eq(schema.operations.key, key))).get();
+      if (existing) {
+        if (existing.hash !== hash) throw new Error('idempotency_conflict');
+        return { operation: existing, created: false };
+      }
+      const operation = { id: randomUUID(), accountId, key, hash, threadId: thread.id, input, state: 'pending', step: 'validate', result: {} };
+      this.db.insert(schema.operations).values(operation).run();
+      this.saveThread(thread, []);
+      return { operation, created: true };
+    });
+  }
+  updateOperation(id: string, state: string, step: string, result: Record<string, unknown>) {
+    this.db.update(schema.operations).set({ state, step, result }).where(eq(schema.operations.id, id)).run();
+  }
+  operation(id: string) { return this.db.select().from(schema.operations).where(eq(schema.operations.id, id)).get(); }
+  operations() { return this.db.select().from(schema.operations).all(); }
+  markInterruptedLaunches() {
+    for (const operation of this.operations()) if (operation.state === 'pending' || operation.state === 'running') this.updateOperation(operation.id, 'unknown', operation.step, operation.result);
+  }
+  registerProfile(id: string, session: string, metadata: string, locations: { projectId: string; path: string }[]) {
+    const previous = this.db.select().from(schema.profiles).where(eq(schema.profiles.id, id)).get();
+    const configVersion = previous ? previous.configVersion + Number(previous.metadata !== metadata || previous.session !== session) : 1;
+    this.db.transaction(() => {
+      this.db.insert(schema.profiles).values({ id, session, metadata, configVersion }).onConflictDoUpdate({ target: schema.profiles.id, set: { session, metadata, configVersion } }).run();
+      this.db.delete(schema.projectLocations).where(eq(schema.projectLocations.machineId, id)).run();
+      for (const location of locations) this.db.insert(schema.projectLocations).values({ id: id + ':' + location.projectId, machineId: id, projectId: location.projectId, path: location.path }).run();
+    });
+    return configVersion;
+  }
+  addDeviceSession(session: DeviceSession & { tokenHash: string }) { this.db.insert(schema.deviceSessions).values(session).run(); }
+  deviceSessionByTokenHash(tokenHash: string) { return this.db.select().from(schema.deviceSessions).where(eq(schema.deviceSessions.tokenHash, tokenHash)).get(); }
+  deviceSessions() { return this.db.select({ id: schema.deviceSessions.id, name: schema.deviceSessions.name, createdAt: schema.deviceSessions.createdAt, lastSeenAt: schema.deviceSessions.lastSeenAt }).from(schema.deviceSessions).all(); }
+  touchDeviceSession(id: string, lastSeenAt: number) { this.db.update(schema.deviceSessions).set({ lastSeenAt }).where(eq(schema.deviceSessions.id, id)).run(); }
+  deleteDeviceSession(id: string) { return this.db.delete(schema.deviceSessions).where(eq(schema.deviceSessions.id, id)).run().changes > 0; }
+  addAuditEvent(event: Omit<AuditEvent, 'id'>) {
+    this.db.transaction(() => {
+      this.db.insert(schema.auditEvents).values(event).run();
+      const oldest = this.db.select({ id: schema.auditEvents.id }).from(schema.auditEvents).orderBy(desc(schema.auditEvents.id)).limit(1).offset(AUDIT_RETENTION).get();
+      if (oldest) this.db.delete(schema.auditEvents).where(lte(schema.auditEvents.id, oldest.id)).run();
+    });
+  }
+  auditEvents(limit: number): AuditEvent[] { return this.db.select().from(schema.auditEvents).orderBy(desc(schema.auditEvents.id)).limit(limit).all() as AuditEvent[]; }
+}

package/src/server/storage/drizzle-node-sqlite.ts

@@ -0,0 +1,18 @@
+import { createTableRelationsHelpers, extractTablesRelationalConfig } from 'drizzle-orm';
+import { BetterSQLiteSession } from 'drizzle-orm/better-sqlite3/session';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
+import { BaseSQLiteDatabase, SQLiteSyncDialect } from 'drizzle-orm/sqlite-core';
+import type { NodeSqliteClient, RunResult } from './node-sqlite-client';
+
+export type NodeSqliteDrizzle<Schema extends Record<string, unknown>> = BaseSQLiteDatabase<'sync', RunResult, Schema>;
+
+/** drizzle's better-sqlite3 `drizzle()` and `migrate()` import the native package, so build both from its session classes. */
+export function openMigratedDrizzle<Schema extends Record<string, unknown>>(client: NodeSqliteClient, schema: Schema, migrationsFolder: string): NodeSqliteDrizzle<Schema> {
+  const dialect = new SQLiteSyncDialect();
+  const relations = extractTablesRelationalConfig(schema, createTableRelationsHelpers);
+  const relationalSchema = { fullSchema: schema, schema: relations.tables, tableNamesMap: relations.tableNamesMap };
+  const session = new BetterSQLiteSession(client as never, dialect, relationalSchema);
+  const config = { migrationsFolder };
+  dialect.migrate(readMigrationFiles(config), session, config);
+  return new BaseSQLiteDatabase('sync', dialect, session, relationalSchema) as NodeSqliteDrizzle<Schema>;
+}

package/src/server/storage/node-sqlite-client.ts

@@ -0,0 +1,44 @@
+import { DatabaseSync, type StatementSync, type SQLInputValue } from 'node:sqlite';
+
+export type RunResult = { changes: number | bigint; lastInsertRowid: number | bigint };
+type BindValues = SQLInputValue[];
+type Behavior = 'deferred' | 'immediate' | 'exclusive';
+
+class NodeSqliteStatement {
+  constructor(private readonly statement: StatementSync) { this.statement.setReturnArrays(false); }
+  run(...parameters: BindValues) { return this.statement.run(...parameters); }
+  all(...parameters: BindValues) { return this.statement.all(...parameters); }
+  get(...parameters: BindValues) { return this.statement.get(...parameters); }
+  raw() { this.statement.setReturnArrays(true); return this; }
+}
+
+function runInTransaction<Args extends unknown[], Result>(database: DatabaseSync, behavior: Behavior, work: (...args: Args) => Result) {
+  return (...args: Args) => {
+    database.exec(`BEGIN ${behavior}`);
+    try {
+      const result = work(...args);
+      database.exec('COMMIT');
+      return result;
+    } catch (error) {
+      if (database.isTransaction) database.exec('ROLLBACK');
+      throw error;
+    }
+  };
+}
+
+/** The slice of the better-sqlite3 client API that drizzle's synchronous SQLite driver calls, backed by `node:sqlite`. */
+export class NodeSqliteClient {
+  private readonly database: DatabaseSync;
+  constructor(path: string) { this.database = new DatabaseSync(path); }
+  exec(sql: string) { this.database.exec(sql); }
+  close() { this.database.close(); }
+  prepare(sql: string) { return new NodeSqliteStatement(this.database.prepare(sql)); }
+  transaction<Args extends unknown[], Result>(work: (...args: Args) => Result) {
+    const inTransaction = (behavior: Behavior) => runInTransaction(this.database, behavior, work);
+    return Object.assign(inTransaction('deferred'), {
+      deferred: inTransaction('deferred'),
+      immediate: inTransaction('immediate'),
+      exclusive: inTransaction('exclusive'),
+    });
+  }
+}

package/src/server/storage/schema.ts

@@ -0,0 +1,25 @@
+import { sqliteTable, text, integer, uniqueIndex } from 'drizzle-orm/sqlite-core';
+import type { Thread } from '../../lib/models';
+import type { LaunchInput } from '../../shared/runtime';
+
+export const threads = sqliteTable('app_threads', {
+  id: text('id').primaryKey(), machineId: text('machine_id').notNull(), session: text('session').notNull(),
+  alias: text('alias'), metadata: text('metadata', { mode: 'json' }).$type<Thread>().notNull(),
+  anchors: text('anchors', { mode: 'json' }).$type<string[]>().notNull(), avatar: integer('avatar').notNull(),
+}, (table) => [uniqueIndex('native_alias').on(table.machineId, table.session, table.alias)]);
+export const operations = sqliteTable('launch_operations', {
+  id: text('id').primaryKey(), accountId: text('account_id').notNull(), key: text('key').notNull(), hash: text('hash').notNull(), threadId: text('thread_id').notNull(),
+  input: text('input', { mode: 'json' }).$type<LaunchInput>().notNull(), state: text('state').notNull(), step: text('step').notNull(),
+  result: text('result', { mode: 'json' }).$type<Record<string, unknown>>().notNull(),
+}, (table) => [uniqueIndex('account_operation_key').on(table.accountId, table.key)]);
+export const settings = sqliteTable('app_settings', { key: text('key').primaryKey(), value: text('value').notNull() });
+export const profiles = sqliteTable('machine_profiles', { id: text('id').primaryKey(), session: text('session').notNull(), configVersion: integer('config_version').notNull(), metadata: text('metadata').notNull() });
+export const projectLocations = sqliteTable('project_locations', { id: text('id').primaryKey(), machineId: text('machine_id').notNull(), projectId: text('project_id').notNull(), path: text('path').notNull() });
+export const deviceSessions = sqliteTable('device_sessions', {
+  id: text('id').primaryKey(), tokenHash: text('token_hash').notNull(), name: text('name').notNull(),
+  createdAt: integer('created_at').notNull(), lastSeenAt: integer('last_seen_at').notNull(),
+}, (table) => [uniqueIndex('device_session_token').on(table.tokenHash)]);
+export const auditEvents = sqliteTable('audit_events', {
+  id: integer('id').primaryKey({ autoIncrement: true }), at: integer('at').notNull(), kind: text('kind').notNull(),
+  source: text('source'), deviceName: text('device_name'),
+});

package/src/server/tailscale-host.ts

@@ -0,0 +1,17 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+const TAILSCALE_BINARIES = ['tailscale', '/Applications/Tailscale.app/Contents/MacOS/Tailscale'];
+
+const magicDnsName = (statusJson: string) => {
+  const name = (JSON.parse(statusJson) as { Self?: { DNSName?: string } }).Self?.DNSName;
+  return name ? name.replace(/\.$/, '') : undefined;
+};
+
+export async function detectTailscaleHost() {
+  for (const binary of TAILSCALE_BINARIES) {
+    try { return magicDnsName((await run(binary, ['status', '--json'], { timeout: 3000 })).stdout); } catch { /* try the next binary */ }
+  }
+  return undefined;
+}

package/src/server/terminal/cli.ts

@@ -0,0 +1,44 @@
+import { spawn, type SpawnOptions } from 'node:child_process';
+import { z } from 'zod';
+import { NdjsonParser } from '../protocol/ndjson';
+import { MAX_FRAME_BYTES } from '../../shared/frame';
+import { OrderedWriter } from './writer';
+
+const frameSchema = z.object({ type: z.literal('terminal.frame'), encoding: z.literal('ansi'), seq: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER), width: z.number().int().min(1).max(500), height: z.number().int().min(1).max(300), full: z.boolean(), bytes: z.string().max(Math.ceil(MAX_FRAME_BYTES / 3) * 4).regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/) });
+export type TerminalFrame = { seq: number; width: number; height: number; full: boolean; bytes: Uint8Array };
+export type TerminalStream = { send(command: Record<string, unknown>): void; close(): void; disconnect?(): void };
+const closeReason = (text: string, fallback: string) => /controller.*(already|conflict|in use)|already.*(controlled|controller|attached client)/i.test(text) ? 'controller_conflict' : /controller.*(replaced|taken.over)|terminal attach taken over/i.test(text) ? 'taken_over' : fallback;
+
+export function openCliStream(command: string, args: string[], options: SpawnOptions, onFrame: (frame: TerminalFrame) => void, onClose: (reason: string) => void): TerminalStream {
+  const child = spawn(command, args, { ...options, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+  child.stdin!.on('error', () => {});
+  let closed = false;
+  let first = true;
+  let stderrBytes = 0;
+  let stderr = '';
+  const writer = new OrderedWriter(child.stdin!, () => finish('writer_failed'));
+  const finish = (reason: string, release = true) => {
+    if (closed) return;
+    closed = true; clearTimeout(timer); writer.close();
+    if (release) child.stdin?.end(JSON.stringify({ type: 'terminal.release' }) + '\n');
+    else { child.stdin?.destroy(); child.kill('SIGTERM'); }
+    const kill = setTimeout(() => child.kill('SIGTERM'), 200);
+    kill.unref(); child.once('exit', () => clearTimeout(kill));
+    onClose(reason);
+  };
+  const timer = setTimeout(() => finish('terminal_timeout'), 5000);
+  const parser = new NdjsonParser((record) => {
+    const closedRecord = z.object({ type: z.literal('terminal.closed'), reason: z.string() }).safeParse(record);
+    if (closedRecord.success) { finish(closeReason(closedRecord.data.reason, 'terminal_closed')); return; }
+    const value = frameSchema.parse(record);
+    const bytes = Buffer.from(value.bytes, 'base64');
+    if (bytes.length > MAX_FRAME_BYTES || (first && !value.full)) throw new Error('baseline_required');
+    first = false; clearTimeout(timer);
+    onFrame({ ...value, bytes });
+  }, 400 * 1024);
+  child.stdout!.on('data', (chunk: Buffer) => { try { parser.push(chunk); } catch { finish('invalid_terminal_frame'); } });
+  child.stderr!.on('data', (chunk: Buffer) => { stderrBytes += chunk.length; if (stderrBytes > 16 * 1024) finish('terminal_stderr_limit'); else stderr += chunk.toString(); });
+  child.on('error', () => finish('terminal_unavailable'));
+  child.on('exit', () => { try { parser.end(); } catch { finish('partial_terminal_frame'); } finish(closeReason(stderr, 'terminal_exited')); });
+  return { send: (command) => { if (closed) throw new Error('terminal_closed'); writer.send(command); }, close: () => finish('released'), disconnect: () => finish('disconnected', false) };
+}

package/src/server/terminal/hub.ts

@@ -0,0 +1,140 @@
+import type { WebSocket } from 'ws';
+import type { RuntimeManager } from '../runtime/manager';
+import { encodeFrame, FrameSequence } from '../../shared/frame';
+import type { TerminalAction } from '../../shared/runtime';
+import type { TerminalFrame, TerminalStream } from './cli';
+import { encodeUserInput } from './writer';
+import { perfLog } from '../perf-log';
+
+type Lease = { id: number; generation: number; terminalId: string; machineId: string; threadId: string; mode: string; stream?: TerminalStream; outstanding: Map<number, number>; bytes: number; sequence: FrameSequence; baselineReady: boolean; outputSeq: number; started: boolean; baselineSeq?: number; expectedSize?: [number, number]; timer?: ReturnType<typeof setTimeout>; scrollAt?: number; scrollMode?: { value: 'scrollback' | 'app'; checkedAt: number } };
+const MAX_WHEEL_TICKS = 30;
+const SCROLL_MODE_CHECK_MS = 1000;
+type SharedControl = { stream: TerminalStream; sequence: FrameSequence; members: Map<Lease, string>; closed: boolean };
+export class TerminalHub {
+  private viewers = new Map<string, { socket: WebSocket; leases: Map<number, Lease>; bytes: number }>();
+  private controllers = new Map<string, SharedControl>();
+  private expiry: ReturnType<typeof setInterval>;
+  constructor(private manager: RuntimeManager, private streamBudget = 512 * 1024, private totalBudget = 2 * 1024 * 1024) {
+    this.expiry = setInterval(() => { for (const [owner, viewer] of this.viewers) for (const lease of viewer.leases.values()) if (lease.mode === 'control') { try { if (!manager.binding(lease.machineId, lease.threadId, lease.terminalId).writable) this.release(owner, lease.id, 'capability_revoked'); } catch { this.release(owner, lease.id, 'binding_invalid'); } } }, 250);
+    this.expiry.unref();
+    manager.on('projection', () => { for (const [owner, viewer] of this.viewers) for (const lease of viewer.leases.values()) { try { manager.binding(lease.machineId, lease.threadId, lease.terminalId); } catch { this.release(owner, lease.id, 'binding_invalid'); } } });
+  }
+  close() { clearInterval(this.expiry); for (const owner of this.viewers.keys()) this.detach(owner); }
+  attach(owner: string, socket: WebSocket) { if (this.viewers.has(owner)) throw new Error('duplicate_terminal_socket'); this.viewers.set(owner, { socket, leases: new Map(), bytes: 0 }); }
+  detach(owner: string) { const viewer = this.viewers.get(owner); if (!viewer) return; for (const lease of [...viewer.leases.values()]) this.release(owner, lease.id, 'connection_closed'); this.viewers.delete(owner); }
+  action(owner: string, action: TerminalAction) {
+    const viewer = this.viewers.get(owner);
+    if (!viewer) throw new Error('viewer_missing');
+    if (action.type === 'open') {
+      if (viewer.leases.size >= 16 || viewer.leases.has(action.streamId)) throw new Error('stream_limit');
+      const target = this.manager.binding(action.machineId, action.threadId, action.terminalId);
+      if (action.mode === 'control' && !target.writable) throw new Error('read_only_target');
+      const controllerKey = action.machineId + '\0' + action.terminalId;
+      const lease: Lease = { id: action.streamId, generation: action.generation, machineId: action.machineId, threadId: action.threadId, terminalId: action.terminalId, mode: action.mode, outstanding: new Map(), bytes: 0, sequence: new FrameSequence(), baselineReady: false, outputSeq: 0, started: false };
+      viewer.leases.set(lease.id, lease);
+      try {
+        lease.stream = action.mode === 'control'
+          ? this.joinControl(controllerKey, owner, lease, action, target)
+          : target.openTerminal(action.terminalId, action.mode, action.cols, action.rows, action.takeover, (frame) => this.deliver(owner, lease, frame), (reason) => this.release(owner, lease.id, reason));
+        if (viewer.leases.get(lease.id) !== lease) lease.stream.close();
+        else this.notice(viewer.socket, { type: 'stream.opened', streamId: lease.id, generation: lease.generation, writable: action.mode === 'control' });
+      } catch (error) { this.release(owner, lease.id, 'open_failed'); throw error; }
+      return;
+    }
+    const lease = viewer.leases.get(action.streamId);
+    if (!lease || lease.generation !== action.generation) throw new Error('stale_lease');
+    if (action.type === 'release') { this.release(owner, lease.id, 'released'); return; }
+    if (action.type === 'ack') {
+      const bytes = lease.outstanding.get(action.seq);
+      if (!bytes || lease.outstanding.keys().next().value !== action.seq) throw new Error('invalid_ack');
+      lease.outstanding.delete(action.seq); lease.bytes -= bytes; viewer.bytes -= bytes;
+      if (action.seq === lease.baselineSeq) lease.baselineReady = true;
+      clearTimeout(lease.timer); lease.timer = lease.outstanding.size ? setTimeout(() => this.release(owner, lease.id, 'ack_timeout'), 5000) : undefined;
+      return;
+    }
+    const target = this.manager.binding(lease.machineId, lease.threadId, lease.terminalId);
+    if (lease.mode !== 'control') throw new Error('observer_read_only');
+    if (!target.writable) { this.release(owner, lease.id, 'capability_revoked'); throw new Error('read_only_target'); }
+    if (action.type !== 'resize' && !lease.baselineReady) throw new Error('baseline_not_acknowledged');
+    if (action.type === 'input') lease.stream?.send({ type: 'terminal.input', text: encodeUserInput(action.text, action.paste) });
+    if (action.type === 'resize') { lease.baselineReady = false; lease.baselineSeq = undefined; lease.expectedSize = [action.cols, action.rows]; lease.stream?.send({ type: 'terminal.resize', cols: action.cols, rows: action.rows }); }
+    if (action.type === 'scroll') lease.scrollAt ??= performance.now();
+    if (action.type === 'scroll') this.scroll(lease, target, action);
+    if (action.type === 'mouse') lease.stream?.send({ type: 'terminal.mouse', action: action.action, button: action.button, column: action.column, row: action.row, modifiers: action.modifiers });
+  }
+  private joinControl(key: string, owner: string, lease: Lease, action: Extract<TerminalAction, { type: 'open' }>, target: ReturnType<RuntimeManager['binding']>): TerminalStream {
+    let shared = this.controllers.get(key);
+    if (shared) {
+      shared.members.set(lease, owner); lease.expectedSize = [action.cols, action.rows];
+      shared.stream.send({ type: 'terminal.resize', cols: action.cols, rows: action.rows });
+    } else {
+      const created: SharedControl = { stream: undefined as unknown as TerminalStream, sequence: new FrameSequence(), members: new Map([[lease, owner]]), closed: false };
+      this.controllers.set(key, created);
+      try { created.stream = target.openTerminal(action.terminalId, 'control', action.cols, action.rows, action.takeover, (frame) => this.fanOut(key, created, frame), (reason) => this.closeShared(key, created, reason)); }
+      catch (error) { this.controllers.delete(key); throw error; }
+      shared = created;
+    }
+    const joined = shared;
+    return { send: (command) => joined.stream.send(command), close: () => this.leave(key, joined, lease) };
+  }
+  private leave(key: string, shared: SharedControl, lease: Lease) {
+    shared.members.delete(lease);
+    if (shared.members.size || shared.closed) return;
+    shared.closed = true;
+    if (this.controllers.get(key) === shared) this.controllers.delete(key);
+    shared.stream.close();
+  }
+  private closeShared(key: string, shared: SharedControl, reason: string) {
+    shared.closed = true;
+    if (this.controllers.get(key) === shared) this.controllers.delete(key);
+    const members = [...shared.members]; shared.members.clear();
+    for (const [lease, owner] of members) this.release(owner, lease.id, reason);
+  }
+  private fanOut(key: string, shared: SharedControl, frame: TerminalFrame) {
+    try { shared.sequence.accept({ ...frame, streamId: 0, generation: 0 }); } catch { shared.stream.close(); this.closeShared(key, shared, 'stream_resync_required'); return; }
+    for (const [lease, owner] of [...shared.members]) this.deliver(owner, lease, frame);
+  }
+  private deliver(owner: string, lease: Lease, upstream: TerminalFrame) {
+    const viewer = this.viewers.get(owner);
+    if (!viewer || viewer.leases.get(lease.id) !== lease) return;
+    if (!lease.started) { if (!upstream.full) return; lease.started = true; }
+    const frame = { ...upstream, seq: ++lease.outputSeq, streamId: lease.id, generation: lease.generation };
+    try {
+      lease.sequence.accept(frame);
+      const packet = encodeFrame(frame);
+      if (lease.bytes + packet.length > this.streamBudget || viewer.bytes + packet.length > this.totalBudget || viewer.socket.bufferedAmount + packet.length > this.totalBudget) throw new Error('viewer_overload');
+      lease.outstanding.set(frame.seq, packet.length); lease.bytes += packet.length; viewer.bytes += packet.length;
+      if (frame.full && !lease.baselineReady && (!lease.expectedSize || frame.width === lease.expectedSize[0] && frame.height === lease.expectedSize[1])) lease.baselineSeq = frame.seq;
+      lease.timer ??= setTimeout(() => this.release(owner, lease.id, 'ack_timeout'), 5000);
+      viewer.socket.send(packet, { binary: true });
+      this.logScrollReply(lease, frame.full, packet.length, viewer.socket.bufferedAmount);
+    } catch { this.release(owner, lease.id, 'stream_resync_required'); }
+  }
+  /** Herdr always puts wheel ticks of full-screen apps at the top-left cell, so those get SGR wheel reports at the pointer instead. */
+  private scroll(lease: Lease, target: ReturnType<RuntimeManager['binding']>, action: { direction: 'up' | 'down'; lines: number; column?: number; row?: number }) {
+    this.refreshScrollMode(lease, target);
+    if (lease.scrollMode?.value !== 'app') { lease.stream?.send({ type: 'terminal.scroll', direction: action.direction, lines: action.lines }); return; }
+    const report = `\x1b[<${action.direction === 'up' ? 64 : 65};${action.column ?? 1};${action.row ?? 1}M`;
+    lease.stream?.send({ type: 'terminal.input', text: report.repeat(Math.min(action.lines, MAX_WHEEL_TICKS)) });
+  }
+  private refreshScrollMode(lease: Lease, target: ReturnType<RuntimeManager['binding']>) {
+    if (!target.scrollMode || lease.scrollMode && Date.now() - lease.scrollMode.checkedAt < SCROLL_MODE_CHECK_MS) return;
+    lease.scrollMode = { value: lease.scrollMode?.value ?? 'scrollback', checkedAt: Date.now() };
+    void target.scrollMode(lease.terminalId).then((value) => { lease.scrollMode = { value, checkedAt: Date.now() }; }, () => undefined);
+  }
+  private logScrollReply(lease: Lease, full: boolean, bytes: number, buffered: number) {
+    if (lease.scrollAt === undefined) return;
+    perfLog('server', { event: 'scroll.reply', herdrRoundTripMs: performance.now() - lease.scrollAt, full, bytes, socketBufferedBytes: buffered });
+    lease.scrollAt = undefined;
+  }
+  stats() { return { viewers: this.viewers.size, controllers: this.controllers.size, bytes: [...this.viewers.values()].reduce((total, viewer) => total + viewer.bytes, 0) }; }
+  private release(owner: string, id: number, reason: string) {
+    const viewer = this.viewers.get(owner);
+    const lease = viewer?.leases.get(id);
+    if (!viewer || !lease) return;
+    viewer.leases.delete(id); viewer.bytes -= lease.bytes; clearTimeout(lease.timer);
+    lease.stream?.close();
+    this.notice(viewer.socket, { type: 'stream.closed', streamId: id, generation: lease.generation, reason });
+  }
+  private notice(socket: WebSocket, value: Record<string, unknown>) { if (socket.readyState === 1) socket.send(JSON.stringify(value)); }
+}

package/src/server/terminal/writer.ts

@@ -0,0 +1,38 @@
+import type { Writable } from 'node:stream';
+
+export class OrderedWriter {
+  private queue: Buffer[] = [];
+  private bytes = 0;
+  private writing = false;
+  private closed = false;
+  private timer?: ReturnType<typeof setTimeout>;
+  constructor(private sink: Writable, private fail: () => void, private budget = 32 * 1024, private deadline = 2000) {}
+  send(command: Record<string, unknown>) {
+    if (this.closed) throw new Error('writer_closed');
+    const bytes = Buffer.from(JSON.stringify(command) + '\n');
+    if (this.bytes + bytes.length > this.budget) { this.close(); this.fail(); throw new Error('input_overload'); }
+    this.queue.push(bytes); this.bytes += bytes.length; this.flush();
+  }
+  close() { this.closed = true; this.queue = []; this.bytes = 0; clearTimeout(this.timer); }
+  private flush() {
+    if (this.writing || this.closed || !this.queue.length) return;
+    this.writing = true;
+    const next = this.queue.shift()!;
+    this.timer = setTimeout(() => { this.close(); this.fail(); }, this.deadline);
+    this.sink.write(next, (error?: Error | null) => {
+      clearTimeout(this.timer);
+      this.writing = false;
+      if (this.closed) return;
+      this.bytes -= next.length;
+      if (error) { this.close(); this.fail(); return; }
+      this.flush();
+    });
+  }
+}
+
+export function encodeUserInput(text: string, paste: boolean): string {
+  if (Buffer.byteLength(text) > 8192 || text.includes('\x1b[200~') || text.includes('\x1b[201~') || text.includes('\0')) throw new Error('invalid_input');
+  if (!paste) return text;
+  if (/[\x00-\x08\x0b-\x1f\x7f]/.test(text)) throw new Error('invalid_paste');
+  return '\x1b[200~' + text + '\x1b[201~';
+}