super-dsh 0.1.9 → 0.1.10-e

package/agent-claude/dist/sdk-runtime.js

@@ -0,0 +1,320 @@
+/**
+ * sdk-runtime.ts — the lazy, durable Claude Agent SDK runtime (2026-10-04 spec §2.1).
+ *
+ * Zero declared dependency: the FIRST real prompt fetches
+ * `@anthropic-ai/claude-agent-sdk` into <worldHome>/sdk-runtime/ and it stays
+ * durable there. Two modes (user ruling 2026-10-04): host-binary (default,
+ * `--omit=optional` — the 206 MB platform payload is never downloaded; the CLI
+ * is the user's own binary) and bundled-payload (no local binary: the SDK's
+ * own platform payload IS the CLI). A mode flip re-installs with the other
+ * flag set (idempotent heal); a FAILED fetch writes sdk-runtime.error.log and
+ * throws — never a silent degradation.
+ *
+ * Layout (the marker/lock/error-log mechanism is, in shape, the one
+ * `agent-codex-sdk/src/sdk-runtime.ts` runs on):
+ *
+ *   <worldHome>/sdk-runtime/            npm tree (`--ignore-scripts`)
+ *     package.json                 the ANCHOR we write before install
+ *                                  (private, never published): npm otherwise
+ *                                  resolves the nearest ancestor project and
+ *                                  may exit 0 having landed nothing here
+ *     node_modules/@anthropic-ai/claude-agent-sdk/
+ *       sdk.mjs                         the entry `loadClaudeQuery` imports
+ *   <worldHome>/sdk-runtime.json        marker — written LAST; a matching
+ *                                       identity AND a live entry mean complete
+ *   <worldHome>/sdk-runtime.lock        atomic (mkdir) bootstrap lock
+ *   <worldHome>/sdk-runtime.error.log   written ONLY by a failed fetch
+ *
+ * Why the world home rather than the package root: the package root is the
+ * installed tarball — read-only in every real consumer install and shared by
+ * every world — while the world home is per-runtime, writable, and already the
+ * home of this adapter's own DSH state.
+ *
+ * Mode is re-derived on EVERY call: the host binary is resolved again (it may
+ * have appeared or vanished since the fetch), and a marker whose recorded mode
+ * no longer matches re-installs under the other flag set.
+ *
+ * Every path derives from the explicit `worldHome` argument — this module never
+ * reads the ambient `DSH_HOME` — and the SDK entry is imported BY RESOLVED PATH,
+ * never by a bare specifier: the runtime lives in the world home while this
+ * module lives in the plugin tarball, so a bare specifier could not resolve it
+ * and would quietly reintroduce the dependency this module exists to delete.
+ */
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { promisify } from "node:util";
+/** The coding-agent SDK this line drives (a plain npm package, never declared). */
+export const SDK_PACKAGE = "@anthropic-ai/claude-agent-sdk";
+/** The pin, written here rather than in `package.json` — the marker carries it. */
+export const SDK_PACKAGE_VERSION = "0.3.263";
+export function sdkRuntimeLayout(worldHome) {
+    return {
+        dir: join(worldHome, "sdk-runtime"),
+        marker: join(worldHome, "sdk-runtime.json"),
+        lock: join(worldHome, "sdk-runtime.lock"),
+        errorLog: join(worldHome, "sdk-runtime.error.log"),
+    };
+}
+/** The entry `loadClaudeQuery` imports — the SDK's `exports["."]`. */
+export function sdkEntryPath(worldHome) {
+    return join(sdkRuntimeLayout(worldHome).dir, "node_modules", SDK_PACKAGE, "sdk.mjs");
+}
+/** Read the install marker; undefined when absent, unreadable or not our shape. */
+export function readSdkRuntimeRecord(worldHome) {
+    const { marker } = sdkRuntimeLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const record = parsed;
+        if (record.sdkPackage !== SDK_PACKAGE)
+            return undefined;
+        if (typeof record.sdkVersion !== "string")
+            return undefined;
+        if (record.mode !== "host-binary" && record.mode !== "bundled-payload")
+            return undefined;
+        if (typeof record.createdAt !== "number")
+            return undefined;
+        return record;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The fast path: the marker is present, is ours, carries the current pin, was
+ * written under `wantedMode`, AND the SDK entry it promises still exists.
+ *
+ * The marker is written LAST, after a successful install, so its identity match
+ * normally implies the tree underneath; but an identity match alone is not
+ * enough. `fetchRuntime`'s failure path deletes the tree, a user may delete it
+ * by hand, and a half-wiped install can leave the (separate) marker behind. The
+ * entry `existsSync` is therefore the completeness contract: without it a stale
+ * marker would hand back a record whose `sdk.mjs` is gone and every prompt would
+ * fail `ERR_MODULE_NOT_FOUND` until someone removed the marker by hand. One stat
+ * costs nothing next to a 206 MB re-download.
+ */
+function sdkRuntimeReady(worldHome, wantedMode) {
+    const record = readSdkRuntimeRecord(worldHome);
+    if (record === undefined)
+        return undefined;
+    if (record.sdkVersion !== SDK_PACKAGE_VERSION)
+        return undefined;
+    if (record.mode !== wantedMode)
+        return undefined;
+    if (!existsSync(sdkEntryPath(worldHome)))
+        return undefined;
+    return record;
+}
+/**
+ * Resolve the host Claude Code binary, most specific first:
+ * `CLAUDE_EXECUTABLE` (only when it exists) > `claude` on `PATH` >
+ * `~/.local/bin/claude` > `/usr/local/bin/claude`.
+ *
+ * `undefined` means "no local binary" and is the trigger for
+ * `bundled-payload` — never a bare `"claude"` fallback, which would pretend a
+ * host binary exists and make the SDK spawn a name that is not on `PATH`.
+ */
+export function resolveClaudeBinary() {
+    const override = process.env.CLAUDE_EXECUTABLE;
+    if (override && existsSync(override))
+        return override;
+    for (const dir of (process.env.PATH ?? "").split(":").filter(Boolean)) {
+        const candidate = join(dir, "claude");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    for (const candidate of [join(homedir(), ".local/bin/claude"), "/usr/local/bin/claude"]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+/** The npm argv the runtime tree is installed with (kept pure for the test). */
+export function sdkInstallArgv(version, mode) {
+    const argv = [
+        "install",
+        "--exact",
+        "--ignore-scripts",
+        "--omit=dev",
+        "--no-audit",
+        "--no-fund",
+        `${SDK_PACKAGE}@${version}`,
+    ];
+    if (mode === "host-binary")
+        argv.push("--omit=optional");
+    return argv;
+}
+/** A held lock older than this is treated as abandoned and reclaimed. */
+const LOCK_STALE_MS = 10 * 60 * 1000;
+const execFileAsync = promisify(execFile);
+/**
+ * The production `install`: `SUPERD_SDK_NPM` (so the fetch can be pointed at
+ * pnpm/corepack) over an otherwise inherited environment, run in the runtime
+ * dir. `maxBuffer` is raised for npm's progress output.
+ */
+async function defaultInstall(cmd, args, opts) {
+    await execFileAsync(cmd, args, {
+        cwd: opts.cwd,
+        env: opts.env ?? process.env,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+/**
+ * Return the record for `<worldHome>`'s durable SDK runtime, fetching it first
+ * when it is absent, stale or was installed under the other mode.
+ *
+ * Idempotent: a complete, matching runtime short-circuits without touching the
+ * network. Concurrent callers are separated by a `mkdir` lock — a second caller
+ * that finds a FRESH lock fails with a clear "fetch in progress" error (the SDK
+ * handle is a per-process singleton; the real race is another dsh process on
+ * the same world home), while an abandoned lock (older than
+ * {@link LOCK_STALE_MS}) is reclaimed so a crashed fetch cannot brick the line.
+ *
+ * A failure appends to `<worldHome>/sdk-runtime.error.log`, drops the partial
+ * tree and throws one actionable error — never a marker, so the next call heals.
+ */
+export async function ensureSdkRuntime(worldHome, deps) {
+    const install = deps?.install ?? defaultInstall;
+    const now = deps?.now ?? Date.now;
+    const layout = sdkRuntimeLayout(worldHome);
+    const wantedMode = resolveClaudeBinary() !== undefined ? "host-binary" : "bundled-payload";
+    const ready = sdkRuntimeReady(worldHome, wantedMode);
+    if (ready !== undefined)
+        return ready;
+    mkdirSync(worldHome, { recursive: true });
+    acquireLock(layout);
+    try {
+        // Re-check inside the lock: a peer may have completed the fetch in the
+        // window between our check and the lock, in which case we pay nothing.
+        const done = sdkRuntimeReady(worldHome, wantedMode);
+        if (done !== undefined)
+            return done;
+        try {
+            return await fetchRuntime(worldHome, layout, wantedMode, install, now);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            try {
+                appendFileSync(layout.errorLog, `[${new Date().toISOString()}] agent-claude SDK runtime fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            rmSync(layout.dir, { recursive: true, force: true });
+            throw new Error(`agent-claude: could not fetch the SDK runtime ` +
+                `(${SDK_PACKAGE}@${SDK_PACKAGE_VERSION}, ${wantedMode} mode) at ${layout.dir}: ${detail}. ` +
+                `Trace: ${layout.errorLog}`);
+        }
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/** The private manifest that anchors npm to the runtime dir (never published). */
+const RUNTIME_MANIFEST = '{"name":"superd-claude-sdk-runtime","private":true}\n';
+/**
+ * The idempotent install step. npm is anchored to the runtime dir by a private
+ * manifest BEFORE install (without one, npm resolves the nearest ANCESTOR
+ * project and may exit 0 having landed nothing here), and the entry is
+ * verified on disk BEFORE the marker is written — exit 0 alone is not success.
+ */
+async function fetchRuntime(worldHome, layout, mode, install, now) {
+    mkdirSync(layout.dir, { recursive: true });
+    // ANCHOR — npm resolves a tree from the nearest ancestor holding a
+    // package.json; with none in the runtime dir it walks up (on the real
+    // machine: to the repo root), reports "up to date" against THAT project,
+    // exits 0 and lands no tree here — yet the marker used to be written anyway,
+    // so every later loadClaudeQuery failed and each "heal" re-hit the same
+    // no-op install (reproduced twice, 2026-10-04). The private manifest pins
+    // the install to THIS directory; written only when missing or not
+    // byte-exact, so a re-run never rewrites a manifest that is already correct.
+    const manifest = join(layout.dir, "package.json");
+    let manifestExact = false;
+    if (existsSync(manifest)) {
+        try {
+            manifestExact = readFileSync(manifest, "utf8") === RUNTIME_MANIFEST;
+        }
+        catch {
+            manifestExact = false; // unreadable ⇒ treat as absent and re-anchor
+        }
+    }
+    if (!manifestExact)
+        writeFileSync(manifest, RUNTIME_MANIFEST);
+    const npm = process.env.SUPERD_SDK_NPM ?? "npm";
+    await install(npm, sdkInstallArgv(SDK_PACKAGE_VERSION, mode), { cwd: layout.dir });
+    // VERIFY — a zero exit is not success: an unanchored (or no-op) install
+    // resolves without producing the entry. Fail BEFORE the marker — it must
+    // only ever exist with the entry verifiably on disk, or the self-healing
+    // loop never converges. The catch in `ensureSdkRuntime` appends the trace
+    // (the note below names the cause) and wipes this partial tree.
+    const entry = sdkEntryPath(worldHome);
+    if (!existsSync(entry)) {
+        throw new Error(`npm install exited 0 but produced no entry at ${entry} — ` +
+            `the install was not anchored to the runtime dir ` +
+            `(npm likely resolved an ancestor project's tree instead of ${manifest})`);
+    }
+    // Marker LAST — a crash before this point leaves an incomplete runtime that
+    // the next call heals, never a false success.
+    const record = {
+        sdkPackage: SDK_PACKAGE,
+        sdkVersion: SDK_PACKAGE_VERSION,
+        mode,
+        createdAt: now(),
+    };
+    writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+    rmSync(layout.errorLog, { force: true });
+    return record;
+}
+/**
+ * mkdir-based mutex: returns owning the lock, throws when a FRESH lock is held
+ * by someone else, reclaims a lock older than {@link LOCK_STALE_MS}.
+ */
+function acquireLock(layout) {
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        let ageMs;
+        try {
+            ageMs = Date.now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > LOCK_STALE_MS) {
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        throw new Error(`agent-claude: another SDK runtime fetch is already in progress (lock ${layout.lock}). ` +
+            `Retry once it finishes; if no fetch is running, remove that lock directory.`);
+    }
+}
+/**
+ * Ensure the durable runtime and return the installed SDK entry's `query`
+ * function — the ONE function the client's default factory drives, and the only
+ * place a real download/install happens on the lazy path.
+ *
+ * The entry is imported by resolved path (see the header) and its shape is
+ * checked here: a tree that installs but exposes no `query` fails at fetch
+ * time, loud and near the cause, rather than inside the agent's first prompt.
+ */
+export async function loadClaudeQuery(worldHome) {
+    await ensureSdkRuntime(worldHome);
+    const entry = sdkEntryPath(worldHome);
+    const module = (await import(pathToFileURL(entry).href));
+    if (typeof module.query !== "function") {
+        throw new Error(`agent-claude: ${entry} exposes no query function`);
+    }
+    return module.query;
+}

package/agent-claude/package.json

@@ -18,10 +18,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --test test/*.test.mjs"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.263"
+    "test": "node --test test/*.test.mjs",
+    "fetch-sdk-runtime": "node scripts/fetch-sdk-runtime.mjs"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -30,6 +28,7 @@
     "@deepseek-ai/dsh-llm": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-session-persistence": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-user-approval": ">=0.1.5-0 <0.3.0-0",
     "@deepseek-ai/dsh-user-questions": ">=0.1.5-0 <0.3.0-0"
   },
@@ -52,6 +51,9 @@
     "@deepseek-ai/dsh-session-persistence": {
       "optional": true
     },
+    "@deepseek-ai/dsh-typert-protocol": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-user-approval": {
       "optional": true
     },

package/agent-codex/README.md

@@ -1,58 +1,92 @@
 # @pgmi-builds/agent-codex
 
-superd 外壳下的 **Codex adapter**（super-dsh 线，AW-E）：把 Codex CLI 经由
-`@openai/codex-sdk` 接进 DSH —— 会话、事件、模型目录、持久化全部按 DSH 语义呈现，
-WebUI 消费的是 DSH 服务提供的数据面。
+superd 外壳下的 **Codex adapter**（super-dsh 线）：把 Codex CLI 经由 **`codex app-server`**
+接进 DSH —— 会话、事件、模型目录、审批、持久化全部按 DSH 语义呈现，WebUI 消费的是 DSH
+服务提供的数据面。
 
 > 通用规则（定位 / 两形态 / 测试准则 / 接线域 / per-agent 定制权 / home 与 profile 布局）
 > 见上级目录的 `agent-adapter-dev-rules.md` —— 改本包前先读它。
+> 迁移计划与实证：`docs/superpowers/plans/2026-10-03-agent-codex-app-server-migration.md`。
 
 ## 它是什么
 
 - 一个**普通 dsh plugin bundle**：`package.json` 的 `dsh.bundle.patch` 指向本目录的
   `cordis.patch.yml`（挂 codex provider、关掉它替代的原生行、重写权限三档表、pin 应用内目录选择器）。
 - 一个 **AgentFactory**：`src/index.ts` 里的 `CodexProvider` 在 `ctx.agents` 注册工厂，
-  每个会话一个 `CodexSdkClient`（真 `@openai/codex-sdk` 线程）；`src/agent.ts` 把 Codex 线程事件
-  投影成 DSH 会话事件。
-- **不包含** 任何 hub 耦合：世界挂载由 hub 侧驱动（AW-B 用 `@pgmi-builds/superd-hub/world` 的
-  mount carrier）。本包自己就足以点亮一个完整的 web app。
+  **每个会话一个 `codex app-server` 子进程**（`src/app-server-client.ts`）；
+  `src/agent.ts` 把 app-server 通知流投影成 DSH 会话事件。
+- **不包含** 任何 hub 耦合：世界挂载由 hub 侧驱动。本包自己就足以点亮一个完整的 web app。
+
+## 线别（2026-10-03 迁移）
+
+**app-server 线**取代了原 `@openai/codex-sdk` 线（SDK 依赖已从本包与主 pack 移除）。
+SDK 线在 adapter 里登记的一整排降级被 app-server 协议面直接消掉：
+
+| 能力 | SDK 线（已退役） | app-server 线（现役） |
+|---|---|---|
+| 打断 | 只有 AbortSignal（掐断本轮 stream） | **`turn/interrupt`** |
+| steer | 无 → 排队 followUp 近似 | **`turn/steer`**（注入进行中的 turn） |
+| 运行时换模型 | 无 → 下一轮 `resumeThread` | **`turn/start.model`**（下一轮起生效，线程不重建） |
+| 运行时审批档 | 无 → launch-only 预设 | **`turn/start.approvalPolicy`**（折叠 `approval/policy`，`/permission` 可用） |
+| 运行时沙箱档 | 无 → launch-only | **`turn/start.sandboxPolicy`**（折叠 `sandbox/mode`） |
+| 审批人机回路 | 无（`sendRaw` 是 no-op） | **`*/requestApproval` → DSH `ctx.approval`**（Web UI ApprovalPanel） |
+| 用户消息回显 | 无（SDK item 无 `user_message`） | `item/started userMessage` |
+| token usage | 只在本轮 `turn/completed`，滞后 | `thread/tokenUsage/updated`（本轮 `turn_end` 附着） |
+
+**未接（登记 backlog）**：`thread/compact/start`（`/compact` 仍显式拒绝）、
+`thread/list` 会话清单（DSH 日志仍是权威）、`skills/list` / `mcpServerStatus/list` 面板、
+`thread/fork`、`requestUserInput` / `mcpServer/elicitation`（fail-closed 应答）、
+collab/subagent 项。
 
 ## 单独跑起来（首选开发/验收形态）
 
-```bash
-# 在仓根执行；端口默认 4988，LAN 走只绑 LAN IP 的 socat relay
-SUPERD_APP_PORT=4989 bash super-dsh/test/start-codex-app.sh
-# 脚本会打印 loopback / LAN token URL；停止：
-systemctl --user stop superd-codex-app-<port>-test superd-codex-app-<port>-relay
-```
-
-环境变量：`SUPERD_APP_PORT`（端口）、`SUPERD_APP_HOME`（默认 `$WT/.tests`）、
-`SUPERD_LAN_HOST`（默认 `192.168.31.130`）、`CODEX_TRACE=1`（provider/agent 追踪）。
+场景级验证唯一入口 = **整包 pack 线**（`super-dsh/test/start-4999.sh`）+ dev3 目标机实装
+（2026-09-24「场景退役」裁决）；本包不再有 standalone 启动脚本。
 
 ## Home 与 profile 布局（user 裁定）
 
 | 位置 | 内容 |
 |---|---|
 | `$DSH_HOME`（测试 = `<repo>/.tests`） | 测试 DSH home |
-| `$DSH_HOME/agents/codex` | **Codex app home**：`config.toml` / `auth.json` / 模型 catalog（standalone 时代的 `setup-codex-home.mjs` 拷入已随 2026-09-24 场景退役删除）+ Codex 自己的 rollout/state |
-| `$DSH_HOME/profiles/codex` | 本 app 的 dsh profile（bundles + `cordis.patch.yml`） |
-| `$DSH_HOME/sessions/...` | **DSH 会话日志**（上游 `session-persistence-jsonl`，zstd）——list/replay 都由此提供 |
-
-**禁止**自造 per-app home（如 `.tests/codex-app`）。
+| 原生 `~/.codex`（`CODEX_HOME` 才重定向） | **Codex 原生 app home**：`config.toml` / `auth.json` / 模型 catalog / rollout / state。adapter **绝不重定向**（红线 §5），**从不写入**（单向阀） |
+| `$DSH_HOME/agents/codex` | 该 world 的 **DSH home**：DSH 会话日志副本、storages、`dsh-sessions.json` 映射 |
+| `$DSH_HOME/profiles/superd-pub` | 整包线的 dsh profile（tarball 物理安装） |
 
 ## 关键实现点
 
-- **session 身份 = 一对一映射**：DSH session id 是权威；Codex thread id 在其物化后写入
-  `<codexHome>/dsh-sessions.json`（`src/session-map.ts`）。resume 只经该映射重挂线程，查不到即
-  fail-closed。**不自建 rollout 扫描做 list，也不自解析 JSONL 做 replay。**
+- **lazy spawn（硬门）**：`CodexAppServerClient.create()` 零 IO、零子进程；`ensureStarted()`
+  在**首个真实 prompt** 才 spawn + `initialize` + `thread/start|resume`。查看/创建/resume
+  一个会话不产生任何 native 进程。单测直接钉住这条不变量（transport factory 调用计数 = 0）。
+- **进程回收**：子进程 `detached: true`（自有进程组），close 时先 `SIGTERM` 进程组、
+  宽限后 `SIGKILL`，再 `child.kill()` 兜底——stdio MCP 后代 `setsid` 逃离时仍能被扫到。
+- **session 身份 = 一对一映射**：DSH session id 是权威；Codex thread id 在**线程 attach**
+  时经 `onThreadAttached` 写入 `<dshHome>/dsh-sessions.json`（`src/session-map.ts`）。
+  resume 只经该映射重挂线程，查不到即 fail-closed。
 - **DSH-native 持久化**：工厂按上游 agent-loop 的方式持有写通道（create `persistence.create` /
   resume `persistence.open(id,'write')` → `read` → `interruptedTurnClosers` → `prepare`），
   发布点刷未存后缀，dispose 时 `handle.close()` 排空。
-- **每会话路由钉住**：工厂在 create/resume 时同步钉住本会话路由（追加 `model/selection` +
-  `installModelSelection`），**不依赖全局默认模型的落盘时序**（共享 test home 里 settings 默认可能属别线）。
-- **事件映射**：`system/message`（Codex 系统提示，rollout HEAD `base_instructions`）、
-  `request/context`（provider/model/contextWindow）、`assistant/message`（reasoning 用
-  `{type:'reasoning',text}`）、`tool/call`（原始 JSON 串）/`tool/result`、`step/start|end`、`turn/start|end`。
+- **每会话路由钉住**：create/resume 时同步钉住本会话路由（追加 `model/selection` +
+  `installModelSelection`），**不依赖全局默认模型的落盘时序**。
+- **每轮权限折叠**：`agent.ts` 在每次 `turn/start` 前把会话日志的
+  `approval/policy` / `sandbox/mode`（无则由 preset 表兜底）折成 codex 覆盖
+  （`permission.ts` 的 `turnPolicyFromEvents`）；`CODEX_APPROVAL_MODE` 只覆盖审批半边。
+- **审批桥 fail-closed**：`app-server-approvals.ts` 把 server-request 映射到
+  `ctx.approval.request()`；无 answerer / 抛错 / 超时（`CODEX_APPROVAL_TIMEOUT_MS`，默认 5 分钟）
+  一律 **decline**，绝不让 codex 挂死。
+- **事件映射**：`system/message`（rollout HEAD `base_instructions`）、`request/context`、
+  `assistant/message`（reasoning 用 `{type:'reasoning',text}`）、
+  `tool/call`（原始 JSON 串）/`tool/result`、`step/start|end`、`turn/start|end`、`todo/write`。
+
+## 环境变量
+
+| 变量 | 作用 |
+|---|---|
+| `CODEX_TRACE=1` | provider/agent/app-server 追踪（stderr） |
+| `CODEX_BIN` | 覆盖 codex 入口脚本（测试）；默认 = 本包 pin 的 `@openai/codex/bin/codex.js` |
+| `CODEX_HOME` | Codex 原生 home 重定向（**测试专用**；生产路径零重定向） |
+| `CODEX_APPROVAL_MODE` | 覆盖审批档（`never`/`on-request`/`on-failure`/`untrusted`；非法值忽略） |
+| `CODEX_APPROVAL_TIMEOUT_MS` | 审批应答超时；`0` 关闭；默认 300000 |
+| `CODEX_IDLE_EXIT_MS` | 会话空闲后拆客户端；`0` 关闭；默认 600000 |
 
 ## 测试
 
@@ -63,12 +97,83 @@ SUPERD_DSH_ANCHOR=<repo>/upstream/deepseek-harness/package.json \
 node --test test/*.test.mjs
 ```
 
-live 门控：`SUPERD_CODEX_LIVE=1`（会真跑一次 Codex turn）。
+单测全部是 fake：`test/fixtures/fake-app-server.mjs` 是一个**可编程的 app-server 替身**
+（真 JSONL JSON-RPC 分帧、真子进程），wire / client 测试用真管道驱动它；投影器与审批桥是纯函数。
+**不 spawn 真 codex、不打模型。**
+
+## 已知边界（app-server 线 v1）
 
-## 已知边界（V1）
+- `thread/compact/start` 未接 → `/compact` 仍以显式错误拒绝；
+- 会话清单仍由 DSH 日志提供（不接 `thread/list`，遵守 mapping-only）；
+- `requestUserInput` / `mcpServer/elicitation` / `permissions/requestApproval` 一律 fail-closed；
+- collab / subagent / `thread/fork` / skills / MCP 面板未接；
+- 内存镜像 `getMessages()` 仅供诊断，权威转录是 DSH 会话日志。
 
-- 审批仅 launch-only 预设（SDK 无运行时审批；app-server 线才有 `*/requestApproval`）；
-- 无 steer / 无运行时换模型（下一轮生效）/ usage 滞后一轮 / 无 fork；
-- `compaction/*`、`todo/write`、`subagent/*` 未接（见规则文档 §9.4 backlog）；
-- **AW-B world 挂载移植**：本包已无 world-plugin；若要在 AW-B 的 mount carrier 下作为世界被挂载，
-  由 hub 侧驱动（移植为跟踪项）。
+## 多 provider 面（Hub + DSH，2026-10-04 重做）
+
+Codex 是**单 provider** harness：它自己的 `config.toml` 只能写一个 `model_provider`。provider 的**清单**
+在 Codex 家里无处安放——那正是 cc-switch 存在的理由；而「这个会话现在跑在哪个 provider 上」在 DSH
+里已有公认答案（`session/selectModel` + 持久的 `model/selection`）。所以本线**只做清单**，选择交给 DSH：
+
+- adapter 的 store 是**正本**（canonical），原生 `config.toml` 是**来源**（source），单向读入；
+- UI 不再有「active provider」概念——界面里切换 provider/model 就是 DSH 自带模型选择器，与本仓其它
+  harness 完全一致；
+- provider 由**进程参数**注入子进程（`-c model_providers.<id>.*`），**不写任何原生文件**。
+
+### 分账
+
+| 位置 | 内容 |
+|---|---|
+| `$DSH_HOME/agents/codex/codex-providers.json`（0600） | **正本**：provider 清单 + 被显式删除的 endpoint 墓碑（含 API key） |
+| `$DSH_HOME/agents/codex/codex-catalogs/<id>.json` | 本 adapter 自有的 per-provider 模型目录；经 `-c model_catalog_json=<绝对路径>` 注入 |
+| `~/.codex/config.toml` | 用户原生：**只读**。启动时 + 每 10 分钟读一次，按 endpoint URL 去重折进正本 |
+| `~/.codex/auth.json` | 用户原生：**只读**。`apiKey` 形态的 key 走子进程环境，不走这里 |
+
+### 同步（2026-10-04 user 裁决）
+
+`syncFromNative()`：启动时 + 每 10 分钟（`SYNC_INTERVAL_MS = 600_000`）读 `config.toml` 的**全部**
+`[model_providers.<id>]` 表，按 endpoint URL 去重折进正本。新 endpoint 在库里没有名字，**就用 URL 端点
+当名字**（`label = baseUrl`）——Codex 的 catalog 是「当前在役 provider」专用的，所以非在役 provider 的
+模型清单**确实无从得知**，此时存 `models: []`（面板显示「no models yet」，该 provider 不注册路由），
+而不是编一个。同步只**增/刷**、永不删；唯一的例外是用户显式删除留下的**墓碑**（endpoint key），
+否则「删除」会在十分钟后自己撤销。
+
+### 选择与切换
+
+- **路由 = DSH 的**：每个有模型的 provider 注册一条 `ctx.llm` 路由，于是 `session/modelCatalog` 天然
+  按 provider 分组，`session/selectModel` 天然持久（`model/selection` + `modelSelection` 投影）；
+- **turn 边界判定 = DSH 的**：agent 每轮按 `pending ?? request/header ?? agentDefaultModel ?? options`
+  解析路由（`codex-route.ts`），并回写 `request/header`——于是投影的 `lastUsed`/`next`、
+  `consumeSelection`、以及「会话上次跑在哪个 provider」全部由上游自洽，UI 重放自然准确；
+- **中途切换不用打断**：`turn/start` 的 `model` 覆盖「本轮及后续轮」，所以换**模型**是原生的；换
+  **provider** 必须换子进程——`turn/start` 没有 provider 字段，而打给**已加载**线程的 `thread/resume`
+  是「接受但忽略」（2026-10-03 实测：要 `zhipu-cn` 回 `deepseek`）。故 agent 在**下一轮冷启动**时
+  kill 掉旧 child、用新 `-c` 起新 child、`thread/resume` **同一个 thread id**，历史与上下文完整保留。
+  turn 中发起的切换落在下一轮（DSH 的 pending 语义），**不打断在跑的 turn**。
+
+### 启动注入（零原生写入）
+
+`codex-launch.ts` 生成 argv/env；三条实测约束写死在注释里：
+
+1. hyphenated id 在 `-c` 点路径里合法（`model_providers.zhipu-cn.…`）⇒ 原生表名可原样作 provider id；
+2. `model_catalog_json` 作为 override 时按**进程 cwd** 解析 ⇒ 路径必须绝对（相对路径实测 `ENOENT`）；
+3. `env_key` 是唯一不经过 auth manager 的形态 ⇒ 库里的 key 以合成变量名（`SUPERD_CODEX_KEY_<ID>`）
+   经**子进程环境**交给 codex，`auth.json` 完全不碰。**这也顺带解决了 ChatGPT 登录遮蔽 keyed provider
+   的老问题**（`requires_openai_auth` 才会被 `auth_mode=chatgpt` 遮蔽）；只有「seeded」形态
+   （`apiKey` 且 value 为空 = key 在 auth.json 里）才回落到 `requires_openai_auth`，面板仍会告警。
+
+### RPC
+
+`TypertRemoteService`，namespace `codexProviders`（hub 经 `/hub/api?agent=codex` 原样转发）：
+`get` / `save` / `remove`。**API key 只写不读**——wire 上只有 `hasKey`，绝不回传值。
+没有 `select`：选择是 DSH 的 per-session 状态。
+
+### 模型目录必须克隆模板
+
+codex 0.154 对 catalog 条目要求 `slug`/`display_name`/`supported_reasoning_levels`/`shell_type`/
+`visibility`/`supported_in_api`/`priority`/`support_verbosity` 以及**嵌套 struct** `truncation_policy`…
+字段链未终止，故只从既有条目克隆并覆盖身份字段。目录是**替换式**：一份目录只写它那个 provider 的模型
+（2026-10-03 修正：早期「吸收且永不丢弃」让 Chat 模型清单只增不减）。
+
+记录：`docs/superpowers/plans/2026-10-03-codex-multi-provider-hub.md` +
+`docs/test-reports/2026-10-04-codex-multi-provider-onthefly.md`。

package/agent-codex/cordis.patch.yml

@@ -1,4 +1,4 @@
-# @pgmi-builds/agent-codex bundle patch (SDK line, standalone form).
+# @pgmi-builds/agent-codex bundle patch (app-server line, standalone form).
 # This file is the `dsh.bundle.patch` layer of the adapter package: when the
 # codex world profile mounts the bundle, the boot merges THIS patch — mount
 # the Codex provider plus disable the native components it replaces.
@@ -8,16 +8,17 @@
 # fixture carries the 127.0.0.1:0 listener posture).
 
 # Mount the Codex provider: a Cordis Service that registers an AgentFactory
-# on ctx.agents. The provider drives @openai/codex-sdk threads (one
-# CodexSdkClient per session) plus resume (--resume-thread); the model
-# selector is served by a Codex-backed LlmAdapter reading the codex home's
-# config.toml + model_catalog_json.
+# on ctx.agents. The provider drives one `codex app-server` child per session
+# (stdio JSONL JSON-RPC; CodexAppServerClient, spawned lazily on the first
+# prompt) plus thread resume by id; the model selector is served by a
+# Codex-backed LlmAdapter reading the codex home's config.toml +
+# model_catalog_json.
 - insert:
     - id: codex-provider
       name: '@pgmi-builds/agent-codex'
 
 # Codex owns the live agent transcript (the rollout JSONL); disable the
-# built-in loop so it does not double-run alongside the SDK thread.
+# built-in loop so it does not double-run alongside the app-server thread.
 - id: agent-loop
   disabled: true
 
@@ -29,7 +30,7 @@
 - id: llm-pi-ai
   disabled: true
 
-# Codex is single-mode: the SDK thread drives tools itself, so no Dash preset
+# Codex is single-mode: the app-server thread drives tools itself, so no Dash preset
 # composition is needed (the provider ships the fixed single-preset roster).
 # 0.1.7: the host AgentPresetRegistry row (renamed `agent-presets` ->
 # `agent-preset-registry`) stays MOUNTED — the adapter registers its one
@@ -43,9 +44,12 @@
 # list/read/replay/workspace grouping are ordinary DSH services over that log.
 # The adapter no longer provides its own persistence.
 
-# Codex has no runtime approval control — the adapter maps the preset onto
-# the launch-only --approval-mode flag (3:3 table in src/permission.ts).
-# Default to danger-full-access. Restate the full 3-preset table: a patch
+# The app-server line DOES have runtime approval control: the adapter folds
+# `approval/policy` + `sandbox/mode` from the session log into the
+# `turn/start` per-turn overrides (src/permission.ts turnPolicyFromEvents),
+# so `/permission` is live. This table still supplies the LAUNCH posture and
+# the fold's fallback. Default to danger-full-access. Restate the full
+# 3-preset table: a patch
 # with only defaultPreset silently drops the bundle's 3-preset table to the
 # plugin's built-in 2, breaking the 3:3 Dash<->Codex pairing.
 - id: permission