@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/cli/instance.ts

@@ -0,0 +1,1037 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { resolve as resolvePath } from "node:path";
+import {
+  AGENT_INSPECTOR_BASE_PATH_ENV,
+  appendBasePathToOrigin,
+  getConfiguredBasePath,
+  normalizeBasePath,
+} from "../lib/basePath";
+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";
+
+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;
+  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,
+    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,
+    instance,
+    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 {
+    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();
+}
+
+function launchArgs(record: InstanceRecord, open: boolean): string[] {
+  const args = [
+    "--background",
+    "--no-open",
+    "--port",
+    String(record.publicPort),
+    "--host",
+    record.host,
+    "--mode",
+    record.captureMode,
+  ];
+  if (open) args.push("--open");
+  return args;
+}
+
+async function defaultLaunch(
+  record: InstanceRecord,
+  open: boolean,
+  cliEntry: string,
+): Promise<boolean> {
+  const child = spawn(process.execPath, [cliEntry, ...launchArgs(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.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.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.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,
+    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);
+}
+
+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,
+    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) (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 {
+    port: input.port ?? null,
+    basePath: input.basePath === undefined ? null : normalizeBasePath(input.basePath),
+    host: input.host ?? null,
+    captureMode: input.captureMode ?? 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;
+  return `Instance ${output.name}: ${output.state}
+  UI:             ${output.urls.ui}
+  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}
+  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;
+    }
+  }
+}
+
+export const instanceLifecycleForTests = {
+  classifyRecord,
+  launchArgs,
+  statusOutput,
+};