agent-gear 2.4.0 → 2.5.0

package/src/cloud-host/supervisor.test.ts

@@ -0,0 +1,367 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import type { Socket } from 'socket.io-client';
+import {
+  CLOUD_HOST_MODE_KEYS,
+  DEFAULT_HARNESS_INIT_WAIT_MS,
+  DEFAULT_WORKSPACE,
+  CloudHostEnvError,
+  isCloudHostMode,
+  parseInitWaitMs,
+  readCloudHostEnv,
+  resolveShutdownExitCode,
+  startCloudHostSupervisor,
+} from './supervisor.js';
+import type { ConnectToServerOptions } from '../socketio-client.js';
+
+const TMP_BASE = '/tmp/opencode';
+
+const BASE_ENV: NodeJS.ProcessEnv = {
+  ZAG_HOST_ENDPOINT: 'wss://controller.example.com',
+  ZAG_HOST_KEY: 'zag_k_1_host_key_secret',
+  ZAG_CONTROLLER_KEY: 'controller-token-secret',
+  ZAG_SERVER_ENDPOINT: 'wss://cloud-controller.example.com/worker',
+  ZAG_HOST_NAME: 'my-cloud-host',
+  ZAG_DEFAULT_WORKSPACE: '/root/workspace',
+};
+
+interface FakeSocket {
+  disconnect: ReturnType<typeof vi.fn>;
+  emit: ReturnType<typeof vi.fn>;
+}
+
+function fakeSocket(): FakeSocket {
+  return { disconnect: vi.fn(), emit: vi.fn() };
+}
+
+function setup(overrides: { env?: NodeJS.ProcessEnv; makeDir?: (path: string) => Promise<void> } = {}) {
+  const worker = fakeSocket();
+  const controller = fakeSocket();
+  const connect = vi.fn((endpoint: string, key: string, options?: ConnectToServerOptions) => {
+    void endpoint;
+    void key;
+    void options;
+    return (connect.mock.calls.length === 1 ? worker : controller) as unknown as Socket;
+  });
+  const exit = vi.fn();
+  const logs: string[] = [];
+  return {
+    worker,
+    controller,
+    connect,
+    exit,
+    logs,
+    deps: {
+      env: overrides.env ?? { ...BASE_ENV },
+      connect: connect as never,
+      makeDir: overrides.makeDir ?? (async () => {}),
+      exit,
+      log: (message: string) => logs.push(message),
+      installSignalHandlers: false,
+    },
+  };
+}
+
+describe('cloud host mode detection (T-AG2)', () => {
+  it('requires all three cloud-host env variables to be non-empty', () => {
+    expect(isCloudHostMode(BASE_ENV)).toBe(true);
+    for (const key of CLOUD_HOST_MODE_KEYS) {
+      expect(isCloudHostMode({ ...BASE_ENV, [key]: '' })).toBe(false);
+      expect(isCloudHostMode({ ...BASE_ENV, [key]: '   ' })).toBe(false);
+      expect(isCloudHostMode({ ...BASE_ENV, [key]: undefined })).toBe(false);
+    }
+    // 本地控制器单连接（无 ZAG_HOST_*）不进入云电脑模式
+    expect(isCloudHostMode({
+      ZAG_SERVER_ENDPOINT: 'http://localhost:4001',
+      ZAG_CONTROLLER_KEY: 'zag_k_1_local',
+    })).toBe(false);
+  });
+
+  it('parses HARNESS_INIT_WAIT_MS with the 10 minute default', () => {
+    expect(parseInitWaitMs(undefined)).toBe(DEFAULT_HARNESS_INIT_WAIT_MS);
+    expect(DEFAULT_HARNESS_INIT_WAIT_MS).toBe(600_000);
+    expect(parseInitWaitMs('1500')).toBe(1500);
+    expect(parseInitWaitMs('0')).toBe(DEFAULT_HARNESS_INIT_WAIT_MS);
+    expect(parseInitWaitMs('-1')).toBe(DEFAULT_HARNESS_INIT_WAIT_MS);
+    expect(parseInitWaitMs('abc')).toBe(DEFAULT_HARNESS_INIT_WAIT_MS);
+  });
+});
+
+describe('readCloudHostEnv (T-AG7)', () => {
+  it('reads required values and applies defaults', () => {
+    const env = readCloudHostEnv({
+      ZAG_HOST_ENDPOINT: ' wss://controller.example.com ',
+      ZAG_HOST_KEY: 'host-key',
+      ZAG_CONTROLLER_KEY: 'worker-token',
+      ZAG_SERVER_ENDPOINT: 'wss://cc.example.com/worker',
+    });
+
+    expect(env).toMatchObject({
+      hostEndpoint: 'wss://controller.example.com',
+      hostKey: 'host-key',
+      controllerKey: 'worker-token',
+      serverEndpoint: 'wss://cc.example.com/worker',
+      workspace: DEFAULT_WORKSPACE,
+      initWaitMs: DEFAULT_HARNESS_INIT_WAIT_MS,
+    });
+    expect(env.hostName.length).toBeGreaterThan(0);
+  });
+
+  it('lists every missing variable by name without leaking values of present ones', () => {
+    let error: unknown;
+    try {
+      readCloudHostEnv({
+        ZAG_HOST_ENDPOINT: 'wss://controller.example.com',
+        ZAG_HOST_KEY: 'super-secret-host-key',
+      });
+    } catch (caught) {
+      error = caught;
+    }
+
+    expect(error).toBeInstanceOf(CloudHostEnvError);
+    const message = (error as Error).message;
+    expect(message).toContain('ZAG_CONTROLLER_KEY');
+    expect(message).toContain('ZAG_SERVER_ENDPOINT');
+    expect(message).not.toContain('super-secret-host-key');
+    expect(message).not.toContain('wss://controller.example.com');
+  });
+});
+
+describe('startCloudHostSupervisor', () => {
+  const dirs: string[] = [];
+
+  afterEach(async () => {
+    await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+  });
+
+  it('T-AG6: creates the default workspace idempotently before connecting', async () => {
+    await mkdir(TMP_BASE, { recursive: true });
+    const dir = await mkdtemp(join(TMP_BASE, 'supervisor-'));
+    dirs.push(dir);
+    const workspace = join(dir, 'workspace', 'nested');
+
+    const context = setup({
+      env: { ...BASE_ENV, ZAG_DEFAULT_WORKSPACE: workspace },
+      makeDir: async (path: string) => {
+        await mkdir(path, { recursive: true });
+      },
+    });
+    const handle = await startCloudHostSupervisor(context.deps);
+    await startCloudHostSupervisor(context.deps);
+
+    expect((await stat(workspace)).isDirectory()).toBe(true);
+    expect(handle.workspace).toBe(workspace);
+    // makeDir 在连接之前完成（connect 的调用发生在其后）
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG3: connects /worker first with the one-time token and no local MCP server', async () => {
+    const context = setup();
+    const handle = await startCloudHostSupervisor(context.deps);
+
+    expect(context.connect).toHaveBeenCalledTimes(1);
+    const [endpoint, key, options] = context.connect.mock.calls[0] as [string, string, ConnectToServerOptions];
+    expect(endpoint).toBe(BASE_ENV.ZAG_SERVER_ENDPOINT);
+    expect(key).toBe(BASE_ENV.ZAG_CONTROLLER_KEY);
+    expect(options).toMatchObject({
+      serverName: 'my-cloud-host',
+      handshakeToken: BASE_ENV.ZAG_CONTROLLER_KEY,
+      skipLocalMcpStart: true,
+      handleWorkload: true,
+      persistConfig: false,
+    });
+    expect(handle.controllerSocket).toBeNull();
+  });
+
+  it('T-AG3b: connects controller-api immediately when initializing is false/absent', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: false });
+
+    expect(context.connect).toHaveBeenCalledTimes(2);
+    const [endpoint, key, options] = context.connect.mock.calls[1] as [string, string, ConnectToServerOptions];
+    expect(endpoint).toBe(BASE_ENV.ZAG_HOST_ENDPOINT);
+    expect(key).toBe(BASE_ENV.ZAG_HOST_KEY);
+    expect(options).toMatchObject({
+      handshakeToken: BASE_ENV.ZAG_HOST_KEY,
+      skipLocalMcpStart: false,
+      handleWorkload: false,
+      persistConfig: false,
+    });
+
+    // 重复 registered（重连）不应重复建连
+    workerOptions.onRegistered?.({ controllerId: 'container-1' });
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG4: waits for the first init workload batch when initializing=true', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    expect(context.connect).toHaveBeenCalledTimes(1);
+
+    // post 批次不触发标准连接
+    workerOptions.onWorkloadBatchComplete?.({ phase: 'post', itemCount: 1, status: 'completed' });
+    expect(context.connect).toHaveBeenCalledTimes(1);
+
+    workerOptions.onWorkloadBatchComplete?.({ phase: 'init', itemCount: 2, status: 'completed' });
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG4b: connects after a failed init batch too', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    workerOptions.onWorkloadBatchComplete?.({ phase: 'init', itemCount: 1, status: 'failed', error: 'boom' });
+
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG4e: does not treat an interrupted (cancelled) init batch as complete', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    workerOptions.onWorkloadBatchComplete?.({
+      phase: 'init',
+      itemCount: 1,
+      status: 'cancelled',
+      cancelled: true,
+      failedCount: 0,
+    });
+
+    expect(context.connect).toHaveBeenCalledTimes(1);
+
+    // 重连重放后的真实 init 完成才建立标准连接
+    workerOptions.onWorkloadBatchComplete?.({
+      phase: 'init',
+      itemCount: 1,
+      status: 'completed',
+      cancelled: false,
+      failedCount: 0,
+    });
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG4c: connects after the init wait timeout', async () => {
+    const context = setup({ env: { ...BASE_ENV, HARNESS_INIT_WAIT_MS: '20' } });
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    expect(context.connect).toHaveBeenCalledTimes(1);
+
+    await vi.waitFor(() => {
+      expect(context.connect).toHaveBeenCalledTimes(2);
+    });
+
+    // 超时后迟到的 initializing registered 不得再次进入等待（不产生幽灵定时器/重复连接）
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    expect(context.connect).toHaveBeenCalledTimes(2);
+    expect(context.logs.join('\n')).toContain('timed out');
+  });
+
+  it('T-AG4d: connects immediately when the init batch finished before registered', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onWorkloadBatchComplete?.({ phase: 'init', itemCount: 1, status: 'completed' });
+    expect(context.connect).toHaveBeenCalledTimes(1);
+
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: true });
+    expect(context.connect).toHaveBeenCalledTimes(2);
+  });
+
+  it('T-AG17: shutdown from either side closes both sockets and exits 0 without unregister', async () => {
+    const context = setup();
+    const handle = await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: false });
+    const controllerOptions = context.connect.mock.calls[1][2] as ConnectToServerOptions;
+
+    workerOptions.onShutdown?.({ reason: 'server requested shutdown' });
+
+    expect(context.worker.disconnect).toHaveBeenCalled();
+    expect(context.controller.disconnect).toHaveBeenCalled();
+    expect(context.exit).toHaveBeenCalledWith(0);
+    expect(context.worker.emit).not.toHaveBeenCalledWith('unregister', expect.anything());
+    expect(context.controller.emit).not.toHaveBeenCalledWith('unregister', expect.anything());
+
+    // 另一端 shutdown / 重复 shutdown 幂等
+    controllerOptions.onShutdown?.({ reason: 'duplicate' });
+    handle.shutdown('SIGTERM');
+    expect(context.exit).toHaveBeenCalledTimes(1);
+  });
+
+  it('T-AG17b: worker shutdown before the controller connection only closes the worker', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onShutdown?.({ reason: 'server requested shutdown' });
+
+    expect(context.worker.disconnect).toHaveBeenCalled();
+    expect(context.controller.disconnect).not.toHaveBeenCalled();
+    expect(context.exit).toHaveBeenCalledWith(0);
+  });
+
+  it('C-2: failure/version-mismatch shutdown exits non-zero (entrypoint self-heal path)', async () => {
+    // socketio-client 的错误事件 reason 前缀
+    expect(resolveShutdownExitCode('version_mismatch: agent-gear 版本不兼容')).toBe(1);
+    expect(resolveShutdownExitCode('error: REGISTER_FAILED')).toBe(1);
+    // 必须工作负载初始化失败（worker shutdown 包装后仍须识别）
+    expect(resolveShutdownExitCode('worker shutdown: 必须工作负载「OpenCode（Harness）」初始化失败')).toBe(1);
+    expect(resolveShutdownExitCode('required init failed')).toBe(1);
+    // 正常路径
+    expect(resolveShutdownExitCode('controller-api shutdown: server requested')).toBe(0);
+    expect(resolveShutdownExitCode('SIGINT')).toBe(0);
+    expect(resolveShutdownExitCode('unregistered')).toBe(0);
+  });
+
+  it('C-2: required init failure closes both sockets and exits 1', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+    workerOptions.onRegistered?.({ controllerId: 'container-1', initializing: false });
+
+    workerOptions.onShutdown?.({ reason: 'worker shutdown: 必须工作负载初始化失败' });
+
+    expect(context.worker.disconnect).toHaveBeenCalled();
+    expect(context.controller.disconnect).toHaveBeenCalled();
+    expect(context.exit).toHaveBeenCalledWith(1);
+    expect(context.worker.emit).not.toHaveBeenCalledWith('unregister', expect.anything());
+
+    // 显式 code 优先（调用方可覆盖）
+    const explicit = setup();
+    const explicitHandle = await startCloudHostSupervisor(explicit.deps);
+    explicitHandle.shutdown('server requested shutdown', 1);
+    expect(explicit.exit).toHaveBeenCalledWith(1);
+  });
+
+  it('C-2: version_mismatch reason exits 1', async () => {
+    const context = setup();
+    await startCloudHostSupervisor(context.deps);
+    const workerOptions = context.connect.mock.calls[0][2] as ConnectToServerOptions;
+
+    workerOptions.onShutdown?.({ reason: 'version_mismatch: agent-gear 版本不兼容' });
+
+    expect(context.exit).toHaveBeenCalledWith(1);
+  });
+
+  it('T-AG7b: rejects with a clear error instead of connecting when cloud-host env is incomplete', async () => {
+    const context = setup({ env: { ...BASE_ENV, ZAG_HOST_KEY: '' } });
+
+    await expect(startCloudHostSupervisor(context.deps)).rejects.toBeInstanceOf(CloudHostEnvError);
+    expect(context.connect).not.toHaveBeenCalled();
+    expect(context.exit).not.toHaveBeenCalled();
+  });
+});

package/src/cloud-host/supervisor.ts

@@ -0,0 +1,289 @@
+import { mkdir } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import type { Socket } from 'socket.io-client';
+import {
+  connectToServer,
+  parseEndpoint,
+  type ConnectToServerOptions,
+} from '../socketio-client.js';
+
+/** 未设置 `HARNESS_INIT_WAIT_MS` 时的初始化等待上限（10 分钟）。 */
+export const DEFAULT_HARNESS_INIT_WAIT_MS = 600_000;
+
+/** 未设置 `ZAG_DEFAULT_WORKSPACE` 时的默认工作区（容器内以 root 运行）。 */
+export const DEFAULT_WORKSPACE = '/root/workspace';
+
+/** 云电脑模式必需的环境变量（三者同时非空才进入 supervisor）。 */
+export const CLOUD_HOST_MODE_KEYS = ['ZAG_HOST_ENDPOINT', 'ZAG_HOST_KEY', 'ZAG_CONTROLLER_KEY'] as const;
+
+/** 云电脑 supervisor 的运行参数（从容器 env 读取）。 */
+export interface CloudHostEnv {
+  /** controller-api 标准连接地址（env `ZAG_HOST_ENDPOINT`）。 */
+  hostEndpoint: string;
+  /** 标准连接凭据（env `ZAG_HOST_KEY`，仅经握手 auth.token 携带）。 */
+  hostKey: string;
+  /** cloud-controller `/worker` 一次性 token（env `ZAG_CONTROLLER_KEY`）。 */
+  controllerKey: string;
+  /** cloud-controller `/worker` 地址（env `ZAG_SERVER_ENDPOINT`）。 */
+  serverEndpoint: string;
+  /** 注册上报的主机名（env `ZAG_HOST_NAME`，缺省 `os.hostname()`）。 */
+  hostName: string;
+  /** 默认工作区（env `ZAG_DEFAULT_WORKSPACE`，缺省 `/root/workspace`）。 */
+  workspace: string;
+  /** 初始化等待超时（env `HARNESS_INIT_WAIT_MS`，缺省 10 分钟）。 */
+  initWaitMs: number;
+}
+
+/** 云电脑 env 校验失败（消息只含变量名，不含任何值）。 */
+export class CloudHostEnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CloudHostEnvError';
+  }
+}
+
+function nonEmpty(value: string | undefined): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * 模式检测：同时设置 `ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY` + `ZAG_CONTROLLER_KEY` 且非空
+ * → 云电脑模式；否则沿用本地控制器单连接旧路径。
+ */
+export function isCloudHostMode(env: NodeJS.ProcessEnv = process.env): boolean {
+  return CLOUD_HOST_MODE_KEYS.every((key) => nonEmpty(env[key]).length > 0);
+}
+
+/** 解析初始化等待超时：显式非正整数时回退默认值（不因错误配置阻塞上线）。 */
+export function parseInitWaitMs(value: string | undefined): number {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_HARNESS_INIT_WAIT_MS;
+}
+
+/**
+ * 读取并校验云电脑模式 env。
+ *
+ * 缺失项一次性列出变量名（便于 init 日志定位），**绝不输出变量值**（含 secret）。
+ */
+export function readCloudHostEnv(env: NodeJS.ProcessEnv = process.env): CloudHostEnv {
+  const required = [
+    'ZAG_HOST_ENDPOINT',
+    'ZAG_HOST_KEY',
+    'ZAG_CONTROLLER_KEY',
+    'ZAG_SERVER_ENDPOINT',
+  ] as const;
+  const missing = required.filter((key) => nonEmpty(env[key]).length === 0);
+  if (missing.length > 0) {
+    throw new CloudHostEnvError(
+      `missing required environment variable(s) for cloud-host mode: ${missing.join(', ')}`,
+    );
+  }
+
+  return {
+    hostEndpoint: nonEmpty(env.ZAG_HOST_ENDPOINT),
+    hostKey: nonEmpty(env.ZAG_HOST_KEY),
+    controllerKey: nonEmpty(env.ZAG_CONTROLLER_KEY),
+    serverEndpoint: nonEmpty(env.ZAG_SERVER_ENDPOINT),
+    hostName: nonEmpty(env.ZAG_HOST_NAME) || hostname(),
+    workspace: nonEmpty(env.ZAG_DEFAULT_WORKSPACE) || DEFAULT_WORKSPACE,
+    initWaitMs: parseInitWaitMs(env.HARNESS_INIT_WAIT_MS),
+  };
+}
+
+/** 依赖注入（测试锚定时序与副作用；生产使用默认实现）。 */
+export interface CloudHostSupervisorDeps {
+  env?: NodeJS.ProcessEnv;
+  connect?: (endpoint: string, key: string, options?: ConnectToServerOptions) => Socket;
+  makeDir?: (path: string) => Promise<void>;
+  exit?: (code: number) => void;
+  log?: (message: string) => void;
+  /** 是否接管 SIGINT/SIGTERM（默认 true；测试关闭以免污染进程）。 */
+  installSignalHandlers?: boolean;
+}
+
+export interface CloudHostSupervisorHandle {
+  /** `/worker` 连接（cloud-controller）。 */
+  workerSocket: Socket;
+  /** controller-api 标准连接（初始化完成后才建立）。 */
+  readonly controllerSocket: Socket | null;
+  /** 已创建（幂等）的默认工作区。 */
+  workspace: string;
+  /**
+   * 关闭两端并退出（不发送 `unregister`）。
+   *
+   * `code` 缺省按 `reason` 自动判定：服务端主动 shutdown / 信号 / unregistered → 0；
+   * `version_mismatch:*` / `error:*` / 初始化失败类 → 1（避免错误路径 `exit(0)` 掩盖失败，
+   * 并让 entrypoint 的 VERSION_MISMATCH 自愈生效，C-2）。
+   */
+  shutdown: (reason: string, code?: number) => void;
+}
+
+/**
+ * 错误/失败类 shutdown reason 判定（C-2）：
+ *
+ * - `socketio-client` 把 `VERSION_MISMATCH` / 其它 `error` 事件转成
+ *   `version_mismatch:*` / `error:<code>` 前缀；
+ * - cloud-controller 的必须工作负载失败 reason 形如「必须工作负载「x」初始化失败」
+ *   （经 `worker shutdown: ...` 包装后仍需识别）；
+ * - 其余（服务端主动 shutdown、`unregistered`、SIGINT/SIGTERM）视为正常退出。
+ */
+export function isFailureShutdownReason(reason: string): boolean {
+  const normalized = reason.trim().toLowerCase();
+  // reason 可能被 `worker shutdown:` / `controller-api shutdown:` 包装，用 includes 判定前缀。
+  if (normalized.includes('version_mismatch:') || /(^|[\s:])error:/.test(normalized)) {
+    return true;
+  }
+  return (
+    reason.includes('初始化失败') ||
+    normalized.includes('init failed') ||
+    normalized.includes('initialization failed')
+  );
+}
+
+/** 由 shutdown reason 推导退出码：失败路径 1、正常退出 0。 */
+export function resolveShutdownExitCode(reason: string): number {
+  return isFailureShutdownReason(reason) ? 1 : 0;
+}
+
+/** 日志中的连接目标：仅 origin + namespace，绝不包含 query/token。 */
+function describeEndpoint(endpoint: string): string {
+  const { origin, namespace } = parseEndpoint(endpoint);
+  return namespace === '/' ? origin : `${origin}${namespace}`;
+}
+
+/**
+ * 云电脑双连接 supervisor（契约 `agent-controller-websocket.md` §4.3）：
+ *
+ * 1. `mkdir -p ZAG_DEFAULT_WORKSPACE`（幂等）；
+ * 2. 先连 cloud-controller `/worker`（`ZAG_SERVER_ENDPOINT` + `ZAG_CONTROLLER_KEY`）；
+ * 3. `registered.initializing=true` → 等待首个 `workload:run` 批次结束（成功/失败/超时）后
+ *    再连 controller-api（`ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY`）；`false`/缺省立即连接；
+ * 4. 任一端 `shutdown` → 关闭两端并退出（正常 0；`version_mismatch`/`error`/初始化失败 1）；**始终不发送 `unregister`**；
+ * 5. 仅 controller-api 标准连接启动本地 MCP 回环服务（worker 连接跳过，避免端口冲突）。
+ */
+export async function startCloudHostSupervisor(
+  deps: CloudHostSupervisorDeps = {},
+): Promise<CloudHostSupervisorHandle> {
+  const env = readCloudHostEnv(deps.env ?? process.env);
+  const connect = deps.connect ?? connectToServer;
+  const makeDir = deps.makeDir ?? ((path: string) => mkdir(path, { recursive: true }).then(() => undefined));
+  const exit = deps.exit ?? ((code: number) => process.exit(code));
+  const log = deps.log ?? ((message: string) => console.log(message));
+
+  // 初始化脚本/工作负载需要在工作区落地前执行，先幂等创建工作区。
+  await makeDir(env.workspace);
+  log(`[CloudHost] workspace ready: ${env.workspace}`);
+
+  let controllerSocket: Socket | null = null;
+  let initWaitTimer: ReturnType<typeof setTimeout> | null = null;
+  let waitingForInit = false;
+  let initBatchCompleted = false;
+  let shutdownStarted = false;
+
+  const clearInitTimer = (): void => {
+    if (initWaitTimer) {
+      clearTimeout(initWaitTimer);
+      initWaitTimer = null;
+    }
+  };
+
+  const shutdown = (reason: string, code?: number): void => {
+    if (shutdownStarted) return;
+    shutdownStarted = true;
+    clearInitTimer();
+    const exitCode = code ?? resolveShutdownExitCode(reason);
+    log(`[CloudHost] shutting down: ${reason} (exit ${exitCode})`);
+    try {
+      workerSocket.disconnect();
+    } catch {
+      /* socket may already be closed */
+    }
+    try {
+      controllerSocket?.disconnect();
+    } catch {
+      /* socket may already be closed */
+    }
+    // 不发送 unregister：容器销毁由 agent-api 编排（stopCloudHost / TTL / 失败回调）。
+    // 失败/版本不兼容路径必须非零退出：Job 终态映射为 failed，且 entrypoint 的自愈升级生效（C-2）。
+    exit(exitCode);
+  };
+
+  const connectController = (): void => {
+    if (controllerSocket) return;
+    clearInitTimer();
+    waitingForInit = false;
+    log(`[CloudHost] connecting controller-api: ${describeEndpoint(env.hostEndpoint)}`);
+    controllerSocket = connect(env.hostEndpoint, env.hostKey, {
+      serverName: env.hostName,
+      handshakeToken: env.hostKey,
+      handleWorkload: false,
+      skipLocalMcpStart: false,
+      persistConfig: false,
+      onShutdown: (payload) => shutdown(`controller-api shutdown: ${payload.reason}`),
+    });
+  };
+
+  const waitForInitBatch = (): void => {
+    if (initBatchCompleted) {
+      connectController();
+      return;
+    }
+    if (waitingForInit) return;
+    waitingForInit = true;
+    log(`[CloudHost] waiting for harness initialization (timeout ${env.initWaitMs}ms)`);
+    initWaitTimer = setTimeout(() => {
+      initWaitTimer = null;
+      // 超时后视为已完成：迟到的 registered(initializing=true) 不得再次进入等待（幽灵定时器）。
+      initBatchCompleted = true;
+      log('[CloudHost] harness initialization wait timed out; connecting controller-api anyway');
+      connectController();
+    }, env.initWaitMs);
+  };
+
+  const workerSocket = connect(env.serverEndpoint, env.controllerKey, {
+    serverName: env.hostName,
+    handshakeToken: env.controllerKey,
+    handleWorkload: true,
+    skipLocalMcpStart: true,
+    persistConfig: false,
+    onRegistered: (payload) => {
+      log(`[CloudHost] worker registered: ${payload.controllerId}${payload.initializing ? ' (initializing)' : ''}`);
+      if (payload.initializing) {
+        waitForInitBatch();
+      } else {
+        connectController();
+      }
+    },
+    onWorkloadBatchComplete: (summary) => {
+      if (summary.phase !== 'init') return;
+      if (summary.cancelled || summary.status === 'cancelled') {
+        // 被新批次/销毁打断：不得视为初始化完成（重连重放 init 时 OpenCode 可能仍在安装）。
+        log('[CloudHost] harness initialization interrupted; waiting for replay');
+        return;
+      }
+      initBatchCompleted = true;
+      if (waitingForInit) {
+        log(
+          `[CloudHost] harness initialization finished (${summary.status}` +
+            `${summary.failedCount ? `, failed=${summary.failedCount}` : ''}); connecting controller-api`,
+        );
+        connectController();
+      }
+    },
+    onShutdown: (payload) => shutdown(`worker shutdown: ${payload.reason}`),
+  });
+
+  if (deps.installSignalHandlers !== false) {
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+  }
+
+  return {
+    workerSocket,
+    get controllerSocket() {
+      return controllerSocket;
+    },
+    workspace: env.workspace,
+    shutdown,
+  };
+}