agent-gear 2.4.0 → 2.5.0

package/AGENTS.md

@@ -16,8 +16,19 @@ src/
 ├── config.ts             # Key/endpoint reading with priority chain
 ├── socketio-client.ts    # Socket.IO client connection + event handling（register 上报完整版本）
 ├── heartbeat.ts          # Heartbeat sender (30s interval)
-├── workload-executor.ts  # 工作负载脚本串行执行（超时/截断/重连重放）+ 参数注入
-└── daemon.ts             # Daemon management (PID file, signal handling)
+├── workload-executor.ts  # 工作负载脚本串行执行（超时/截断/重连重放）+ 参数/容器 env 注入 + secret 脱敏
+├── daemon.ts             # Daemon management (PID file, signal handling)
+├── cloud-host/
+│   └── supervisor.ts     # 云电脑双连接（/worker → controller-api）与 init 等待编排
+├── harness/
+│   ├── env.ts            # harness env 校验（ZAG_MODEL_* / ZAG_DEFAULT_WORKSPACE）
+│   ├── opencode-cli.ts   # `opencode --version` 硬校验（兼容 `-v`）
+│   ├── opencode-config.ts# opencode.jsonc 定位/合并（保留注释，仅替换 provider.zag，0600）
+│   └── prepare.ts        # `harness prepare` 编排 + 摘要（不含 secret）
+└── commands/
+    ├── harness.ts        # `agent-gear harness prepare`
+    ├── mcp.ts
+    └── mcp-proxy.ts
 ```
 
 ## 工作负载参数注入
@@ -41,9 +52,57 @@ src/
 - `post` 批次不参与必须判定（`required` 固定 `false`，即使携带 `true` 也不短路）。
 - 无 `required` 字段时行为与旧版完全一致（非必须项失败后继续执行后续条目）。
 
-- 版本：包版本 `2.4.0`（major 保持 2；标记 `items[].required` 短路能力）；worker 镜像内 agent-gear 需
-  `>=2.4.0` 才具备短路优化。参数注入需 `>=2.3.0`。cloud-controller `MIN_WORKER_VERSION` 仍为 `2.2.0`
-  （服务端为唯一裁决，旧 worker 忽略 `required` 仍正确）。
+- 版本：包版本 `2.5.0`（major 保持 2；云电脑双连接 / `harness prepare`，cloud-controller 对
+  `purpose=harness` 的 `MIN_HARNESS_WORKER_VERSION` 为 `2.5.0`）。参数注入需 `>=2.3.0`、`items[].required`
+  短路需 `>=2.4.0`；普通容器 `MIN_WORKER_VERSION` 仍为 `2.2.0`（服务端为唯一裁决，旧 worker 忽略
+  `required` 仍正确）。
+
+## 容器级 env 与 secret 脱敏（2.5.0）
+
+`workload:run` 可携带容器级 `env`（仅 `purpose=harness` 下发，如 `ZAG_MODEL_*` / `ZAG_HOST_*` /
+`ZAG_DEFAULT_WORKSPACE`）。每个 item 的执行环境合并顺序：
+
+```
+process.env  →  容器 env（批次内所有 item）  →  WORKLOAD_PARAMS / WORKLOAD_PARAM_*（item 参数优先）
+```
+
+- `ZAG_MODEL_API_KEY` / `ZAG_HOST_KEY` / `ZAG_CONTROLLER_KEY` 的值在**脚本输出、日志、错误**中统一替换为
+  `***`（`redactSecrets`；日志中的 `workload:run` payload 同样脱敏）。
+- 普通容器不携带 `env`，行为与旧版完全一致。
+
+## 云电脑模式（cloud-host supervisor）
+
+入口默认 action 检测 `ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY` + `ZAG_CONTROLLER_KEY`（三者同时非空）：
+
+| 连接 | endpoint env | 凭据 env | 职责 |
+|------|--------------|----------|------|
+| `/worker`（cloud-controller） | `ZAG_SERVER_ENDPOINT` | `ZAG_CONTROLLER_KEY`（一次性 token） | 生命周期 / 初始化脚本 |
+| controller-api 标准连接 | `ZAG_HOST_ENDPOINT` | `ZAG_HOST_KEY`（仅握手 `auth.token`，不入 URL） | 会话 / ACP / 工作区 / 心跳 |
+
+- 先连 `/worker`：`registered.initializing=true` 时等待首个 `workload:run` init 批次结束（成功/失败）后
+  再连 controller-api；`false`/缺省立即连接；等待上限 `HARNESS_INIT_WAIT_MS`（默认 10 分钟）。
+  **被打断（cancelled）的批次不算完成**（重连重放时继续等待）；超时后迟到的 `registered` 不再次进入等待。
+- 启动时 `mkdir -p ZAG_DEFAULT_WORKSPACE`（默认 `/root/workspace`，幂等）。
+- 云电脑两端连接均 `persistConfig=false`：**不读写** `~/.zag/config.toml`（不落 resumeToken/Key）；
+  本地单连接保持原行为，配置写入使用权限 `0600`。
+- 任一端 `shutdown` → 关闭两端并退出：正常（服务端主动 shutdown/SIGTERM/SIGINT）退出 0；`version_mismatch:*` / `error:*` / 必须工作负载初始化失败退出 1（entrypoint 自愈与失败语义）；**不发送 `unregister`**（容器销毁由 agent-api 编排）。
+- `KEY_ALREADY_ONLINE` 在云电脑模式按 1s→2s→…→30s 退避手动重连；**仅在 `registered` 成功后重置退避计数**（connect 先于 register 结果，不能作为成功信号）。退避定时器不 `unref`，避免双端断开时进程静默退出。
+- 双连接只启动一个 `LocalMcpServer`：`/worker` 连接 `skipLocalMcpStart=true`，标准连接负责启动。
+- 未检测到云电脑模式时保持本地控制器单连接旧行为不变。
+
+## harness prepare（OpenCode）
+
+init 脚本（admin-api 迁移 005）在安装固定版本 OpenCode 后执行 `agent-gear harness prepare`：
+
+1. 校验 `ZAG_MODEL_BASE_URL` / `ZAG_MODEL_API_KEY` / `ZAG_MODEL_IDS`（JSON 数组，去空去重）/
+   `ZAG_DEFAULT_WORKSPACE`；缺失项按变量名报错并非零退出（不泄漏其它 env 值）。
+2. `opencode --version` 硬校验（旧版兼容 `opencode -v`），失败非零退出。
+3. `mkdir -p ZAG_DEFAULT_WORKSPACE`。
+4. 定位 `~/.config/opencode/opencode.jsonc`：同目录已有 `.json` 且无 `.jsonc` 时合并 `.json`；否则新建
+   `.jsonc`。使用 `jsonc-parser` 保留注释与既有 provider，仅替换 `provider.zag`；权限 0600。
+   `provider.zag = { npm: '@ai-sdk/openai-compatible', name: 'ZAG', options: { baseURL, apiKey }, models: { <id>: { name: <id> } } }`。
+
+> 镜像**不预装** `@opencode/cli`，由 harness 工作负载按 `OPENCODE_CLI_VERSION` 固定版本安装。
 
 ## Dev Commands
 

package/dist/cloud-host/supervisor.d.ts

@@ -0,0 +1,92 @@
+import type { Socket } from 'socket.io-client';
+import { type ConnectToServerOptions } from '../socketio-client.js';
+/** 未设置 `HARNESS_INIT_WAIT_MS` 时的初始化等待上限（10 分钟）。 */
+export declare const DEFAULT_HARNESS_INIT_WAIT_MS = 600000;
+/** 未设置 `ZAG_DEFAULT_WORKSPACE` 时的默认工作区（容器内以 root 运行）。 */
+export declare const DEFAULT_WORKSPACE = "/root/workspace";
+/** 云电脑模式必需的环境变量（三者同时非空才进入 supervisor）。 */
+export declare const CLOUD_HOST_MODE_KEYS: readonly ["ZAG_HOST_ENDPOINT", "ZAG_HOST_KEY", "ZAG_CONTROLLER_KEY"];
+/** 云电脑 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 declare class CloudHostEnvError extends Error {
+    constructor(message: string);
+}
+/**
+ * 模式检测：同时设置 `ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY` + `ZAG_CONTROLLER_KEY` 且非空
+ * → 云电脑模式；否则沿用本地控制器单连接旧路径。
+ */
+export declare function isCloudHostMode(env?: NodeJS.ProcessEnv): boolean;
+/** 解析初始化等待超时：显式非正整数时回退默认值（不因错误配置阻塞上线）。 */
+export declare function parseInitWaitMs(value: string | undefined): number;
+/**
+ * 读取并校验云电脑模式 env。
+ *
+ * 缺失项一次性列出变量名（便于 init 日志定位），**绝不输出变量值**（含 secret）。
+ */
+export declare function readCloudHostEnv(env?: NodeJS.ProcessEnv): CloudHostEnv;
+/** 依赖注入（测试锚定时序与副作用；生产使用默认实现）。 */
+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 declare function isFailureShutdownReason(reason: string): boolean;
+/** 由 shutdown reason 推导退出码：失败路径 1、正常退出 0。 */
+export declare function resolveShutdownExitCode(reason: string): number;
+/**
+ * 云电脑双连接 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 declare function startCloudHostSupervisor(deps?: CloudHostSupervisorDeps): Promise<CloudHostSupervisorHandle>;
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/cloud-host/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/cloud-host/supervisor.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAGL,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,mDAAmD;AACnD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,oBAAoB,CAAC;AAEnD,0CAA0C;AAC1C,eAAO,MAAM,oBAAoB,sEAAuE,CAAC;AAEzG,wCAAwC;AACxC,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,mCAAmC;AACnC,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,OAAO,CAE7E;AAED,0CAA0C;AAC1C,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGjE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,YAAY,CAuBnF;AAED,iCAAiC;AACjC,MAAM,WAAW,uBAAuB;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,sBAAsB,KAAK,MAAM,CAAC;IACtF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,+CAA+C;IAC/C,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,yBAAyB;IACxC,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAW/D;AAED,6CAA6C;AAC7C,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE9D;AAQD;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,IAAI,GAAE,uBAA4B,GACjC,OAAO,CAAC,yBAAyB,CAAC,CA2HpC"}

package/dist/cloud-host/supervisor.js

@@ -0,0 +1,216 @@
+import { mkdir } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { connectToServer, parseEndpoint, } 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'];
+/** 云电脑 env 校验失败（消息只含变量名，不含任何值）。 */
+export class CloudHostEnvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CloudHostEnvError';
+    }
+}
+function nonEmpty(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+/**
+ * 模式检测：同时设置 `ZAG_HOST_ENDPOINT` + `ZAG_HOST_KEY` + `ZAG_CONTROLLER_KEY` 且非空
+ * → 云电脑模式；否则沿用本地控制器单连接旧路径。
+ */
+export function isCloudHostMode(env = process.env) {
+    return CLOUD_HOST_MODE_KEYS.every((key) => nonEmpty(env[key]).length > 0);
+}
+/** 解析初始化等待超时：显式非正整数时回退默认值（不因错误配置阻塞上线）。 */
+export function parseInitWaitMs(value) {
+    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 = process.env) {
+    const required = [
+        'ZAG_HOST_ENDPOINT',
+        'ZAG_HOST_KEY',
+        'ZAG_CONTROLLER_KEY',
+        'ZAG_SERVER_ENDPOINT',
+    ];
+    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),
+    };
+}
+/**
+ * 错误/失败类 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) {
+    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) {
+    return isFailureShutdownReason(reason) ? 1 : 0;
+}
+/** 日志中的连接目标：仅 origin + namespace，绝不包含 query/token。 */
+function describeEndpoint(endpoint) {
+    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 = {}) {
+    const env = readCloudHostEnv(deps.env ?? process.env);
+    const connect = deps.connect ?? connectToServer;
+    const makeDir = deps.makeDir ?? ((path) => mkdir(path, { recursive: true }).then(() => undefined));
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const log = deps.log ?? ((message) => console.log(message));
+    // 初始化脚本/工作负载需要在工作区落地前执行，先幂等创建工作区。
+    await makeDir(env.workspace);
+    log(`[CloudHost] workspace ready: ${env.workspace}`);
+    let controllerSocket = null;
+    let initWaitTimer = null;
+    let waitingForInit = false;
+    let initBatchCompleted = false;
+    let shutdownStarted = false;
+    const clearInitTimer = () => {
+        if (initWaitTimer) {
+            clearTimeout(initWaitTimer);
+            initWaitTimer = null;
+        }
+    };
+    const shutdown = (reason, code) => {
+        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 = () => {
+        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 = () => {
+        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,
+    };
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/cloud-host/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../src/cloud-host/supervisor.ts"],"names":[],"mappings":"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"}

package/dist/cloud-host/supervisor.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=supervisor.test.d.ts.map

package/dist/cloud-host/supervisor.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.test.d.ts","sourceRoot":"","sources":["../../src/cloud-host/supervisor.test.ts"],"names":[],"mappings":""}