@tonyclaw/agent-inspector 4.0.1 → 4.0.2

package/src/cli/instance.ts

@@ -1,1071 +0,0 @@
-import { spawn, type ChildProcess } from "node:child_process";
-import { resolve as resolvePath } from "node:path";
-import packageJson from "../../package.json";
-import {
-  AGENT_INSPECTOR_BASE_PATH_ENV,
-  appendBasePathToOrigin,
-  getConfiguredBasePath,
-  normalizePublicBasePath,
-} from "../lib/basePath";
-import type { BackendImplementation } from "../lib/backendImplementation";
-import {
-  type InstanceConnectionOutput,
-  type InstanceOperationOutcome,
-  type InstanceOperationOutput,
-  type InstanceStartRequest,
-  type InstanceStatusOutput,
-  INSTANCE_API_SCHEMA_VERSION,
-  isRetryableInstanceError,
-} from "../lib/instanceContract";
-import { AGENT_INSPECTOR_CLI_ENTRY_ENV, MANAGED_INSTANCE_ENV } from "../lib/managedInstance";
-import { resolveDataDir } from "../proxy/dataDir";
-import { openUrlCommand } from "../proxy/platformCommands";
-import { type InstanceAction, instanceHelp, parseInstanceArgs } from "./instanceArgs";
-import {
-  type ExpectedInstanceControlIdentity,
-  type InstanceControlFetch,
-  probeInstanceControl,
-  requestInstanceShutdown,
-} from "./instanceControl";
-import {
-  acquireInstanceLock,
-  acquireRegistryLock,
-  canonicalizeDataDirectory,
-  createInstanceRecord,
-  getInstancePaths,
-  getInstancesRoot,
-  instanceRegistrySuccess,
-  isPortAvailableByBinding,
-  listInstanceRecords,
-  planInstancePorts,
-  readInstanceRecord,
-  rotateInstanceLaunch,
-  type InstanceLockHandle,
-  type InstancePortPair,
-  type InstanceRecord,
-  type InstanceRegistryErrorCode,
-  type InstanceRegistryResult,
-  validateDataDirectoryAssignment,
-  validateInstanceName,
-  writeInstanceRecord,
-  InstanceRecordSchema,
-  type PortAvailabilityCheck,
-} from "./instanceRegistry";
-import { probeHostForBindHost, urlForHost } from "./networkHints";
-import { resolvePreferredBackendImplementation } from "./rustBackendPackage";
-
-const DEFAULT_INSTANCE_HOST = "127.0.0.1";
-const DEFAULT_INSTANCE_CAPTURE_MODE = "simple";
-const INSTANCE_READY_TIMEOUT_MS = 15_000;
-const INSTANCE_STOP_TIMEOUT_MS = 20_000;
-const INSTANCE_POLL_INTERVAL_MS = 200;
-
-export type InstanceLifecycleErrorCode =
-  | InstanceRegistryErrorCode
-  | "argument_invalid"
-  | "config_mismatch"
-  | "identity_mismatch"
-  | "instance_not_found"
-  | "launch_failed"
-  | "launch_unavailable"
-  | "restart_failed_degraded"
-  | "restart_failed_rolled_back"
-  | "self_lifecycle_unsupported"
-  | "shutdown_failed";
-
-export type InstanceLifecycleError = {
-  code: InstanceLifecycleErrorCode;
-  message: string;
-  retryable: boolean;
-};
-
-export type InstanceLifecycleResult<T> =
-  | { kind: "success"; value: T }
-  | { kind: "error"; error: InstanceLifecycleError };
-
-type InstanceLiveState =
-  | { state: "running"; supervisorPid: number }
-  | { state: "stopped"; supervisorPid: null }
-  | {
-      state: "conflict";
-      supervisorPid: null;
-      code: "identity_mismatch" | "port_conflict";
-    };
-
-export type InstanceIo = {
-  stdout: (text: string) => void;
-  stderr: (text: string) => void;
-};
-
-export type InstanceLifecycleDependencies = {
-  root?: string;
-  cliEntry?: string;
-  fetchImpl?: InstanceControlFetch;
-  isPortAvailable?: PortAvailabilityCheck;
-  launch?: (record: InstanceRecord, open: boolean) => Promise<boolean>;
-  openUrl?: (url: string) => void;
-  resolveDefaultBackend?: () => BackendImplementation;
-  sleep?: (milliseconds: number) => Promise<void>;
-  readyTimeoutMs?: number;
-  stopTimeoutMs?: number;
-};
-
-const processIo: InstanceIo = {
-  stdout: (text) => process.stdout.write(text),
-  stderr: (text) => process.stderr.write(text),
-};
-
-function success<T>(value: T): InstanceLifecycleResult<T> {
-  return { kind: "success", value };
-}
-
-function failure<T>(code: InstanceLifecycleErrorCode, message: string): InstanceLifecycleResult<T> {
-  return {
-    kind: "error",
-    error: { code, message, retryable: isRetryableInstanceError(code) },
-  };
-}
-
-function fromRegistry<T>(result: InstanceRegistryResult<T>): InstanceLifecycleResult<T> {
-  return result.kind === "success"
-    ? success(result.value)
-    : failure(result.error.code, result.error.message);
-}
-
-function sleep(milliseconds: number): Promise<void> {
-  return new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds));
-}
-
-function displayBasePath(basePath: string): string {
-  return basePath.length === 0 ? "/" : basePath;
-}
-
-function recordUrls(record: InstanceRecord): InstanceStatusOutput["urls"] {
-  const origin = urlForHost(record.publicPort, record.host);
-  return {
-    ui: appendBasePathToOrigin(origin, "/", record.basePath),
-    api: appendBasePathToOrigin(origin, "/api", record.basePath),
-    health: appendBasePathToOrigin(origin, "/api/health", record.basePath),
-    proxy: appendBasePathToOrigin(origin, "/proxy", record.basePath),
-    openai: appendBasePathToOrigin(origin, "/proxy/v1", record.basePath),
-    mcp: appendBasePathToOrigin(origin, "/api/mcp", record.basePath),
-  };
-}
-
-function statusOutput(
-  record: InstanceRecord,
-  live: InstanceLiveState,
-  checkedAt = new Date(),
-): InstanceStatusOutput {
-  return {
-    schemaVersion: INSTANCE_API_SCHEMA_VERSION,
-    name: record.name,
-    instanceId: record.instanceId,
-    state: live.state,
-    stateReason: live.state === "conflict" ? live.code : null,
-    checkedAt: checkedAt.toISOString(),
-    createdAt: record.createdAt,
-    updatedAt: record.updatedAt,
-    launch: {
-      launchId: record.launch.launchId,
-      startedAt: record.launch.startedAt,
-    },
-    host: record.host,
-    publicPort: record.publicPort,
-    upstreamPort: record.upstreamPort,
-    basePath: displayBasePath(record.basePath),
-    captureMode: record.captureMode,
-    backend: record.backend,
-    uiEnabled: record.uiEnabled,
-    dataDir: record.dataDir,
-    supervisorPid: live.supervisorPid,
-    urls: recordUrls(record),
-  };
-}
-
-function operationOutput(
-  operation: InstanceOperationOutput["operation"],
-  outcome: InstanceOperationOutcome,
-  instance: InstanceStatusOutput,
-): InstanceOperationOutput {
-  return {
-    schemaVersion: INSTANCE_API_SCHEMA_VERSION,
-    operation,
-    outcome,
-    instance,
-  };
-}
-
-function connectionOutput(instance: InstanceStatusOutput): InstanceConnectionOutput {
-  const serverName = `agent-inspector-${instance.name}`;
-  return {
-    schemaVersion: INSTANCE_API_SCHEMA_VERSION,
-    uiEnabled: instance.uiEnabled,
-    instance,
-    surfaces: {
-      ui: {
-        enabled: instance.uiEnabled,
-        baseUrl: instance.uiEnabled ? instance.urls.ui : null,
-      },
-      control: { baseUrl: instance.urls.ui },
-      agent: { baseUrl: instance.urls.ui },
-    },
-    baseUrl: instance.urls.ui,
-    endpoints: instance.urls,
-    environment: {
-      ANTHROPIC_BASE_URL: instance.urls.proxy,
-      LLM_BASE_URL: instance.urls.proxy,
-      OPENAI_BASE_URL: instance.urls.openai,
-      AGENT_INSPECTOR_MCP_URL: instance.urls.mcp,
-    },
-    mcp: {
-      serverName,
-      transport: "streamable-http",
-      url: instance.urls.mcp,
-    },
-    codex: {
-      providerName: serverName,
-      baseUrl: instance.urls.openai,
-      wireApi: "responses",
-    },
-  };
-}
-
-function expectedIdentity(record: InstanceRecord): ExpectedInstanceControlIdentity {
-  return {
-    backend: record.backend,
-    instanceId: record.instanceId,
-    launchId: record.launch.launchId,
-    controlToken: record.launch.controlToken,
-    host: probeHostForBindHost(record.host),
-    publicPort: record.publicPort,
-  };
-}
-
-async function classifyRecord(
-  record: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLiveState> {
-  const probe = await probeInstanceControl(expectedIdentity(record), deps.fetchImpl);
-  if (probe.kind === "running") {
-    return { state: "running", supervisorPid: probe.identity.supervisorPid };
-  }
-  if (probe.kind === "identity-mismatch" || probe.kind === "invalid-response") {
-    return { state: "conflict", supervisorPid: null, code: "identity_mismatch" };
-  }
-
-  const check = deps.isPortAvailable ?? isPortAvailableByBinding;
-  const publicAvailable = await check(record.publicPort, record.host);
-  const upstreamAvailable = await check(record.upstreamPort, DEFAULT_INSTANCE_HOST);
-  return publicAvailable && upstreamAvailable
-    ? { state: "stopped", supervisorPid: null }
-    : { state: "conflict", supervisorPid: null, code: "port_conflict" };
-}
-
-function waitForProcess(child: ChildProcess): Promise<number> {
-  return new Promise((resolveExit) => {
-    let settled = false;
-    const finish = (code: number): void => {
-      if (settled) return;
-      settled = true;
-      resolveExit(code);
-    };
-    child.once("exit", (code) => finish(code ?? 1));
-    child.once("error", () => finish(1));
-  });
-}
-
-function defaultOpenUrl(targetUrl: string): void {
-  const command = openUrlCommand(targetUrl);
-  if (command === null) return;
-  const child = spawn(command.command, command.args, {
-    stdio: "ignore",
-    detached: true,
-    windowsHide: true,
-  });
-  child.once("error", () => undefined);
-  child.unref();
-}
-
-export function buildInstanceLaunchArgs(record: InstanceRecord, open: boolean): string[] {
-  const args = [
-    "--background",
-    "--no-open",
-    "--backend",
-    record.backend,
-    "--port",
-    String(record.publicPort),
-    "--host",
-    record.host,
-    "--mode",
-    record.captureMode,
-  ];
-  if (!record.uiEnabled) args.push("--backend-only");
-  if (open && record.uiEnabled) args.push("--open");
-  return args;
-}
-
-async function defaultLaunch(
-  record: InstanceRecord,
-  open: boolean,
-  cliEntry: string,
-): Promise<boolean> {
-  const child = spawn(process.execPath, [cliEntry, ...buildInstanceLaunchArgs(record, open)], {
-    stdio: "ignore",
-    windowsHide: true,
-    env: {
-      ...process.env,
-      [AGENT_INSPECTOR_CLI_ENTRY_ENV]: cliEntry,
-      AGENT_INSPECTOR_DATA_DIR: record.dataDir,
-      [AGENT_INSPECTOR_BASE_PATH_ENV]: displayBasePath(record.basePath),
-      [MANAGED_INSTANCE_ENV.backend]: record.backend,
-      [MANAGED_INSTANCE_ENV.name]: record.name,
-      [MANAGED_INSTANCE_ENV.instanceId]: record.instanceId,
-      [MANAGED_INSTANCE_ENV.launchId]: record.launch.launchId,
-      [MANAGED_INSTANCE_ENV.controlToken]: record.launch.controlToken,
-      [MANAGED_INSTANCE_ENV.startedAt]: record.launch.startedAt,
-      [MANAGED_INSTANCE_ENV.upstreamPort]: String(record.upstreamPort),
-    },
-  });
-  return (await waitForProcess(child)) === 0;
-}
-
-async function launchRecord(
-  record: InstanceRecord,
-  open: boolean,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceLiveState>> {
-  const cliEntry = deps.cliEntry ?? process.env[AGENT_INSPECTOR_CLI_ENTRY_ENV] ?? process.argv[1];
-  if (deps.launch === undefined && (cliEntry === undefined || cliEntry.length === 0)) {
-    return failure("launch_unavailable", "Cannot resolve the packaged Agent Inspector CLI entry.");
-  }
-  const launched =
-    deps.launch === undefined
-      ? await defaultLaunch(record, open, cliEntry ?? "")
-      : await deps.launch(record, open);
-  if (!launched) {
-    return failure(
-      "launch_failed",
-      `Instance ${record.name} did not become ready; its saved configuration is retained for retry.`,
-    );
-  }
-
-  const wait = deps.sleep ?? sleep;
-  const deadline = Date.now() + (deps.readyTimeoutMs ?? INSTANCE_READY_TIMEOUT_MS);
-  while (Date.now() <= deadline) {
-    const live = await classifyRecord(record, deps);
-    if (live.state === "running") return success(live);
-    if (live.state === "conflict") {
-      return failure(
-        live.code,
-        `Instance ${record.name} launch identity does not own its saved port pair; no process was terminated.`,
-      );
-    }
-    await wait(INSTANCE_POLL_INTERVAL_MS);
-  }
-  return failure(
-    "launch_failed",
-    `Instance ${record.name} launch timed out; its saved configuration is retained for retry.`,
-  );
-}
-
-async function waitForPortsToClose(
-  record: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<boolean> {
-  const check = deps.isPortAvailable ?? isPortAvailableByBinding;
-  const wait = deps.sleep ?? sleep;
-  const deadline = Date.now() + (deps.stopTimeoutMs ?? INSTANCE_STOP_TIMEOUT_MS);
-  while (Date.now() <= deadline) {
-    const publicAvailable = await check(record.publicPort, record.host);
-    const upstreamAvailable = await check(record.upstreamPort, DEFAULT_INSTANCE_HOST);
-    if (publicAvailable && upstreamAvailable) return true;
-    await wait(INSTANCE_POLL_INTERVAL_MS);
-  }
-  return false;
-}
-
-type StoppedRecord = {
-  live: Extract<InstanceLiveState, { state: "stopped" }>;
-  outcome: "stopped" | "already_stopped";
-};
-
-async function stopRecord(
-  record: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<StoppedRecord>> {
-  const live = await classifyRecord(record, deps);
-  if (live.state === "stopped") return success({ live, outcome: "already_stopped" });
-  if (live.state === "conflict") {
-    return failure(
-      live.code,
-      `Instance ${record.name} does not own its saved port pair; refusing to stop another process.`,
-    );
-  }
-  const requested = await requestInstanceShutdown(expectedIdentity(record), deps.fetchImpl);
-  if (requested.kind === "identity-mismatch") {
-    return failure(
-      "identity_mismatch",
-      `Instance ${record.name} changed identity before shutdown; no process was terminated.`,
-    );
-  }
-  if (requested.kind !== "accepted") {
-    return failure("shutdown_failed", `Instance ${record.name} rejected the shutdown request.`);
-  }
-  return (await waitForPortsToClose(record, deps))
-    ? success({
-        live: { state: "stopped", supervisorPid: null },
-        outcome: "stopped",
-      })
-    : failure(
-        "shutdown_failed",
-        `Instance ${record.name} did not stop before the shutdown deadline.`,
-      );
-}
-
-type AcquiredLocks = {
-  registry: InstanceLockHandle | null;
-  instance: InstanceLockHandle;
-};
-
-async function acquireLocks(
-  root: string,
-  name: string,
-  includeRegistry: boolean,
-): Promise<InstanceLifecycleResult<AcquiredLocks>> {
-  const registryResult = includeRegistry ? await acquireRegistryLock(root) : null;
-  if (registryResult !== null && registryResult.kind === "error") {
-    return fromRegistry(registryResult);
-  }
-  const registry = registryResult?.kind === "success" ? registryResult.value : null;
-  const instanceResult = await acquireInstanceLock(root, name);
-  if (instanceResult.kind === "error") {
-    registry?.release();
-    return fromRegistry(instanceResult);
-  }
-  return success({ registry, instance: instanceResult.value });
-}
-
-function releaseLocks(locks: AcquiredLocks): InstanceLifecycleResult<void> {
-  const instanceReleased = locks.instance.release();
-  const registryReleased = locks.registry?.release() ?? instanceRegistrySuccess(undefined);
-  if (instanceReleased.kind === "error") return fromRegistry(instanceReleased);
-  return fromRegistry(registryReleased);
-}
-
-async function withLocks<T>(
-  root: string,
-  name: string,
-  includeRegistry: boolean,
-  operation: () => Promise<InstanceLifecycleResult<T>>,
-): Promise<InstanceLifecycleResult<T>> {
-  const locks = await acquireLocks(root, name, includeRegistry);
-  if (locks.kind === "error") return locks;
-  let result: InstanceLifecycleResult<T>;
-  try {
-    result = await operation();
-  } catch {
-    result = failure("registry_io", "The named-instance lifecycle operation failed.");
-  }
-  const released = releaseLocks(locks.value);
-  return result.kind === "success" && released.kind === "error" ? released : result;
-}
-
-function readRequiredRecord(root: string, name: string): InstanceLifecycleResult<InstanceRecord> {
-  const read = readInstanceRecord(root, name);
-  if (read.kind === "error") return fromRegistry(read);
-  return read.value === null
-    ? failure("instance_not_found", `Named instance ${name} does not exist.`)
-    : success(read.value);
-}
-
-function overridesDiffer(
-  record: InstanceRecord,
-  action: Extract<InstanceAction, { kind: "start" | "restart" }>,
-): boolean {
-  const { overrides } = action;
-  if (overrides.backend !== null && overrides.backend !== record.backend) return true;
-  if (overrides.port !== null && overrides.port !== record.publicPort) return true;
-  if (overrides.basePath !== null && overrides.basePath !== record.basePath) return true;
-  if (overrides.host !== null && overrides.host !== record.host) return true;
-  if (overrides.captureMode !== null && overrides.captureMode !== record.captureMode) return true;
-  if (overrides.uiEnabled !== null && overrides.uiEnabled !== record.uiEnabled) return true;
-  if (overrides.dataDir !== null) {
-    const requested = canonicalizeDataDirectory(overrides.dataDir);
-    const saved = canonicalizeDataDirectory(record.dataDir);
-    if (
-      requested.kind === "error" ||
-      saved.kind === "error" ||
-      requested.value.comparisonKey !== saved.value.comparisonKey
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
-
-function updatedRecord(
-  record: InstanceRecord,
-  action: Extract<InstanceAction, { kind: "restart" }>,
-  pair: InstancePortPair,
-  dataDir: string,
-): InstanceLifecycleResult<InstanceRecord> {
-  const candidate: unknown = {
-    ...record,
-    host: action.overrides.host ?? record.host,
-    publicPort: pair.publicPort,
-    upstreamPort: pair.upstreamPort,
-    basePath: action.overrides.basePath ?? record.basePath,
-    captureMode: action.overrides.captureMode ?? record.captureMode,
-    backend: action.overrides.backend ?? record.backend,
-    uiEnabled: action.overrides.uiEnabled ?? record.uiEnabled,
-    dataDir,
-  };
-  const parsed = InstanceRecordSchema.safeParse(candidate);
-  if (!parsed.success) {
-    return failure(
-      "record_invalid",
-      `Cannot update instance ${record.name}: ${parsed.error.issues[0]?.message ?? "invalid configuration"}.`,
-    );
-  }
-  return fromRegistry(rotateInstanceLaunch(parsed.data));
-}
-
-function saveRecord(root: string, record: InstanceRecord): InstanceLifecycleResult<InstanceRecord> {
-  return fromRegistry(writeInstanceRecord(root, record));
-}
-
-function validateInstanceDataDirectory(
-  rawPath: string,
-  records: readonly InstanceRecord[],
-  excludeName?: string,
-): InstanceLifecycleResult<string> {
-  const assigned = validateDataDirectoryAssignment(rawPath, records, excludeName);
-  if (assigned.kind === "error") return fromRegistry(assigned);
-  const defaultDirectory = canonicalizeDataDirectory(resolveDataDir(() => false));
-  if (defaultDirectory.kind === "error") return fromRegistry(defaultDirectory);
-  if (assigned.value.comparisonKey === defaultDirectory.value.comparisonKey) {
-    return failure(
-      "data_dir_conflict",
-      `Data directory ${assigned.value.path} belongs to the unmanaged default instance; named instances cannot share it.`,
-    );
-  }
-  return success(assigned.value.path);
-}
-
-function resolveDefaultInstanceBackend(deps: InstanceLifecycleDependencies): BackendImplementation {
-  return (
-    deps.resolveDefaultBackend?.() ??
-    resolvePreferredBackendImplementation({ rootVersion: packageJson.version })
-  );
-}
-
-async function createNewRecord(
-  root: string,
-  action: Extract<InstanceAction, { kind: "start" }>,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceRecord>> {
-  const recordsResult = listInstanceRecords(root);
-  if (recordsResult.kind === "error") return fromRegistry(recordsResult);
-  const pathsResult = getInstancePaths(root, action.name);
-  if (pathsResult.kind === "error") return fromRegistry(pathsResult);
-  const host = action.overrides.host ?? DEFAULT_INSTANCE_HOST;
-  const pairResult = await planInstancePorts({
-    records: recordsResult.value,
-    requestedPublicPort: action.overrides.port ?? undefined,
-    publicHost: host,
-    isPortAvailable: deps.isPortAvailable,
-  });
-  if (pairResult.kind === "error") return fromRegistry(pairResult);
-  const requestedDataDir = action.overrides.dataDir ?? pathsResult.value.dataDir;
-  const dataDirResult = validateInstanceDataDirectory(requestedDataDir, recordsResult.value);
-  if (dataDirResult.kind === "error") return dataDirResult;
-  const created = createInstanceRecord({
-    name: action.name,
-    host,
-    publicPort: pairResult.value.publicPort,
-    upstreamPort: pairResult.value.upstreamPort,
-    basePath: action.overrides.basePath ?? getConfiguredBasePath(process.env),
-    captureMode: action.overrides.captureMode ?? DEFAULT_INSTANCE_CAPTURE_MODE,
-    backend: action.overrides.backend ?? resolveDefaultInstanceBackend(deps),
-    uiEnabled: action.overrides.uiEnabled ?? true,
-    dataDir: dataDirResult.value,
-  });
-  return created.kind === "error" ? fromRegistry(created) : saveRecord(root, created.value);
-}
-
-async function prepareStoppedStart(
-  root: string,
-  record: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceRecord>> {
-  const records = listInstanceRecords(root);
-  if (records.kind === "error") return fromRegistry(records);
-  const pair = await planInstancePorts({
-    records: records.value,
-    requestedPublicPort: record.publicPort,
-    requestedUpstreamPort: record.upstreamPort,
-    excludeName: record.name,
-    publicHost: record.host,
-    isPortAvailable: deps.isPortAvailable,
-  });
-  if (pair.kind === "error") return fromRegistry(pair);
-  const dataDir = validateInstanceDataDirectory(record.dataDir, records.value, record.name);
-  if (dataDir.kind === "error") return dataDir;
-  const rotated = rotateInstanceLaunch({ ...record, dataDir: dataDir.value });
-  return rotated.kind === "error" ? fromRegistry(rotated) : saveRecord(root, rotated.value);
-}
-
-async function startAction(
-  root: string,
-  action: Extract<InstanceAction, { kind: "start" }>,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  return withLocks(root, action.name, true, async () => {
-    const read = readInstanceRecord(root, action.name);
-    if (read.kind === "error") return fromRegistry(read);
-    if (read.value === null) {
-      const created = await createNewRecord(root, action, deps);
-      if (created.kind === "error") return created;
-      const launched = await launchRecord(created.value, action.overrides.open, deps);
-      return launched.kind === "error"
-        ? launched
-        : success(operationOutput("start", "created", statusOutput(created.value, launched.value)));
-    }
-
-    const record = read.value;
-    if (overridesDiffer(record, action)) {
-      return failure(
-        "config_mismatch",
-        `Instance ${record.name} already has saved configuration; use "agent-inspector instance restart ${record.name}" with overrides to change it.`,
-      );
-    }
-    const live = await classifyRecord(record, deps);
-    if (live.state === "running") {
-      if (action.overrides.open && record.uiEnabled) {
-        (deps.openUrl ?? defaultOpenUrl)(recordUrls(record).ui);
-      }
-      return success(operationOutput("start", "already_running", statusOutput(record, live)));
-    }
-    if (live.state === "conflict") {
-      return failure(
-        live.code,
-        `Instance ${record.name} does not own its saved port pair; no process was terminated.`,
-      );
-    }
-    const prepared = await prepareStoppedStart(root, record, deps);
-    if (prepared.kind === "error") return prepared;
-    const launched = await launchRecord(prepared.value, action.overrides.open, deps);
-    return launched.kind === "error"
-      ? launched
-      : success(operationOutput("start", "started", statusOutput(prepared.value, launched.value)));
-  });
-}
-
-async function planRestartRecord(
-  root: string,
-  record: InstanceRecord,
-  action: Extract<InstanceAction, { kind: "restart" }>,
-  wasRunning: boolean,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceRecord>> {
-  const records = listInstanceRecords(root);
-  if (records.kind === "error") return fromRegistry(records);
-  const desiredPublicPort = action.overrides.port ?? record.publicPort;
-  const desiredUpstreamPort = desiredPublicPort + 2;
-  const sameLivePair =
-    wasRunning &&
-    desiredPublicPort === record.publicPort &&
-    desiredUpstreamPort === record.upstreamPort;
-  let pair: InstancePortPair;
-  if (sameLivePair) {
-    pair = { publicPort: record.publicPort, upstreamPort: record.upstreamPort };
-  } else {
-    const planned = await planInstancePorts({
-      records: records.value,
-      requestedPublicPort: desiredPublicPort,
-      requestedUpstreamPort: desiredUpstreamPort,
-      excludeName: record.name,
-      publicHost: action.overrides.host ?? record.host,
-      isPortAvailable: deps.isPortAvailable,
-    });
-    if (planned.kind === "error") return fromRegistry(planned);
-    pair = planned.value;
-  }
-  const requestedDataDir = action.overrides.dataDir ?? record.dataDir;
-  const dataDir = validateInstanceDataDirectory(requestedDataDir, records.value, record.name);
-  if (dataDir.kind === "error") return dataDir;
-  return updatedRecord(record, action, pair, dataDir.value);
-}
-
-async function rollbackRestart(
-  root: string,
-  previous: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<boolean> {
-  const rotated = rotateInstanceLaunch(previous);
-  if (rotated.kind === "error") return false;
-  const saved = saveRecord(root, rotated.value);
-  if (saved.kind === "error") return false;
-  const launched = await launchRecord(saved.value, false, deps);
-  return launched.kind === "success";
-}
-
-async function restartFailureAfterStop<T>(
-  root: string,
-  previous: InstanceRecord,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<T>> {
-  const rolledBack = await rollbackRestart(root, previous, deps);
-  return rolledBack
-    ? failure(
-        "restart_failed_rolled_back",
-        `Instance ${previous.name} replacement failed; the previous configuration was restored with a fresh launch.`,
-      )
-    : failure(
-        "restart_failed_degraded",
-        `Instance ${previous.name} replacement and rollback both failed; its saved configuration remains recoverable for a later start.`,
-      );
-}
-
-async function restartAction(
-  root: string,
-  action: Extract<InstanceAction, { kind: "restart" }>,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  return withLocks(root, action.name, true, async () => {
-    const required = readRequiredRecord(root, action.name);
-    if (required.kind === "error") return required;
-    const current = required.value;
-    const live = await classifyRecord(current, deps);
-    if (live.state === "conflict") {
-      return failure(
-        live.code,
-        `Instance ${current.name} does not own its saved port pair; refusing to replace another process.`,
-      );
-    }
-    const planned = await planRestartRecord(root, current, action, live.state === "running", deps);
-    if (planned.kind === "error") return planned;
-    if (live.state === "running") {
-      const stopped = await stopRecord(current, deps);
-      if (stopped.kind === "error") return stopped;
-      if (
-        planned.value.publicPort === current.publicPort &&
-        planned.value.upstreamPort === current.upstreamPort
-      ) {
-        const check = deps.isPortAvailable ?? isPortAvailableByBinding;
-        if (
-          !(await check(current.publicPort, current.host)) ||
-          !(await check(current.upstreamPort, DEFAULT_INSTANCE_HOST))
-        ) {
-          return failure(
-            "port_conflict",
-            `Instance ${current.name} ports did not become available after shutdown.`,
-          );
-        }
-      }
-    }
-    const saved = saveRecord(root, planned.value);
-    if (saved.kind === "error") {
-      return live.state === "running" ? restartFailureAfterStop(root, current, deps) : saved;
-    }
-    const launched = await launchRecord(saved.value, action.overrides.open, deps);
-    if (launched.kind === "error") {
-      return live.state === "running" ? restartFailureAfterStop(root, current, deps) : launched;
-    }
-    return success(
-      operationOutput("restart", "restarted", statusOutput(saved.value, launched.value)),
-    );
-  });
-}
-
-async function stopAction(
-  root: string,
-  action: Extract<InstanceAction, { kind: "stop" }>,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  return withLocks(root, action.name, false, async () => {
-    const required = readRequiredRecord(root, action.name);
-    if (required.kind === "error") return required;
-    const stopped = await stopRecord(required.value, deps);
-    return stopped.kind === "error"
-      ? stopped
-      : success(
-          operationOutput(
-            "stop",
-            stopped.value.outcome,
-            statusOutput(required.value, stopped.value.live),
-          ),
-        );
-  });
-}
-
-async function statusAction(
-  root: string,
-  name: string,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<InstanceStatusOutput>> {
-  const required = readRequiredRecord(root, name);
-  if (required.kind === "error") return required;
-  const live = await classifyRecord(required.value, deps);
-  return success(statusOutput(required.value, live));
-}
-
-async function listAction(
-  root: string,
-  deps: InstanceLifecycleDependencies,
-): Promise<InstanceLifecycleResult<readonly InstanceStatusOutput[]>> {
-  const records = listInstanceRecords(root);
-  if (records.kind === "error") return fromRegistry(records);
-  const outputs = await Promise.all(
-    records.value.map(async (record) => statusOutput(record, await classifyRecord(record, deps))),
-  );
-  return success(outputs);
-}
-
-function requestActionOverrides(
-  input: InstanceStartRequest,
-): Extract<InstanceAction, { kind: "start" }>["overrides"] {
-  return {
-    backend: input.backend ?? null,
-    port: input.port ?? null,
-    basePath: input.basePath === undefined ? null : normalizePublicBasePath(input.basePath),
-    host: input.host ?? null,
-    captureMode: input.captureMode ?? null,
-    uiEnabled: input.uiEnabled ?? null,
-    dataDir: input.dataDir ?? null,
-    open: false,
-  };
-}
-
-function lifecycleRoot(deps: InstanceLifecycleDependencies): string {
-  return resolvePath(deps.root ?? getInstancesRoot());
-}
-
-function normalizedServiceName(rawName: string): InstanceLifecycleResult<string> {
-  const validated = validateInstanceName(rawName);
-  return validated.kind === "error" ? fromRegistry(validated) : success(validated.value);
-}
-
-export async function startNamedInstance(
-  rawName: string,
-  input: InstanceStartRequest = {},
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  const name = normalizedServiceName(rawName);
-  if (name.kind === "error") return name;
-  return startAction(
-    lifecycleRoot(deps),
-    { kind: "start", name: name.value, overrides: requestActionOverrides(input), json: true },
-    deps,
-  );
-}
-
-export async function restartNamedInstance(
-  rawName: string,
-  input: InstanceStartRequest = {},
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  const name = normalizedServiceName(rawName);
-  if (name.kind === "error") return name;
-  return restartAction(
-    lifecycleRoot(deps),
-    { kind: "restart", name: name.value, overrides: requestActionOverrides(input), json: true },
-    deps,
-  );
-}
-
-export async function stopNamedInstance(
-  rawName: string,
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<InstanceOperationOutput>> {
-  const name = normalizedServiceName(rawName);
-  if (name.kind === "error") return name;
-  return stopAction(lifecycleRoot(deps), { kind: "stop", name: name.value, json: true }, deps);
-}
-
-export async function getNamedInstance(
-  rawName: string,
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<InstanceStatusOutput>> {
-  const name = normalizedServiceName(rawName);
-  if (name.kind === "error") return name;
-  return statusAction(lifecycleRoot(deps), name.value, deps);
-}
-
-export async function getNamedInstanceConnection(
-  rawName: string,
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<InstanceConnectionOutput>> {
-  const instance = await getNamedInstance(rawName, deps);
-  return instance.kind === "error" ? instance : success(connectionOutput(instance.value));
-}
-
-export async function listNamedInstances(
-  deps: InstanceLifecycleDependencies = {},
-): Promise<InstanceLifecycleResult<readonly InstanceStatusOutput[]>> {
-  return listAction(lifecycleRoot(deps), deps);
-}
-
-function formatStatus(output: InstanceStatusOutput): string {
-  const pid = output.supervisorPid === null ? "-" : String(output.supervisorPid);
-  const reason = output.stateReason === null ? "-" : output.stateReason;
-  const ui = output.uiEnabled ? output.urls.ui : `disabled (configured URL: ${output.urls.ui})`;
-  return `Instance ${output.name}: ${output.state}
-  UI:             ${ui}
-  UI enabled:     ${output.uiEnabled ? "yes" : "no"}
-  Proxy:          ${output.urls.proxy}
-  OpenAI /v1:     ${output.urls.openai}
-  MCP:            ${output.urls.mcp}
-  Health:         ${output.urls.health}
-  Port pair:      ${String(output.publicPort)} / ${String(output.upstreamPort)} (private)
-  Base Path:      ${output.basePath}
-  Capture mode:   ${output.captureMode}
-  Backend:        ${output.backend}
-  Data directory: ${output.dataDir}
-  Supervisor PID: ${pid}
-  State reason:   ${reason}
-`;
-}
-
-function formatConnection(output: InstanceConnectionOutput): string {
-  return `${formatStatus(output.instance)}
-Coding Agent connection:
-  ANTHROPIC_BASE_URL=${output.environment.ANTHROPIC_BASE_URL}
-  LLM_BASE_URL=${output.environment.LLM_BASE_URL}
-  OPENAI_BASE_URL=${output.environment.OPENAI_BASE_URL}
-  AGENT_INSPECTOR_MCP_URL=${output.environment.AGENT_INSPECTOR_MCP_URL}
-  MCP server name: ${output.mcp.serverName}
-  Codex provider:  ${output.codex.providerName} (${output.codex.wireApi})
-`;
-}
-
-function writeError(io: InstanceIo, json: boolean, error: InstanceLifecycleError): void {
-  if (json) {
-    io.stderr(`${JSON.stringify({ schemaVersion: INSTANCE_API_SCHEMA_VERSION, error })}\n`);
-    return;
-  }
-  io.stderr(`agent-inspector instance: ${error.message} (${error.code})\n`);
-}
-
-function writeConnectionOutput(
-  io: InstanceIo,
-  json: boolean,
-  output: InstanceConnectionOutput,
-): void {
-  io.stdout(json ? `${JSON.stringify(output, null, 2)}\n` : formatConnection(output));
-}
-
-function writeSingleOutput(io: InstanceIo, json: boolean, output: InstanceStatusOutput): void {
-  io.stdout(json ? `${JSON.stringify(output, null, 2)}\n` : formatStatus(output));
-}
-
-function writeListOutput(
-  io: InstanceIo,
-  json: boolean,
-  outputs: readonly InstanceStatusOutput[],
-): void {
-  if (json) {
-    io.stdout(`${JSON.stringify({ schemaVersion: 1, instances: outputs }, null, 2)}\n`);
-    return;
-  }
-  io.stdout(
-    outputs.length === 0
-      ? "No named Agent Inspector instances are registered.\n"
-      : outputs.map(formatStatus).join("\n"),
-  );
-}
-
-function normalizeActionName(action: InstanceAction): InstanceLifecycleResult<InstanceAction> {
-  if (action.kind === "list") return success(action);
-  const validated = validateInstanceName(action.name);
-  if (validated.kind === "error") return fromRegistry(validated);
-  return success({ ...action, name: validated.value });
-}
-
-export async function runInstance(
-  argv: readonly string[],
-  deps: InstanceLifecycleDependencies = {},
-  io: InstanceIo = processIo,
-): Promise<number> {
-  const parsed = parseInstanceArgs(argv);
-  if (parsed.kind === "help") {
-    io.stdout(instanceHelp());
-    return 0;
-  }
-  if (parsed.kind === "error") {
-    if (argv.includes("--json")) {
-      writeError(io, true, {
-        code: "argument_invalid",
-        message: parsed.message,
-        retryable: false,
-      });
-    } else {
-      io.stderr(`${parsed.message}\n\n${instanceHelp()}`);
-    }
-    return 2;
-  }
-  const normalized = normalizeActionName(parsed.action);
-  if (normalized.kind === "error") {
-    writeError(io, parsed.action.json, normalized.error);
-    return 2;
-  }
-  const root = resolvePath(deps.root ?? getInstancesRoot());
-  const action = normalized.value;
-  switch (action.kind) {
-    case "start": {
-      const result = await startAction(root, action, deps);
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeSingleOutput(io, action.json, result.value.instance);
-      return 0;
-    }
-    case "restart": {
-      const result = await restartAction(root, action, deps);
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeSingleOutput(io, action.json, result.value.instance);
-      return 0;
-    }
-    case "stop": {
-      const result = await stopAction(root, action, deps);
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeSingleOutput(io, action.json, result.value.instance);
-      return 0;
-    }
-    case "status": {
-      const result = await statusAction(root, action.name, deps);
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeSingleOutput(io, action.json, result.value);
-      return result.value.state === "conflict" ? 1 : 0;
-    }
-    case "connect": {
-      const result = await getNamedInstanceConnection(action.name, { ...deps, root });
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeConnectionOutput(io, action.json, result.value);
-      return result.value.instance.state === "conflict" ? 1 : 0;
-    }
-    case "list": {
-      const result = await listAction(root, deps);
-      if (result.kind === "error") {
-        writeError(io, action.json, result.error);
-        return 1;
-      }
-      writeListOutput(io, action.json, result.value);
-      return 0;
-    }
-  }
-}