@pablopunk/webr 0.1.1

package/src/server/protocol/ndjson.ts

@@ -0,0 +1,22 @@
+export class NdjsonParser {
+  private pending = Buffer.alloc(0);
+  constructor(private onRecord: (record: unknown) => void, private limit = 1024 * 1024) {}
+  push(chunk: Buffer) {
+    let start = 0;
+    for (let index = 0; index < chunk.length; index++) {
+      if (chunk[index] !== 10) continue;
+      this.append(chunk.subarray(start, index));
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(this.pending);
+      this.pending = Buffer.alloc(0);
+      if (!text.trim()) throw new Error('empty_record');
+      this.onRecord(JSON.parse(text));
+      start = index + 1;
+    }
+    this.append(chunk.subarray(start));
+  }
+  end() { if (this.pending.length) throw new Error('partial_record'); }
+  private append(chunk: Buffer) {
+    if (this.pending.length + chunk.length > this.limit) throw new Error('record_limit');
+    if (chunk.length) this.pending = Buffer.concat([this.pending, chunk]);
+  }
+}

package/src/server/protocol/socket.ts

@@ -0,0 +1,81 @@
+import { connect, type Socket } from 'node:net';
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { NdjsonParser } from './ndjson';
+import { lifecycleSubscriptions } from './native';
+import { requestDeadline, type RpcOptions } from './deadlines';
+
+const envelope = z.object({ id: z.string(), result: z.record(z.string(), z.unknown()).optional(), error: z.object({ code: z.string(), message: z.string() }).optional() });
+const allowed = new Set(['ping', 'session.snapshot', 'events.subscribe', 'server.agent_manifests', 'workspace.create', 'worktree.create', 'worktree.list', 'worktree.open', 'tab.create', 'agent.start', 'agent.get', 'agent.prompt', 'pane.process_info', 'pane.read', 'pane.focus', 'tab.close', 'workspace.close', 'worktree.remove', 'tab.rename', 'workspace.rename', 'pane.split', 'pane.close']);
+export class SocketApi {
+  private sockets = new Set<Socket>();
+  constructor(readonly path: string, readonly deadline = 5000, private methods: ReadonlySet<string> = allowed) {}
+  request(method: string, params: Record<string, unknown> = {}, options?: RpcOptions): Promise<Record<string, unknown>> {
+    if (!this.methods.has(method) || method === 'events.subscribe') return Promise.reject(new Error('method_not_allowed'));
+    let deadline: number;
+    try { deadline = requestDeadline(method, params, this.deadline, options); } catch (error) { return Promise.reject(error); }
+    return new Promise((resolve, reject) => {
+      const id = options?.requestId ?? randomUUID();
+      const socket = this.open();
+      let done = false;
+      const finish = (error?: Error, result?: Record<string, unknown>) => {
+        if (done) return;
+        done = true; clearTimeout(timer); socket.destroy();
+        if (error) reject(error); else resolve(result!);
+      };
+      const timer = setTimeout(() => finish(new Error('rpc_timeout')), deadline);
+      const parser = new NdjsonParser((value) => {
+        const record = envelope.parse(value);
+        if (record.id !== id) throw new Error('request_id_mismatch');
+        if (record.error) throw new Error(record.error.code);
+        if (!record.result) throw new Error('missing_result');
+        finish(undefined, record.result);
+      });
+      socket.on('connect', () => socket.write(JSON.stringify({ id, method, params }) + '\n'));
+      socket.on('data', (chunk) => { try { parser.push(chunk); } catch (error) { finish(error as Error); } });
+      socket.on('error', (error: NodeJS.ErrnoException) => finish(Object.assign(new Error('socket_unavailable', { cause: error }), { code: error.code })));
+      socket.on('close', () => finish(new Error('rpc_closed')));
+      socket.on('end', () => { try { parser.end(); finish(new Error('rpc_closed')); } catch (error) { finish(error as Error); } });
+    });
+  }
+  subscribe(onEvent: () => void, onClose: (reason: string) => void, paneIds: string[] = []): Promise<() => void> {
+    return new Promise((resolve, reject) => {
+      const socket = this.open();
+      const id = randomUUID();
+      let acknowledged = false;
+      let closed = false;
+      const stop = (reason: string, notify = true) => {
+        if (closed) return;
+        closed = true; clearTimeout(timer); socket.destroy();
+        if (!acknowledged) reject(new Error(reason));
+        else if (notify) onClose(reason);
+      };
+      const timer = setTimeout(() => stop('subscription_timeout'), this.deadline);
+      const parser = new NdjsonParser((value) => {
+        const response = envelope.safeParse(value);
+        if (response.success) {
+          if (response.data.id !== id) throw new Error('request_id_mismatch');
+          if (response.data.error) throw new Error(response.data.error.code);
+          if (acknowledged || response.data.result?.type !== 'subscription_started') throw new Error('invalid_ack');
+          acknowledged = true; clearTimeout(timer); resolve(() => stop('released', false));
+        } else {
+          z.object({ event: z.string(), data: z.unknown() }).parse(value);
+          if (!acknowledged) throw new Error('event_before_ack');
+          onEvent();
+        }
+      });
+      socket.on('connect', () => socket.write(JSON.stringify({ id, method: 'events.subscribe', params: { subscriptions: [...lifecycleSubscriptions, ...paneIds.map((pane_id) => ({ type: 'pane.agent_status_changed', pane_id }))] } }) + '\n'));
+      socket.on('data', (chunk) => { try { parser.push(chunk); } catch (error) { stop((error as Error).message); } });
+      socket.on('error', () => stop('socket_unavailable'));
+      socket.on('end', () => stop('subscription_closed'));
+      socket.on('close', () => stop('subscription_closed'));
+    });
+  }
+  close() { for (const socket of this.sockets) socket.destroy(); }
+  private open() {
+    const socket = connect(this.path);
+    this.sockets.add(socket);
+    socket.once('close', () => this.sockets.delete(socket));
+    return socket;
+  }
+}

package/src/server/protocol/validate.ts

@@ -0,0 +1,17 @@
+type SchemaNode = { const?: unknown; required?: string[]; properties?: Record<string, SchemaNode>; oneOf?: SchemaNode[]; $defs?: Record<string, SchemaNode> };
+type Schema = { protocol?: number; schemas?: Record<string, SchemaNode> };
+export function validateInstalledSchema(schema: Schema) {
+  const errors: string[] = [];
+  if (schema.protocol !== 22) errors.push('Unsupported protocol: expected 22');
+  const request = schema.schemas?.request;
+  const methods = new Set(request?.oneOf?.map((variant) => variant.properties?.method?.const));
+  for (const method of ['ping', 'session.snapshot', 'events.subscribe', 'tab.create', 'worktree.create', 'agent.start', 'agent.get', 'agent.prompt']) if (!methods.has(method)) errors.push('Missing method: ' + method);
+  const requiredFields = { SessionSnapshot: ['version', 'protocol', 'workspaces', 'tabs', 'panes', 'layouts', 'agents'], PaneInfo: ['pane_id', 'terminal_id', 'workspace_id', 'tab_id'], PaneLayoutSnapshot: ['area', 'panes', 'tab_id', 'workspace_id'] };
+  for (const [record, fields] of Object.entries(requiredFields)) for (const field of fields) if (!schema.schemas?.success_response?.$defs?.[record]?.required?.includes(field)) errors.push('Missing required response field: ' + record + '.' + field);
+  if (!request?.$defs?.EventsSubscribeParams?.required?.includes('subscriptions')) errors.push('Missing EventsSubscribeParams.subscriptions');
+  for (const [record, fields] of Object.entries({ AgentStartParams: ['name', 'kind', 'pane_id', 'args', 'timeout_ms'], AgentPromptParams: ['target', 'text'], TabCreateParams: ['workspace_id', 'cwd', 'focus'], WorktreeCreateParams: ['workspace_id', 'branch', 'focus'] })) for (const field of fields) if (!request?.$defs?.[record]?.properties?.[field]) errors.push('Missing request field: ' + record + '.' + field);
+  const statusSubscription = request?.$defs?.Subscription?.oneOf?.find((variant) => variant.properties?.type?.const === 'pane.agent_status_changed');
+  if (!statusSubscription?.required?.includes('pane_id')) errors.push('Missing pane-scoped status subscription');
+  for (const field of ['name', 'pane_id', 'terminal_id', 'agent', 'agent_status']) if (!schema.schemas?.success_response?.$defs?.AgentInfo?.properties?.[field]) errors.push('Missing agent identity field: ' + field);
+  return errors;
+}

package/src/server/public-urls.ts

@@ -0,0 +1,17 @@
+import { networkInterfaces } from 'node:os';
+import { isLoopbackHost } from './auth/access';
+
+const WILDCARD_HOSTS = new Set(['0.0.0.0', '::', '[::]']);
+type Interfaces = ReturnType<typeof networkInterfaces>;
+
+const VIRTUAL_INTERFACE = /^(bridge|vmnet|docker|br-|veth|vboxnet|virbr|vethernet)/i;
+
+const lanAddresses = (interfaces: Interfaces) => Object.entries(interfaces).filter(([name]) => !VIRTUAL_INTERFACE.test(name)).flatMap(([, list]) => list ?? []).filter((entry) => entry.family === 'IPv4' && !entry.internal).map((entry) => entry.address);
+
+export function publicUrls(origin: string, host: string, port: number, interfaces: Interfaces = networkInterfaces(), tailscaleHost?: string) {
+  const { protocol, host: originHost } = new URL(origin);
+  const reachable = WILDCARD_HOSTS.has(host) ? lanAddresses(interfaces) : isLoopbackHost(host) ? [] : [host];
+  const named = tailscaleHost && WILDCARD_HOSTS.has(host) ? [tailscaleHost] : [];
+  const urls = [...named, ...reachable].map((address) => `${protocol}//${address}:${port}`);
+  return [...new Set([...(isLoopbackHost(originHost) ? [] : [origin]), ...urls])];
+}

package/src/server/runtime/herdr-actions.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { acceptsModelFlag, isHerdrAgentKind } from '../../shared/agent-kinds';
+import type { LaunchInput } from '../../shared/runtime';
+import type { LaunchLocation, TerminalDirection } from './target';
+import { nativePane, nativeTab, type NativeSnapshot } from '../protocol/native';
+import { AGENT_READY_TIMEOUT_MS, SCREEN_SETTLE_TIMEOUT_MS, SHELL_READY_TIMEOUT_MS, requestDeadline, type RpcOptions } from '../protocol/deadlines';
+
+type Api = { request(method: string, params?: Record<string, unknown>, options?: RpcOptions): Promise<Record<string, unknown>> };
+const agentShape = { name: z.string(), terminal_id: z.string(), pane_id: z.string(), agent_status: z.enum(['idle', 'done', 'working', 'blocked', 'unknown']) };
+const startedAgent = z.object({ ...agentShape, agent: z.string() });
+const detectingAgent = z.object({ ...agentShape, agent: z.string().nullable().optional() });
+const processInfo = z.object({ shell_pid: z.number().int().positive(), foreground_processes: z.array(z.object({ pid: z.number().int().positive() })) });
+const worktreeEntry = z.object({ path: z.string(), branch: z.string().nullable().optional(), label: z.string(), is_bare: z.boolean(), is_prunable: z.boolean(), open_workspace_id: z.string().nullable().optional() });
+export type WorktreeEntry = z.infer<typeof worktreeEntry>;
+const SETTLE_INTERVAL_MS = 350;
+const AGENT_SHARE_OF_TERMINAL_SPLIT = 0.5;
+const SETTLED_READS = 3;
+const pause = (ms: number) => new Promise<void>((done) => setTimeout(done, ms));
+export function modelArguments(kind: string, model: string): string[] {
+  if (!isHerdrAgentKind(kind) || !/^[A-Za-z0-9_/.:+-]{1,120}$/.test(model)) throw new Error('unsupported_launch_adapter');
+  if (model === 'Default') return [];
+  if (!acceptsModelFlag(kind)) throw new Error('unsupported_launch_adapter');
+  return ['--model', model];
+}
+export const agentName = (threadId: string) => 'web-' + threadId.replaceAll('-', '').slice(0, 28);
+
+export class HerdrActions {
+  constructor(private api: Api, private locations: LaunchLocation[], private requireCapability: (input?: LaunchInput) => void) {}
+  async create(input: LaunchInput, threadId: string) {
+    this.requireCapability(input);
+    const location = this.locations.find((location) => location.projectId === input.projectId);
+    if (!location) throw new Error('unknown_project_location');
+    const result = await this.api.request(input.worktree ? 'worktree.create' : 'tab.create', input.worktree
+      ? { workspace_id: location.workspaceId, branch: 'web/' + threadId, label: input.prompt.split('\n')[0].slice(0, 90), focus: false }
+      : { workspace_id: location.workspaceId, cwd: location.path, label: input.prompt.split('\n')[0].slice(0, 90), focus: false }, { timeoutMs: requestDeadline(input.worktree ? 'worktree.create' : 'tab.create', {}) });
+    if (result.type !== (input.worktree ? 'worktree_created' : 'tab_created')) throw new Error('unexpected_create_result');
+    const pane = nativePane.parse(result.root_pane); const tab = nativeTab.parse(result.tab);
+    if (pane.tab_id !== tab.tab_id || pane.workspace_id !== tab.workspace_id) throw new Error('inconsistent_create_result');
+    return { paneId: pane.pane_id, terminalId: pane.terminal_id, tabId: tab.tab_id, workspaceId: pane.workspace_id };
+  }
+  async start(input: LaunchInput, paneId: string, threadId: string) {
+    this.requireCapability(input);
+    await this.untilShellReady(paneId);
+    const params = { name: agentName(threadId), kind: input.agent, pane_id: paneId, args: modelArguments(input.agent, input.model), timeout_ms: AGENT_READY_TIMEOUT_MS };
+    const result = await this.startWhenPromptReady(params);
+    if (result.type !== 'agent_started') throw new Error('agent_not_ready');
+    const isReady = (agent: z.infer<typeof detectingAgent>) => agent.name === params.name && agent.pane_id === paneId && agent.agent === input.agent && ['idle', 'done'].includes(agent.agent_status);
+    const started = detectingAgent.parse(result.agent);
+    if (started.name !== params.name || started.pane_id !== paneId) throw new Error('agent_not_ready');
+    if (!isReady(started)) await this.untilReady(params.name, isReady);
+  }
+  private async startWhenPromptReady(params: Record<string, unknown>) {
+    const end = Date.now() + SHELL_READY_TIMEOUT_MS;
+    for (;;) {
+      try { return await this.api.request('agent.start', params, { timeoutMs: requestDeadline('agent.start', params) }); }
+      catch (error) { if (!(error instanceof Error) || error.message !== 'agent_pane_busy' || Date.now() >= end) throw error; await pause(500); }
+    }
+  }
+  private async untilShellReady(paneId: string) {
+    const end = Date.now() + SHELL_READY_TIMEOUT_MS;
+    do {
+      const info = processInfo.safeParse((await this.api.request('pane.process_info', { pane_id: paneId })).process_info);
+      if (info.success && info.data.foreground_processes.length && info.data.foreground_processes.every((process) => process.pid === info.data.shell_pid)) return;
+      await pause(250);
+    } while (Date.now() < end);
+    throw new Error('shell_not_ready');
+  }
+  private async untilReady(name: string, isReady: (agent: z.infer<typeof detectingAgent>) => boolean) {
+    const end = Date.now() + AGENT_READY_TIMEOUT_MS;
+    do {
+      const current = detectingAgent.safeParse((await this.api.request('agent.get', { target: name })).agent);
+      if (current.success && isReady(current.data)) return;
+      await pause(250);
+    } while (Date.now() < end);
+    throw new Error('agent_not_ready');
+  }
+  async worktrees(workspaceId: string) { return z.array(worktreeEntry).parse((await this.api.request('worktree.list', { workspace_id: workspaceId })).worktrees); }
+  async openWorktree(workspaceId: string, path: string) { await this.api.request('worktree.open', { workspace_id: workspaceId, path, focus: false }); }
+  async focus(paneId: string) { await this.api.request('pane.focus', { pane_id: paneId }); }
+  async splitTerminal(snapshot: NativeSnapshot, paneId: string, direction: TerminalDirection) {
+    const pane = snapshot.panes.find((pane) => pane.pane_id === paneId);
+    if (!pane) throw new Error('thread_not_found');
+    const result = await this.api.request('pane.split', { target_pane_id: paneId, direction, ratio: AGENT_SHARE_OF_TERMINAL_SPLIT, cwd: pane.cwd ?? null, focus: false });
+    return nativePane.parse(result.pane).pane_id;
+  }
+  async closePane(paneId: string) { await this.api.request('pane.close', { pane_id: paneId }); }
+  async renameTab(snapshot: NativeSnapshot, tabId: string, label: string, renameWorkspace: boolean) {
+    const tab = snapshot.tabs.find((tab) => tab.tab_id === tabId);
+    if (!tab) throw new Error('thread_not_found');
+    await this.api.request('tab.rename', { tab_id: tabId, label });
+    if (renameWorkspace && this.isOnlyTabOfItsWorkspace(snapshot, tab)) await this.api.request('workspace.rename', { workspace_id: tab.workspace_id, label });
+  }
+  private isOnlyTabOfItsWorkspace(snapshot: NativeSnapshot, tab: NativeSnapshot['tabs'][number]) {
+    return snapshot.tabs.filter((other) => other.workspace_id === tab.workspace_id).length === 1;
+  }
+  async discardTab(snapshot: NativeSnapshot, tabId: string, removeWorktree: boolean) {
+    const tab = snapshot.tabs.find((tab) => tab.tab_id === tabId);
+    if (!tab) return;
+    const linkedWorktree = snapshot.workspaces.find((workspace) => workspace.workspace_id === tab.workspace_id)?.worktree?.is_linked_worktree;
+    if (removeWorktree && linkedWorktree && this.isOnlyTabOfItsWorkspace(snapshot, tab)) await this.api.request('worktree.remove', { workspace_id: tab.workspace_id, force: true });
+    else await this.api.request('tab.close', { tab_id: tabId });
+  }
+  async prompt(paneId: string, prompt: string, terminalId: string, threadId: string, kind: string, input?: LaunchInput) {
+    this.requireCapability(input);
+    const name = agentName(threadId);
+    const result = await this.api.request('agent.get', { target: name });
+    const agent = startedAgent.parse(result.agent);
+    if (agent.name !== name || agent.terminal_id !== terminalId || agent.pane_id !== paneId || agent.agent !== kind || !['idle', 'done'].includes(agent.agent_status)) throw new Error('agent_occupant_changed');
+    await this.untilScreenSettles(paneId);
+    await this.api.request('agent.prompt', { target: name, text: prompt });
+  }
+  private async untilScreenSettles(paneId: string) {
+    const read = async () => z.object({ text: z.string() }).safeParse((await this.api.request('pane.read', { pane_id: paneId, source: 'recent_unwrapped', format: 'text', strip_ansi: true, lines: 120 })).read).data?.text;
+    const end = Date.now() + SCREEN_SETTLE_TIMEOUT_MS;
+    let previous = await read(); let unchanged = 0;
+    while (Date.now() < end && unchanged < SETTLED_READS) {
+      await pause(SETTLE_INTERVAL_MS);
+      const current = await read();
+      unchanged = current !== undefined && current === previous ? unchanged + 1 : 0; previous = current;
+    }
+  }
+}

package/src/server/runtime/launch.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from 'node:crypto';
+import type { MetadataDatabase } from '../storage/database';
+import type { TargetAdapter } from './target';
+import type { LaunchInput } from '../../shared/runtime';
+import type { Thread } from '../../lib/models';
+
+export class LaunchJournal {
+  private queues = new Map<string, Promise<void>>();
+  private stopping = false;
+  constructor(private database: MetadataDatabase, private publish: () => void) { database.markInterruptedLaunches(); }
+  submit(accountId: string, key: string, input: LaunchInput, target: TargetAdapter) {
+    if (this.stopping) throw new Error('gateway_stopping');
+    const thread: Thread = { id: randomUUID(), avatarIndex: this.database.nextAvatarIndex(), projectId: input.projectId, machineId: target.id, title: input.prompt.split('\n')[0].slice(0, 90), prompt: input.prompt, agent: input.agent, model: input.model, status: 'unknown', updatedAt: new Date().toISOString(), branch: '', worktree: input.worktree, ownsWorktree: input.worktree, session: target.session, tabId: '', panes: [], bindingState: 'pending', bindingFingerprint: target.fingerprint, bindingConfigVersion: target.configVersion };
+    const { operation, created } = this.database.beginLaunch(accountId, key, input, thread);
+    if (created) {
+      const scope = target.id + '\0' + input.projectId;
+      const previous = this.queues.get(scope) ?? Promise.resolve();
+      const next = previous.then(() => this.run(operation.id, input, target, thread));
+      this.queues.set(scope, next);
+      void next.finally(() => { if (this.queues.get(scope) === next) this.queues.delete(scope); });
+      this.publish();
+    }
+    return { operationId: operation.id, id: operation.threadId, state: operation.state };
+  }
+  async stop() { this.stopping = true; await Promise.allSettled([...this.queues.values()]); }
+  private async run(id: string, input: LaunchInput, target: TargetAdapter, thread: Thread) {
+    let step = 'validate';
+    let result: Record<string, unknown> = {};
+    try {
+      const catalog = await target.catalog(input.projectId);
+      if (this.stopping) throw new Error('gateway_stopping');
+      const harness = catalog.harnesses.find((harness) => harness.id === input.agent);
+      if (!catalog.connected || !harness?.launchEnabled || target.canLaunch && !target.canLaunch(input) || !target.locations.some((location) => location.projectId === input.projectId)) throw new Error('launch_unavailable');
+      step = 'checkout'; this.database.updateOperation(id, 'running', step, result); this.publish();
+      const created = await target.create(input, thread.id);
+      result = { ...created };
+      this.database.db.transaction(() => {
+        this.database.updateOperation(id, 'running', 'checkout_complete', result);
+        thread.tabId = created.tabId;
+        this.database.saveThread(thread, [created.terminalId], created.tabId);
+      });
+      if (this.stopping) throw new Error('gateway_stopping');
+      step = 'start'; this.database.updateOperation(id, 'running', step, result); this.publish();
+      await target.start(input, created.paneId, thread.id);
+      if (this.stopping) throw new Error('gateway_stopping');
+      step = 'prompt'; this.database.updateOperation(id, 'running', step, result); this.publish();
+      await target.prompt(created.paneId, input.prompt, created.terminalId, thread.id, input);
+      this.database.updateOperation(id, 'ready', 'ready', result);
+    } catch (error) {
+      console.error(`launch ${id} stopped at ${step}:`, error instanceof Error ? error.message : error);
+      this.database.updateOperation(id, step === 'validate' ? 'failed' : 'unknown', step, result);
+    }
+    this.publish();
+  }
+}

package/src/server/runtime/manager.ts

@@ -0,0 +1,187 @@
+import { EventEmitter } from 'node:events';
+import type { TargetAdapter, TerminalDirection } from './target';
+import type { Thread } from '../../lib/models';
+import { threadAgent, threadShell } from '../../lib/terminal-split';
+import { TargetSupervisor } from './supervisor';
+import { reconcile } from './reconcile';
+import type { MetadataDatabase } from '../storage/database';
+import type { Bootstrap, Projection } from '../../shared/runtime';
+import type { Machine } from '../../lib/machines';
+import { LaunchJournal } from './launch';
+
+const CATALOG_TTL_MS = 5 * 60_000;
+
+export class RuntimeManager extends EventEmitter {
+  readonly supervisors = new Map<string, TargetSupervisor>();
+  readonly journal: LaunchJournal;
+  private projections = new Map<string, Projection>();
+  private catalogs = new Map<string, { expires: number; value: Promise<Machine> }>();
+  private configVersions = new Map<string, number>();
+  constructor(readonly database: MetadataDatabase, targets: TargetAdapter[]) {
+    super(); this.setMaxListeners(100);
+    this.journal = new LaunchJournal(database, () => this.publishAll());
+    for (const target of targets) {
+      target.configVersion = database.registerProfile(target.id, target.session, JSON.stringify({ fingerprint: target.fingerprint, locations: target.locations }), target.locations);
+      this.configVersions.set(target.id, target.configVersion);
+      const supervisor = new TargetSupervisor(target, () => this.publish(supervisor));
+      if (target.enabled === false) supervisor.error = 'profile_disabled';
+      this.supervisors.set(target.id, supervisor);
+      this.publish(supervisor);
+    }
+  }
+  start() { for (const supervisor of this.supervisors.values()) if (supervisor.target.enabled !== false) void supervisor.start(); }
+  async close() { for (const supervisor of this.supervisors.values()) supervisor.stop(); await this.journal.stop(); this.removeAllListeners(); }
+  bootstrap(): Bootstrap {
+    const projections = [...this.projections.values()];
+    return { projections, projects: projections.flatMap((projection) => projection.projects), threads: projections.flatMap((projection) => projection.threads), machines: [...this.supervisors.values()].map((supervisor) => ({ id: supervisor.target.id, name: supervisor.target.name, session: supervisor.target.session, connected: supervisor.connected, projectPaths: Object.fromEntries(supervisor.target.locations.map((location) => [location.projectId, location.path])), harnesses: [], error: supervisor.error, writable: supervisor.target.writable, configVersion: this.configVersions.get(supervisor.target.id) })) };
+  }
+  private machine(supervisor: TargetSupervisor): Machine { return { id: supervisor.target.id, name: supervisor.target.name, session: supervisor.target.session, connected: supervisor.connected, configVersion: supervisor.target.configVersion, writable: supervisor.target.writable, error: supervisor.error, projectPaths: Object.fromEntries(supervisor.target.locations.map((location) => [location.projectId, location.path])), harnesses: [] }; }
+  async catalog(machineId: string, projectId?: string) {
+    const supervisor = this.supervisors.get(machineId);
+    if (!supervisor?.connected) throw new Error('machine_disconnected');
+    if (projectId && !supervisor.target.locations.some((location) => location.projectId === projectId)) throw new Error('unknown_project_location');
+    const key = JSON.stringify([machineId, supervisor.target.fingerprint, supervisor.target.session, supervisor.target.configVersion]);
+    const existing = this.catalogs.get(key);
+    if (existing && existing.expires > Date.now()) return existing.value;
+    const value = supervisor.target.catalog(projectId);
+    this.catalogs.set(key, { expires: Date.now() + CATALOG_TTL_MS, value });
+    try { return await value; } catch (error) { this.catalogs.delete(key); throw error; }
+  }
+  refreshCatalog(machineId: string) {
+    for (const key of this.catalogs.keys()) if (JSON.parse(key)[0] === machineId) this.catalogs.delete(key);
+    this.supervisors.get(machineId)?.invalidate();
+  }
+  binding(machineId: string, threadId: string, terminalId: string) {
+    const supervisor = this.supervisors.get(machineId);
+    const projection = this.projections.get(machineId);
+    const thread = projection?.threads.find((thread) => thread.id === threadId);
+    if (!supervisor?.connected || !thread || thread.bindingFingerprint !== supervisor.target.fingerprint || thread.bindingConfigVersion !== supervisor.target.configVersion || thread.session !== supervisor.target.session || thread.bindingState !== 'attached' || !thread.panes.some((pane) => pane.terminalId === terminalId)) throw new Error('binding_invalid');
+    return supervisor.target;
+  }
+  async adopt(machineId: string, threadId: string, terminalIds: string[]) {
+    const supervisor = this.supervisors.get(machineId);
+    const row = this.database.threadRows(machineId).find((row) => row.id === threadId);
+    if (!supervisor?.connected || !row || !terminalIds.length || new Set(terminalIds).size !== terminalIds.length) throw new Error('invalid_adoption');
+    const snapshot = await supervisor.readFresh();
+    const panes = snapshot.panes.filter((pane) => terminalIds.includes(pane.terminal_id));
+    const tab = panes[0]?.tab_id;
+    if (panes.length !== terminalIds.length || !tab || panes.some((pane) => pane.tab_id !== tab) || snapshot.panes.filter((pane) => pane.tab_id === tab).length !== panes.length) throw new Error('invalid_adoption');
+    if (this.projections.get(machineId)?.threads.some((other) => other.id !== threadId && other.bindingState === 'attached' && other.tabId === tab)) throw new Error('binding_conflict');
+    this.database.saveThread({ ...row.metadata, session: supervisor.target.session, tabId: tab, bindingFingerprint: supervisor.target.fingerprint, bindingConfigVersion: supervisor.target.configVersion, semanticSignature: undefined }, terminalIds, tab); this.publish(supervisor);
+  }
+  private workspacesWithThreads(machineId: string) {
+    const shownTabs = new Set(this.projections.get(machineId)?.threads.filter((thread) => thread.bindingState === 'attached' && !thread.archivedAt).map((thread) => thread.tabId));
+    return new Set(this.supervisors.get(machineId)?.snapshot?.tabs.filter((tab) => shownTabs.has(tab.tab_id)).map((tab) => tab.workspace_id));
+  }
+  private worktreeSupervisor(machineId: string) {
+    const supervisor = this.supervisors.get(machineId);
+    if (!supervisor?.connected || !supervisor.target.worktrees || !supervisor.target.openWorktree) throw new Error('machine_disconnected');
+    return supervisor;
+  }
+  async worktrees(machineId: string, projectId: string) {
+    const supervisor = this.worktreeSupervisor(machineId);
+    const shown = this.workspacesWithThreads(machineId);
+    const entries = await supervisor.target.worktrees!(projectId);
+    return entries.filter((entry) => !entry.is_bare && !entry.is_prunable && !(entry.open_workspace_id && shown.has(entry.open_workspace_id))).map((entry) => ({ path: entry.path, branch: entry.branch ?? null, label: entry.label }));
+  }
+  async openWorktree(machineId: string, projectId: string, path: string) {
+    const supervisor = this.worktreeSupervisor(machineId);
+    if (!(await this.worktrees(machineId, projectId)).some((worktree) => worktree.path === path)) throw new Error('unknown_worktree');
+    await supervisor.target.openWorktree!(projectId, path);
+    const snapshot = await supervisor.readFresh(); this.publish(supervisor);
+    const workspace = snapshot.workspaces.find((workspace) => workspace.worktree?.checkout_path === path);
+    const tab = snapshot.tabs.find((tab) => tab.workspace_id === workspace?.workspace_id);
+    const thread = this.projections.get(machineId)?.threads.find((thread) => thread.tabId === tab?.tab_id && thread.bindingState === 'attached');
+    if (!thread) throw new Error('worktree_not_opened');
+    if (thread.archivedAt) this.archive(machineId, thread.id, false);
+    return { id: thread.id };
+  }
+  async focusPane(machineId: string, threadId: string, paneId: string) {
+    const supervisor = this.supervisors.get(machineId);
+    const thread = this.projections.get(machineId)?.threads.find((thread) => thread.id === threadId);
+    if (!supervisor?.connected || !thread?.panes.some((pane) => pane.id === paneId) || !supervisor.target.focusPane) throw new Error('invalid_focus');
+    await supervisor.target.focusPane(paneId);
+  }
+  archive(machineId: string, threadId: string, archived: boolean) {
+    const supervisor = this.supervisors.get(machineId);
+    const row = this.database.threadRows(machineId).find((row) => row.id === threadId);
+    if (!supervisor || !row) throw new Error('thread_not_found');
+    this.database.saveThread({ ...row.metadata, archivedAt: archived ? new Date().toISOString() : undefined }, row.anchors, row.alias);
+    this.publish(supervisor);
+  }
+  async renameThread(machineId: string, threadId: string, title: string) {
+    const supervisor = this.supervisors.get(machineId);
+    const thread = this.projections.get(machineId)?.threads.find((thread) => thread.id === threadId);
+    if (!supervisor || !thread) throw new Error('thread_not_found');
+    if (thread.bindingState === 'attached') {
+      if (!supervisor.connected || !supervisor.target.renameTab) throw new Error('machine_disconnected');
+      await supervisor.target.renameTab(thread.tabId, title, !!thread.ownsWorktree);
+    }
+    const row = this.database.threadRows(machineId).find((row) => row.id === threadId);
+    if (row) this.database.saveThread({ ...row.metadata, title }, row.anchors, row.alias);
+    if (thread.bindingState === 'attached') await supervisor.readFresh();
+    this.publish(supervisor);
+  }
+  async toggleTerminal(machineId: string, threadId: string, direction: TerminalDirection) {
+    const { supervisor, thread } = this.attachedThread(machineId, threadId);
+    const shell = threadShell(thread);
+    const agent = threadAgent(thread);
+    if (shell) { this.saveThreadMetadata(machineId, threadId, { terminalHidden: !thread.terminalHidden }); this.publish(supervisor); return { paneId: shell.id, hidden: !thread.terminalHidden }; }
+    if (!agent || !supervisor.target.splitTerminal) throw new Error('thread_not_found');
+    const paneId = await supervisor.target.splitTerminal(agent.id, direction);
+    this.saveThreadMetadata(machineId, threadId, { terminalHidden: false });
+    await supervisor.readFresh(); this.publish(supervisor);
+    return { paneId, hidden: false };
+  }
+  async closeTerminal(machineId: string, threadId: string) {
+    const { supervisor, thread } = this.attachedThread(machineId, threadId);
+    const shell = threadShell(thread);
+    if (shell) await supervisor.target.closePane?.(shell.id);
+    this.saveThreadMetadata(machineId, threadId, { terminalHidden: false });
+    await supervisor.readFresh(); this.publish(supervisor);
+  }
+  private attachedThread(machineId: string, threadId: string) {
+    const supervisor = this.supervisors.get(machineId);
+    const thread = this.projections.get(machineId)?.threads.find((thread) => thread.id === threadId);
+    if (!supervisor || !thread) throw new Error('thread_not_found');
+    if (!supervisor.connected || thread.bindingState !== 'attached') throw new Error('machine_disconnected');
+    return { supervisor, thread };
+  }
+  private saveThreadMetadata(machineId: string, threadId: string, change: Partial<Thread>) {
+    const row = this.database.threadRows(machineId).find((row) => row.id === threadId);
+    if (row) this.database.saveThread({ ...row.metadata, ...change }, row.anchors, row.alias);
+  }
+  async deleteThread(machineId: string, threadId: string) {
+    const supervisor = this.supervisors.get(machineId);
+    const thread = this.projections.get(machineId)?.threads.find((thread) => thread.id === threadId);
+    if (!supervisor || !thread) throw new Error('thread_not_found');
+    if (['pending', 'running'].includes(thread.operation?.state ?? '')) throw new Error('launch_in_progress');
+    if (thread.bindingState === 'attached') {
+      if (!supervisor.connected || !supervisor.target.discardTab) throw new Error('machine_disconnected');
+      await supervisor.target.discardTab(thread.tabId, !!thread.ownsWorktree);
+      await supervisor.readFresh();
+    }
+    this.database.deleteThread(threadId);
+    this.publish(supervisor);
+  }
+  async deleteArchived() {
+    const archived = [...this.projections.values()].flatMap((projection) => projection.threads.filter((thread) => thread.archivedAt));
+    const failed: string[] = [];
+    for (const thread of archived) await this.deleteThread(thread.machineId, thread.id).catch(() => failed.push(thread.id));
+    return { deleted: archived.length - failed.length, failed };
+  }
+  private publishAll() { for (const supervisor of this.supervisors.values()) { this.publish(supervisor); supervisor.invalidate(); } }
+  private publish(supervisor: TargetSupervisor) {
+    const records = supervisor.snapshot ? reconcile(this.database, supervisor.target, supervisor.snapshot) : { threads: this.database.threadRows(supervisor.target.id).map((row) => ({ ...row.metadata, panes: [], bindingState: 'detached' as const, status: 'unknown' as const })), projects: [] };
+    const previous = this.projections.get(supervisor.target.id);
+    const projection: Projection = { machineId: supervisor.target.id, generation: supervisor.generation, revision: (previous?.revision ?? 0) + 1, freshAt: supervisor.freshAt, connected: supervisor.connected, error: supervisor.error, ...records, layouts: supervisor.snapshot?.layouts.map((layout) => ({ workspaceId: layout.workspace_id, tabId: layout.tab_id, area: layout.area, panes: layout.panes.map((pane) => ({ paneId: pane.pane_id, rect: pane.rect })) })) ?? [] };
+    projection.threads = projection.threads.map((thread) => ({ ...thread, prompt: '', ...(!projection.connected ? { panes: [], status: 'unknown' as const, bindingState: 'detached' as const } : {}) }));
+    projection.availableTabs = projection.connected ? supervisor.snapshot?.tabs.map((tab) => ({ tabId: tab.tab_id, workspaceId: tab.workspace_id, label: tab.label ?? tab.tab_id, bound: projection.threads.some((thread) => thread.bindingState === 'attached' && thread.tabId === tab.tab_id), panes: supervisor.snapshot!.panes.filter((pane) => pane.tab_id === tab.tab_id && pane.workspace_id === tab.workspace_id).map((pane) => ({ id: pane.pane_id, terminalId: pane.terminal_id, title: pane.title ?? pane.agent ?? 'Shell' })) })) ?? [] : [];
+    projection.machine = this.machine(supervisor);
+    const semantic = (value: Projection) => JSON.stringify({ ...value, revision: 0, freshAt: null });
+    if (previous && semantic(previous) === semantic(projection) && (!projection.freshAt || Date.parse(projection.freshAt) - Date.parse(previous.freshAt ?? '') < 30_000)) return;
+    this.projections.set(supervisor.target.id, projection);
+    if (!projection.connected) for (const key of this.catalogs.keys()) if (JSON.parse(key)[0] === supervisor.target.id) this.catalogs.delete(key);
+    this.emit('projection', projection);
+  }
+}

package/src/server/runtime/reconcile.ts

@@ -0,0 +1,51 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type { MetadataDatabase } from '../storage/database';
+import type { NativeSnapshot } from '../protocol/native';
+import type { Project, Thread } from '../../lib/models';
+import type { TargetAdapter } from './target';
+
+export const projectIdentity = (machineId: string, repository: string) => createHash('sha256').update(machineId + '\0' + repository).digest('hex').slice(0, 32);
+const sameBinding = (thread: Thread, target: TargetAdapter) => thread.session === target.session && thread.bindingFingerprint === target.fingerprint && thread.bindingConfigVersion === target.configVersion;
+const paneStatus = (panes: NativeSnapshot['panes']) => { const agents = panes.filter((pane) => pane.agent); return ['blocked', 'working', 'done', 'idle', 'unknown'].find((status) => (agents.length ? agents : panes).some((pane) => pane.agent_status === status)) as Thread['status'] | undefined; };
+const threadTitle = (label: string | null | undefined, panes: NativeSnapshot['panes'], fallback = 'Terminal') => {
+  const namedTab = label?.trim();
+  if (namedTab && !/^\d+$/.test(namedTab)) return namedTab;
+  const agent = panes.find((pane) => pane.agent && pane.focused) ?? panes.find((pane) => pane.agent);
+  return agent?.title?.trim() || agent?.terminal_title_stripped?.trim() || namedTab || fallback;
+};
+
+export function reconcile(database: MetadataDatabase, target: TargetAdapter, snapshot: NativeSnapshot): { threads: Thread[]; projects: Project[] } {
+  const saved = database.threadRows(target.id);
+  const projects: Project[] = [];
+  const tabProjects = new Map<string, string>();
+  for (const workspace of snapshot.workspaces) {
+    const cwd = workspace.worktree?.repo_root ?? snapshot.panes.find((pane) => pane.workspace_id === workspace.workspace_id)?.cwd ?? '';
+    const location = target.locations.find((location) => location.workspaceId === workspace.workspace_id || location.path === cwd);
+    const id = location?.projectId ?? projectIdentity(target.id, workspace.worktree?.repo_key ?? (cwd || workspace.workspace_id));
+    if (!projects.some((project) => project.id === id)) projects.push({ id, machineId: target.id, localId: location?.localId, logicalId: location?.logicalId ?? workspace.worktree?.repo_key ?? id, name: workspace.worktree?.repo_name ?? workspace.label, path: location?.path ?? cwd, color: '#9b83df', initial: (workspace.label[0] ?? 'P').toUpperCase(), iconUrl: target.icon && location ? `/api/projects/${encodeURIComponent(target.id)}/${encodeURIComponent(id)}/icon` : undefined });
+    for (const tab of snapshot.tabs.filter((tab) => tab.workspace_id === workspace.workspace_id)) tabProjects.set(tab.tab_id, id);
+  }
+  const launching = database.operations().some((operation) => operation.input.machineId === target.id && ['pending', 'running'].includes(operation.state));
+  for (const tab of snapshot.tabs) {
+    if (launching || saved.some((row) => row.alias === tab.tab_id)) continue;
+    const panes = snapshot.panes.filter((pane) => pane.tab_id === tab.tab_id && pane.workspace_id === tab.workspace_id);
+    if (!panes.length) continue;
+    const thread: Thread = { id: randomUUID(), avatarIndex: database.nextAvatarIndex(), projectId: tabProjects.get(tab.tab_id) ?? '', machineId: target.id, title: threadTitle(tab.label, panes), prompt: '', agent: '', model: '', status: 'unknown', updatedAt: new Date().toISOString(), branch: '', worktree: !!snapshot.workspaces.find((workspace) => workspace.workspace_id === tab.workspace_id)?.worktree?.is_linked_worktree, session: target.session, tabId: tab.tab_id, panes: [], bindingState: 'attached', bindingFingerprint: target.fingerprint, bindingConfigVersion: target.configVersion };
+    database.saveThread(thread, panes.map((pane) => pane.terminal_id), tab.tab_id);
+    saved.push(database.threadRows(target.id).find((row) => row.id === thread.id)!);
+  }
+  const operations = database.operations();
+  const threads = saved.map((row): Thread => {
+    const tab = snapshot.tabs.find((tab) => tab.tab_id === row.alias);
+    const members = tab ? snapshot.panes.filter((pane) => pane.tab_id === tab.tab_id && pane.workspace_id === tab.workspace_id) : [];
+    const attached = sameBinding(row.metadata, target) && members.length > 0;
+    const panes = attached ? members : [];
+    const signature = JSON.stringify([tab?.label, panes.map((pane) => [pane.terminal_id, pane.pane_id, pane.agent, pane.agent_status, pane.title, pane.terminal_title_stripped, pane.focused, snapshot.agents.find((agent) => agent.terminal_id === pane.terminal_id)?.state_change_seq])]);
+    const meaningfulChange = attached && row.metadata.semanticSignature !== signature;
+    const operation = operations.find((operation) => operation.threadId === row.id);
+    const thread: Thread = { ...row.metadata, title: attached ? threadTitle(tab?.label, panes, row.metadata.title) : row.metadata.title, projectId: attached ? tabProjects.get(tab!.tab_id) ?? row.metadata.projectId : row.metadata.projectId, bindingState: attached ? 'attached' : operation && !row.anchors.length ? 'pending' : 'detached', status: attached ? paneStatus(panes) ?? 'unknown' : 'unknown', agent: attached ? panes.find((pane) => pane.agent)?.agent ?? '' : row.metadata.agent, semanticSignature: attached ? signature : row.metadata.semanticSignature, updatedAt: meaningfulChange ? new Date().toISOString() : row.metadata.updatedAt, panes: panes.map((pane) => ({ id: pane.pane_id, terminalId: pane.terminal_id, title: pane.title ?? pane.terminal_title_stripped ?? pane.agent ?? 'Shell', kind: pane.agent ? 'agent' : 'shell' })), operation: operation ? { id: operation.id, state: operation.state, step: operation.step } : undefined };
+    if (attached && (meaningfulChange || JSON.stringify(row.anchors) !== JSON.stringify(panes.map((pane) => pane.terminal_id)))) database.saveThread({ ...thread, panes: [], operation: undefined }, panes.map((pane) => pane.terminal_id), row.alias);
+    return thread;
+  });
+  return { threads, projects };
+}