@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/server/harness-chat-service.ts

@@ -0,0 +1,796 @@
+/**
+ * VGAI host adapter for Supercode's headless client.
+ *
+ * Supercode owns harness/session/runtime semantics, lifecycle normalization,
+ * transcript projection, retries, reconciliation, and concurrency. VGAI owns
+ * the trusted YOLO policy, HTTP/SSE boundary, shell-command presentation, and
+ * React visuals. Keep this file as a mapping layer; reusable agent logic
+ * belongs in @volter-ai-dev/supercode-client.
+ */
+
+import { existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import type {
+  HarnessChatAction,
+  HarnessChatAuthState,
+  HarnessChatAvailableActions,
+  HarnessChatCapabilities,
+  HarnessChatConversationEntry,
+  HarnessChatError,
+  HarnessChatHarness,
+  HarnessChatRuntimeState,
+  HarnessChatSession,
+  HarnessChatSnapshot,
+  JsonValue,
+} from '../src/harness-chat-types';
+
+// @volter-ai-dev/supercode-client is an optional runtime peer, so this adapter keeps only
+// the structural projection it consumes. The validator loaded atomically from
+// that same peer module is the runtime authority for every production capture.
+type RuntimeCapabilities = {
+  start_session: boolean;
+  resume_session: boolean;
+  attach_existing_process: boolean;
+  send_input: boolean;
+  stream_events: boolean;
+  interrupt: boolean;
+  respond_to_requests?: boolean;
+};
+type StructuredLaunch = {
+  program: string;
+  arguments: string[];
+  cwd: string;
+  env?: Record<string, string>;
+};
+type HeadlessHarness = {
+  id: string;
+  display_name: string;
+  installed: boolean;
+  auth: HarnessChatAuthState;
+  runtime: HarnessChatRuntimeState;
+  protocol: string;
+  capabilities: RuntimeCapabilities;
+  effective_capabilities: RuntimeCapabilities;
+  availableActions: {
+    start: boolean;
+    resume: boolean;
+    attach: boolean;
+    send: boolean;
+    interrupt: boolean;
+    respond: boolean;
+  };
+  reason: string | null;
+  repair: string | null;
+};
+type HeadlessSession = {
+  key: string;
+  identity: string;
+  harness: string;
+  sessionId: string;
+  cwd: string | null;
+  title: string | null;
+  updatedAt: number | null;
+  messageCount: number | null;
+  model: string | null;
+  storage: 'file' | 'sqlite';
+  liveEndpoint: string | null;
+};
+type HeadlessConversationEntry = HarnessChatConversationEntry;
+type HeadlessSnapshot = {
+  schema: 'supercode.client-state.v1';
+  revision: number;
+  workspace: string;
+  availability: 'loading' | 'ready' | 'unavailable' | 'error';
+  operation: HarnessChatSnapshot['operation'];
+  harnesses: HeadlessHarness[];
+  sessions: HeadlessSession[];
+  activeSessionKey: string | null;
+  activeHarness: string | null;
+  activeSessionId: string | null;
+  connection: {
+    mode: 'none' | 'mirror' | 'control';
+    strategy: 'start' | 'resume' | 'attach' | 'branch' | null;
+    follow: 'inactive' | 'following' | 'retrying';
+    ownsRuntime: boolean;
+  };
+  turn: {
+    state: 'idle' | 'running' | 'interrupting' | 'reconciling';
+    id: string | null;
+    startedAt: number | null;
+  };
+  conversation: HeadlessConversationEntry[];
+  requests: Extract<HeadlessConversationEntry, { kind: 'request' }>[];
+  availableActions: HarnessChatAvailableActions;
+  error: HarnessChatError | null;
+  terminalLaunch: StructuredLaunch | null;
+};
+type HeadlessAction =
+  | { type: 'refresh'; autoObserve?: boolean }
+  | { type: 'observe'; sessionKey: string }
+  | { type: 'start'; harness: string }
+  | { type: 'resume'; sessionKey: string }
+  | { type: 'attach'; sessionKey: string; baseUrl?: string }
+  | { type: 'branch'; sessionKey: string }
+  | { type: 'restore'; identity: string; connection: 'observe' | 'attach' }
+  | { type: 'detach' }
+  | { type: 'openTerminal' }
+  | { type: 'send'; text: string; context?: Array<{ label: string; detail: string }> }
+  | { type: 'interrupt' }
+  | { type: 'respond'; requestId: JsonValue; optionId: string | null }
+  | { type: 'respond'; requestId: JsonValue; response: JsonValue };
+type HeadlessController = {
+  getSnapshot(): HeadlessSnapshot;
+  subscribe(listener: () => void): () => void;
+  initialize(): Promise<HeadlessSnapshot>;
+  dispatch(action: HeadlessAction): Promise<HeadlessSnapshot>;
+  setWorkspace(workspace: string, options?: { autoObserve?: boolean }): Promise<HeadlessSnapshot>;
+  close(): Promise<void>;
+};
+type HeadlessControllerConstructor = new (options: {
+  client: SupercodeClient;
+  workspace: string;
+  policy: 'yolo';
+  ownsClient: true;
+  autoObserve: boolean;
+}) => HeadlessController;
+type HeadlessSnapshotAssertion = (value: unknown) => HeadlessSnapshot;
+type SupercodeClient = {
+  close(): Promise<void>;
+  [key: string]: unknown;
+};
+type SupercodeClientConstructor = new (options?: {
+  command?: string;
+  cwd?: string;
+}) => SupercodeClient;
+
+export interface HarnessChatServiceOptions {
+  engineRoot: string;
+  getProjectRoot: () => string;
+  onChange: (snapshot: HarnessChatSnapshot) => void;
+  initializeTimeoutMs?: number;
+  /** Test seam. Production loads the real zero-dependency Supercode SDK. */
+  createClient?: ((workspace: string) => Promise<SupercodeClient>) | undefined;
+  /** Test seam for the framework-neutral controller. */
+  createController?:
+    | ((
+        client: SupercodeClient,
+        workspace: string,
+        options: { autoObserve: boolean },
+      ) => HeadlessController)
+    | undefined;
+}
+
+const EMPTY_CAPABILITIES: HarnessChatCapabilities = {
+  startSession: false,
+  resumeSession: false,
+  attachExistingProcess: false,
+  sendInput: false,
+  streamEvents: false,
+  interrupt: false,
+  respondToRequests: false,
+};
+
+function capabilities(value: RuntimeCapabilities | undefined): HarnessChatCapabilities {
+  if (!value) return { ...EMPTY_CAPABILITIES };
+  return {
+    startSession: value.start_session,
+    resumeSession: value.resume_session,
+    attachExistingProcess: value.attach_existing_process,
+    sendInput: value.send_input,
+    streamEvents: value.stream_events,
+    interrupt: value.interrupt,
+    respondToRequests: value.respond_to_requests ?? false,
+  };
+}
+
+function defaultSessionTitle(harness: string): string {
+  const label = harness
+    .split('-')
+    .filter(Boolean)
+    .map((part) => `${part[0]?.toUpperCase() ?? ''}${part.slice(1)}`)
+    .join(' ');
+  return `${label || 'Agent'} chat`;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`${label} timed out after ${timeoutMs}ms.`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+// A cold editor boot can be optimizing Vite dependencies while Supercode scans
+// several local harness stores. Real five-harness startup can cross ten seconds
+// without being stuck, so keep the failure bounded but leave enough cold-start
+// grace for the first inventory pass to finish.
+const DEFAULT_INITIALIZE_TIMEOUT_MS = 30_000;
+
+function moduleCandidate(explicit: string | undefined, defaultFile: string): string[] {
+  if (!explicit) return [];
+  const absolute = resolve(explicit);
+  try {
+    return [
+      existsSync(absolute) && statSync(absolute).isDirectory()
+        ? join(absolute, defaultFile)
+        : absolute,
+    ];
+  } catch {
+    return [absolute];
+  }
+}
+
+async function importOptional<T>(
+  label: string,
+  exportName: string,
+  candidates: string[],
+): Promise<T> {
+  const failures: string[] = [];
+  for (const candidate of candidates) {
+    try {
+      const specifier = candidate.startsWith('/') ? pathToFileURL(candidate).href : candidate;
+      const module = (await import(specifier)) as Record<string, unknown>;
+      const value = module[exportName];
+      if (value) return value as T;
+      failures.push(`${candidate}: missing ${exportName} export`);
+    } catch (error) {
+      failures.push(`${candidate}: ${errorMessage(error)}`);
+    }
+  }
+  throw new Error(`${label} is unavailable. Tried: ${failures.join('; ')}`);
+}
+
+async function importOptionalModule<const Names extends readonly string[]>(
+  label: string,
+  exportNames: Names,
+  candidates: string[],
+): Promise<{ [Key in Names[number]]: unknown }> {
+  const failures: string[] = [];
+  for (const candidate of candidates) {
+    try {
+      const specifier = candidate.startsWith('/') ? pathToFileURL(candidate).href : candidate;
+      const module = (await import(specifier)) as Record<string, unknown>;
+      const missing = exportNames.filter((name) => !module[name]);
+      if (missing.length === 0) return module as { [Key in Names[number]]: unknown };
+      failures.push(`${candidate}: missing ${missing.join(', ')} export`);
+    } catch (error) {
+      failures.push(`${candidate}: ${errorMessage(error)}`);
+    }
+  }
+  throw new Error(`${label} is unavailable. Tried: ${failures.join('; ')}`);
+}
+
+async function importSupercodePackages(engineRoot: string): Promise<{
+  SupercodeHarnessClient: SupercodeClientConstructor;
+  SupercodeController: HeadlessControllerConstructor;
+  assertSupercodeClientSnapshot: HeadlessSnapshotAssertion;
+}> {
+  const sibling = join(dirname(engineRoot), 'supercode', 'sdk');
+  const cwdSibling = join(dirname(resolve(process.cwd())), 'supercode', 'sdk');
+  const controllerCandidates = [
+    ...moduleCandidate(process.env['SUPERCODE_CLIENT_PATH'], 'client.mjs'),
+    '@volter-ai-dev/supercode-client',
+    join(sibling, 'client', 'client.mjs'),
+    join(cwdSibling, 'client', 'client.mjs'),
+  ];
+  const [SupercodeHarnessClient, clientModule] = await Promise.all([
+    importOptional<SupercodeClientConstructor>('Supercode harness SDK', 'SupercodeHarnessClient', [
+      ...moduleCandidate(process.env['SUPERCODE_SDK_PATH'], 'client.mjs'),
+      '@volter-ai-dev/supercode-harness-sdk',
+      join(sibling, 'typescript', 'client.mjs'),
+      join(cwdSibling, 'typescript', 'client.mjs'),
+    ]),
+    importOptionalModule(
+      'Supercode headless client',
+      ['SupercodeController', 'assertSupercodeClientSnapshot'] as const,
+      controllerCandidates,
+    ),
+  ]);
+  const SupercodeController = clientModule.SupercodeController as HeadlessControllerConstructor;
+  const assertSupercodeClientSnapshot =
+    clientModule.assertSupercodeClientSnapshot as HeadlessSnapshotAssertion;
+  return { SupercodeHarnessClient, SupercodeController, assertSupercodeClientSnapshot };
+}
+
+async function importSupercodeController(engineRoot: string): Promise<{
+  SupercodeController: HeadlessControllerConstructor;
+  assertSupercodeClientSnapshot: HeadlessSnapshotAssertion;
+}> {
+  const sibling = join(dirname(engineRoot), 'supercode', 'sdk', 'client', 'client.mjs');
+  const cwdSibling = join(
+    dirname(resolve(process.cwd())),
+    'supercode',
+    'sdk',
+    'client',
+    'client.mjs',
+  );
+  const candidates = [
+    ...moduleCandidate(process.env['SUPERCODE_CLIENT_PATH'], 'client.mjs'),
+    '@volter-ai-dev/supercode-client',
+    sibling,
+    cwdSibling,
+  ];
+  const clientModule = await importOptionalModule(
+    'Supercode headless client',
+    ['SupercodeController', 'assertSupercodeClientSnapshot'] as const,
+    candidates,
+  );
+  const SupercodeController = clientModule.SupercodeController as HeadlessControllerConstructor;
+  const assertSupercodeClientSnapshot =
+    clientModule.assertSupercodeClientSnapshot as HeadlessSnapshotAssertion;
+  return { SupercodeController, assertSupercodeClientSnapshot };
+}
+
+export function findSupercodeCommand(engineRoot: string): string | undefined {
+  if (process.env['SUPERCODE_BIN']) return process.env['SUPERCODE_BIN'];
+  try {
+    const require = createRequire(import.meta.url);
+    const packageRoot = dirname(require.resolve('@volter-ai-dev/supercode/package.json'));
+    const installedCommand = join(packageRoot, 'bin', 'supercode.js');
+    if (existsSync(installedCommand) && statSync(installedCommand).isFile())
+      return installedCommand;
+  } catch {
+    // Optional dependency omitted: retain source-checkout fallbacks below.
+  }
+  for (const candidate of [
+    join(dirname(engineRoot), 'supercode', 'target', 'release', 'supercode'),
+    join(dirname(engineRoot), 'supercode', 'target', 'debug', 'supercode'),
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+function shellQuote(value: string): string {
+  if (/^[a-zA-Z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function launchCommand(launch: StructuredLaunch): string {
+  return `cd ${shellQuote(launch.cwd)} && ${[launch.program, ...launch.arguments].map(shellQuote).join(' ')}`;
+}
+
+function visibleEntry(entry: HeadlessConversationEntry): HarnessChatConversationEntry | null {
+  if (entry.kind === 'message') {
+    // Supercode preserves context; VGAI chooses not to render harness
+    // envelopes as chat messages. This is a presentation policy, not loss.
+    return entry.visibility === 'context'
+      ? null
+      : {
+          id: entry.id,
+          kind: 'message',
+          role: entry.role,
+          text: entry.text,
+          ...(entry.content === undefined ? {} : { content: entry.content }),
+          metadata: { ...entry.metadata },
+          visibility: entry.visibility,
+        };
+  }
+  if (entry.kind === 'tool') {
+    return {
+      id: entry.id,
+      kind: 'tool',
+      callId: entry.callId,
+      name: entry.name,
+      arguments: entry.arguments,
+      resultText: entry.resultText,
+      ...(entry.resultContent === undefined ? {} : { resultContent: entry.resultContent }),
+      status: entry.status,
+      metadata: { ...entry.metadata },
+    };
+  }
+  if (entry.kind === 'reasoning') return { ...entry };
+  if (entry.kind === 'request') {
+    return { ...entry, options: entry.options.map((option) => ({ ...option })) };
+  }
+  return { ...entry };
+}
+
+function conversation(entries: HeadlessConversationEntry[]): HarnessChatConversationEntry[] {
+  return entries.map(visibleEntry).filter((entry) => entry !== null);
+}
+
+function toSnapshot(snapshot: HeadlessSnapshot, workspaceGeneration: number): HarnessChatSnapshot {
+  const harnesses: HarnessChatHarness[] = snapshot.harnesses.map((item) => ({
+    id: item.id,
+    label: item.display_name,
+    installed: item.installed,
+    auth: item.auth,
+    runtime: item.runtime,
+    protocol: item.protocol,
+    capabilities: capabilities(item.effective_capabilities),
+    availableActions: { ...item.availableActions },
+    reason: item.reason,
+    repair: item.repair,
+  }));
+  const sessions: HarnessChatSession[] = snapshot.sessions.map((item) => ({
+    // The controller key is intentionally opaque and collision-free. Native
+    // IDs can collide between harnesses and stores.
+    id: item.key,
+    identity: item.identity,
+    nativeId: item.sessionId,
+    harness: item.harness,
+    title: item.title ?? defaultSessionTitle(item.harness),
+    cwd: item.cwd,
+    updatedAt: item.updatedAt,
+    messageCount: item.messageCount,
+    model: item.model,
+    storage: item.storage,
+    attachable: Boolean(item.liveEndpoint),
+  }));
+  const working = snapshot.turn.state !== 'idle';
+  return {
+    workspace: snapshot.workspace,
+    status:
+      snapshot.availability === 'unavailable'
+        ? 'unavailable'
+        : snapshot.availability === 'error'
+          ? 'error'
+          : snapshot.availability === 'loading'
+            ? 'loading'
+            : working
+              ? 'working'
+              : 'ready',
+    mode:
+      snapshot.connection.mode === 'mirror'
+        ? 'observe'
+        : snapshot.connection.mode === 'control'
+          ? 'control'
+          : 'none',
+    schema: 'vgai.harness-chat.v3',
+    revision: snapshot.revision,
+    workspaceGeneration,
+    operation: snapshot.operation,
+    harnesses,
+    sessions,
+    activeHarness: snapshot.activeHarness,
+    activeSessionId: snapshot.activeSessionKey,
+    connection: {
+      strategy: snapshot.connection.strategy,
+      follow: snapshot.connection.follow,
+      ownsRuntime: snapshot.connection.ownsRuntime,
+    },
+    turn: { ...snapshot.turn },
+    conversation: conversation(snapshot.conversation),
+    requests: snapshot.requests.map((request) => ({
+      ...request,
+      options: request.options.map((option) => ({ ...option })),
+    })),
+    availableActions: { ...snapshot.availableActions },
+    error: snapshot.error ? { ...snapshot.error } : null,
+    terminalCommand: snapshot.terminalLaunch ? launchCommand(snapshot.terminalLaunch) : null,
+  };
+}
+
+function unavailable(
+  workspace: string | null,
+  error: string,
+  workspaceGeneration = 0,
+): HarnessChatSnapshot {
+  return {
+    schema: 'vgai.harness-chat.v3',
+    revision: 0,
+    workspaceGeneration,
+    workspace,
+    status: 'unavailable',
+    mode: 'none',
+    operation: null,
+    harnesses: [],
+    sessions: [],
+    activeHarness: null,
+    activeSessionId: null,
+    connection: { strategy: null, follow: 'inactive', ownsRuntime: false },
+    turn: { state: 'idle', id: null, startedAt: null },
+    conversation: [],
+    requests: [],
+    availableActions: {
+      refresh: false,
+      observe: false,
+      start: false,
+      resume: false,
+      attach: false,
+      branch: false,
+      detach: false,
+      openTerminal: false,
+      send: false,
+      interrupt: false,
+      respond: false,
+    },
+    error: { code: 'unavailable', message: error, operation: 'load', recoverable: true },
+    terminalCommand: null,
+  };
+}
+
+function loading(workspace: string, workspaceGeneration: number): HarnessChatSnapshot {
+  return {
+    ...unavailable(workspace, 'Supercode is loading.', workspaceGeneration),
+    status: 'loading',
+    error: null,
+  };
+}
+
+export class HarnessChatService {
+  private workspace: string | null = null;
+  private controller: HeadlessController | null = null;
+  private unsubscribe: (() => void) | null = null;
+  private starting: Promise<void> | null = null;
+  private closing: Promise<void> | null = null;
+  private workspaceGeneration = 0;
+  private closed = false;
+  private assertSnapshot: HeadlessSnapshotAssertion = (value) => value as HeadlessSnapshot;
+  private lastSnapshot: HarnessChatSnapshot = unavailable(null, 'Supercode is loading.');
+
+  constructor(private readonly options: HarnessChatServiceOptions) {}
+
+  snapshot(): HarnessChatSnapshot {
+    return {
+      ...this.lastSnapshot,
+      harnesses: this.lastSnapshot.harnesses.map((item) => ({
+        ...item,
+        capabilities: { ...item.capabilities },
+        availableActions: { ...item.availableActions },
+      })),
+      sessions: this.lastSnapshot.sessions.map((item) => ({ ...item })),
+      connection: { ...this.lastSnapshot.connection },
+      turn: { ...this.lastSnapshot.turn },
+      conversation: this.lastSnapshot.conversation.map((item) =>
+        item.kind === 'request'
+          ? { ...item, options: item.options.map((option) => ({ ...option })) }
+          : { ...item },
+      ),
+      requests: this.lastSnapshot.requests.map((item) => ({
+        ...item,
+        options: item.options.map((option) => ({ ...option })),
+      })),
+      availableActions: { ...this.lastSnapshot.availableActions },
+      error: this.lastSnapshot.error ? { ...this.lastSnapshot.error } : null,
+    };
+  }
+
+  async refresh(autoObserve = true): Promise<HarnessChatSnapshot> {
+    const created = !this.controller;
+    await this.ensureController(autoObserve);
+    if (!this.controller) return this.snapshot();
+    if (!created) await this.controller.dispatch({ type: 'refresh', autoObserve });
+    this.capture();
+    return this.snapshot();
+  }
+
+  /** Ensure the live controller exists without re-running full harness/session
+   * discovery when an editor tab mounts or reloads. The controller already
+   * follows external transcript changes; discovery is reserved for the
+   * explicit Refresh action. */
+  async load(autoObserve = true): Promise<HarnessChatSnapshot> {
+    const next = resolve(this.options.getProjectRoot());
+    if (!this.controller && !this.starting) {
+      this.beginWorkspace(next);
+      void this.ensureController(autoObserve);
+    } else if (this.controller && this.workspace === next) {
+      this.capture();
+    } else if (this.workspace !== next) {
+      this.beginWorkspace(next);
+      void this.ensureController(autoObserve);
+    }
+    return this.snapshot();
+  }
+
+  async act(action: HarnessChatAction): Promise<HarnessChatSnapshot> {
+    await this.ensureController();
+    const controller = this.controller;
+    if (!controller) {
+      throw new Error(this.lastSnapshot.error?.message ?? 'Supercode is unavailable.');
+    }
+    switch (action.type) {
+      case 'refresh':
+        await controller.dispatch({ type: 'refresh', autoObserve: true });
+        break;
+      case 'create':
+        await controller.dispatch({ type: 'start', harness: action.harness });
+        break;
+      case 'observe':
+        await controller.dispatch({ type: 'observe', sessionKey: action.sessionId });
+        break;
+      case 'resume':
+        await controller.dispatch({ type: 'resume', sessionKey: action.sessionId });
+        break;
+      case 'attach':
+        await controller.dispatch({ type: 'attach', sessionKey: action.sessionId });
+        break;
+      case 'branch':
+        await controller.dispatch({ type: 'branch', sessionKey: action.sessionId });
+        break;
+      case 'restore':
+        await controller.dispatch({
+          type: 'restore',
+          identity: action.sessionIdentity,
+          connection: action.connection,
+        });
+        break;
+      case 'detach':
+        await controller.dispatch({ type: 'detach' });
+        break;
+      case 'openTerminal':
+        await controller.dispatch({ type: 'openTerminal' });
+        break;
+      case 'prompt':
+        await controller.dispatch({
+          type: 'send',
+          text: action.text,
+          ...(action.context
+            ? { context: action.context.map(({ label, detail }) => ({ label, detail })) }
+            : {}),
+        });
+        break;
+      case 'interrupt':
+        await controller.dispatch({ type: 'interrupt' });
+        break;
+      case 'respond':
+        await controller.dispatch(
+          'optionId' in action
+            ? { type: 'respond', requestId: action.requestId, optionId: action.optionId }
+            : { type: 'respond', requestId: action.requestId, response: action.response },
+        );
+        break;
+      default:
+        throw new Error('Unknown harness Chat action.');
+    }
+    this.capture();
+    return this.snapshot();
+  }
+
+  async setWorkspace(): Promise<void> {
+    const next = resolve(this.options.getProjectRoot());
+    if (this.workspace === next) return;
+    this.beginWorkspace(next);
+    if (this.controller) {
+      await this.controller.setWorkspace(next, { autoObserve: true });
+      this.capture();
+      return;
+    }
+    await this.ensureController(true);
+  }
+
+  async close(): Promise<void> {
+    if (this.closing) return this.closing;
+    this.closed = true;
+    this.unsubscribe?.();
+    this.unsubscribe = null;
+    const controller = this.controller;
+    this.controller = null;
+    this.closing = controller
+      ? withTimeout(controller.close(), 2_500, 'Supercode shutdown').then(
+          () => undefined,
+          () => undefined,
+        )
+      : Promise.resolve();
+    return this.closing;
+  }
+
+  private async ensureController(autoObserve = true): Promise<void> {
+    if (this.closed) throw new Error('Harness Chat service is closed.');
+    const next = resolve(this.options.getProjectRoot());
+    if (this.controller) {
+      if (this.workspace !== next) {
+        this.beginWorkspace(next);
+        await this.controller.setWorkspace(next, { autoObserve: true });
+        this.capture();
+      }
+      return;
+    }
+    if (this.starting) {
+      await this.starting;
+      return;
+    }
+    this.beginWorkspace(next);
+    const generation = this.workspaceGeneration;
+    this.starting = this.startController(next, autoObserve, generation);
+    try {
+      await this.starting;
+    } finally {
+      this.starting = null;
+    }
+  }
+
+  private async startController(
+    workspace: string,
+    autoObserve: boolean,
+    generation: number,
+  ): Promise<void> {
+    let controller: HeadlessController | null = null;
+    try {
+      controller = await this.createHeadlessController(workspace, autoObserve);
+      if (this.closed || generation !== this.workspaceGeneration) {
+        await withTimeout(controller.close(), 2_500, 'Supercode shutdown').catch(() => undefined);
+        return;
+      }
+      this.workspace = workspace;
+      this.controller = controller;
+      this.unsubscribe = controller.subscribe(() => this.capture());
+      this.capture();
+      const timeoutMs = this.options.initializeTimeoutMs ?? DEFAULT_INITIALIZE_TIMEOUT_MS;
+      await withTimeout(controller.initialize(), timeoutMs, 'Supercode initialization');
+      this.capture();
+    } catch (error) {
+      if (controller && controller === this.controller) {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.controller = null;
+      }
+      if (generation === this.workspaceGeneration && !this.closed) {
+        this.lastSnapshot = unavailable(workspace, errorMessage(error), generation);
+        this.options.onChange(this.snapshot());
+      }
+      if (controller) {
+        await withTimeout(controller.close(), 2_500, 'Supercode shutdown').catch(() => undefined);
+      }
+    }
+  }
+
+  private async createHeadlessController(
+    workspace: string,
+    autoObserve: boolean,
+  ): Promise<HeadlessController> {
+    if (this.options.createClient) {
+      const client = await this.options.createClient(workspace);
+      if (this.options.createController) {
+        return this.options.createController(client, workspace, { autoObserve });
+      }
+      const { SupercodeController, assertSupercodeClientSnapshot } =
+        await importSupercodeController(this.options.engineRoot);
+      this.assertSnapshot = assertSupercodeClientSnapshot;
+      return new SupercodeController({
+        client,
+        workspace,
+        policy: 'yolo',
+        ownsClient: true,
+        autoObserve,
+      });
+    }
+    const { SupercodeHarnessClient, SupercodeController, assertSupercodeClientSnapshot } =
+      await importSupercodePackages(this.options.engineRoot);
+    this.assertSnapshot = assertSupercodeClientSnapshot;
+    const command = findSupercodeCommand(this.options.engineRoot);
+    const client = new SupercodeHarnessClient({
+      cwd: workspace,
+      ...(command ? { command } : {}),
+    });
+    return new SupercodeController({
+      client,
+      workspace,
+      policy: 'yolo',
+      ownsClient: true,
+      autoObserve,
+    });
+  }
+
+  private capture(): void {
+    if (!this.controller) return;
+    const snapshot = this.assertSnapshot(this.controller.getSnapshot());
+    if (snapshot.workspace !== this.workspace) return;
+    this.lastSnapshot = toSnapshot(snapshot, this.workspaceGeneration);
+    this.options.onChange(this.snapshot());
+  }
+
+  private beginWorkspace(workspace: string): void {
+    if (this.workspace === workspace) return;
+    this.workspace = workspace;
+    this.workspaceGeneration++;
+    this.lastSnapshot = loading(workspace, this.workspaceGeneration);
+    this.options.onChange(this.snapshot());
+  }
+}