super-dsh 0.1.6 → 0.1.10

package/agent-agy-sdk/dist/sdk-venv.js

@@ -0,0 +1,173 @@
+/**
+ * sdk-venv.ts — the lazy, durable Python venv the SDK bridge runs on.
+ *
+ * 2026-10-02 user ruling (spec §4.2): this package declares NO Python
+ * dependency and ships NO postinstall/allow-scripts hook. Nothing is fetched at
+ * install time; the FIRST real use fetches the venv into the world home, where
+ * it is durable across sessions, restarts and package upgrades. A second use
+ * reuses it (idempotent), and a FAILED fetch leaves a trace on disk instead of
+ * silently degrading into a confusing bridge crash.
+ *
+ * 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 (the CLI one included). The world home is per-runtime, writable,
+ * and already the home of this adapter's own state.
+ *
+ * The bootstrap is two idempotent steps, so a half-built venv heals in place
+ * rather than being thrown away and re-downloaded:
+ *   1. `<worldHome>/sdk-venv/bin/python` missing → `python3 -m venv <dir>`
+ *   2. `<worldHome>/sdk-venv.json` marker missing → `pip install google-antigravity`
+ */
+import { execFileSync } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The Python distribution the bridge imports (`bridge/agy_bridge.py`). */
+export const SDK_PYTHON_PACKAGE = "google-antigravity";
+export function sdkVenvLayout(worldHome) {
+    const dir = join(worldHome, "sdk-venv");
+    return {
+        dir,
+        python: join(dir, "bin", "python"),
+        pip: join(dir, "bin", "pip"),
+        marker: join(worldHome, "sdk-venv.json"),
+        errorLog: join(worldHome, "sdk-venv.error.log"),
+        lock: join(worldHome, "sdk-venv.lock"),
+    };
+}
+/** Read the install marker; undefined when absent or unreadable. */
+export function readSdkVenvRecord(worldHome) {
+    const { marker } = sdkVenvLayout(worldHome);
+    if (!existsSync(marker))
+        return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(marker, "utf8"));
+        return typeof parsed === "object" && parsed !== null ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Fast path: the complete venv already exists → the interpreter to use. */
+export function resolveSdkPython(worldHome) {
+    const layout = sdkVenvLayout(worldHome);
+    return existsSync(layout.python) && existsSync(layout.marker) ? layout.python : undefined;
+}
+const DEFAULTS = {
+    basePython: "python3",
+    lockTimeoutMs: 30 * 60 * 1000,
+    lockPollMs: 1000,
+    lockStaleMs: 30 * 60 * 1000,
+};
+function defaultRun(cmd, args) {
+    execFileSync(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+}
+/**
+ * Return the interpreter path for `<worldHome>`'s durable venv, fetching it
+ * first when it is absent or incomplete.
+ *
+ * Idempotent: a complete venv short-circuits without touching the network.
+ * Failures append to `<worldHome>/sdk-venv.error.log` and throw a single
+ * actionable error — never a partial venv left behind a success marker.
+ */
+export async function ensureSdkVenv(worldHome, opts = {}) {
+    const layout = sdkVenvLayout(worldHome);
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const run = opts.run ?? defaultRun;
+    const ready = resolveSdkPython(worldHome);
+    if (ready !== undefined)
+        return ready;
+    mkdirSync(worldHome, { recursive: true });
+    // `acquired === false` means a peer finished the fetch while we waited: the
+    // lock is not ours and MUST NOT be released by this caller.
+    const acquired = await acquireLock(worldHome, layout, now, sleep, opts);
+    if (!acquired)
+        return layout.python;
+    try {
+        // Re-check inside the lock: a concurrent bootstrap may have finished while
+        // we waited, in which case this caller pays nothing.
+        const done = resolveSdkPython(worldHome);
+        if (done !== undefined)
+            return done;
+        const basePython = opts.basePython ?? process.env.AGY_SDK_BASE_PYTHON ?? DEFAULTS.basePython;
+        const stale = existsSync(layout.python);
+        try {
+            opts.trace?.(`sdk-venv: fetching ${SDK_PYTHON_PACKAGE} into ${layout.dir}`);
+            if (!stale)
+                run(basePython, ["-m", "venv", layout.dir]);
+            run(layout.pip, ["install", "-q", SDK_PYTHON_PACKAGE]);
+            if (!existsSync(layout.python)) {
+                throw new Error(`venv created but ${layout.python} is missing`);
+            }
+            const record = {
+                package: SDK_PYTHON_PACKAGE,
+                python: layout.python,
+                installedAt: new Date(now()).toISOString(),
+                createdWith: basePython,
+            };
+            writeFileSync(layout.marker, JSON.stringify(record, null, 2) + "\n");
+            rmSync(layout.errorLog, { force: true });
+            opts.trace?.(`sdk-venv: ready (${layout.python})`);
+            return layout.python;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            const stamp = new Date(now()).toISOString();
+            try {
+                appendFileSync(layout.errorLog, `[${stamp}] ${SDK_PYTHON_PACKAGE} fetch failed: ${detail}\n`);
+            }
+            catch {
+                /* the trace is best-effort; the throw below is the contract */
+            }
+            throw new Error(`agy-sdk: could not fetch the Python SDK venv (${SDK_PYTHON_PACKAGE}) at ${layout.dir}: ${detail}. ` +
+                `Install it by hand with \`npm run fetch-venv\` (or set AGY_PYTHON to an interpreter that has it). ` +
+                `Trace: ${layout.errorLog}`);
+        }
+    }
+    finally {
+        rmSync(layout.lock, { recursive: true, force: true });
+    }
+}
+/**
+ * mkdir-based mutex with stale-lock reclamation.
+ *
+ * Resolves `true` when THIS caller owns the lock (and must release it), `false`
+ * when a peer completed the fetch while we waited (nothing to release, the
+ * venv is ready). Throws when the wait budget is exhausted.
+ */
+async function acquireLock(worldHome, layout, now, sleep, opts) {
+    const timeout = opts.lockTimeoutMs ?? DEFAULTS.lockTimeoutMs;
+    const poll = opts.lockPollMs ?? DEFAULTS.lockPollMs;
+    const staleMs = opts.lockStaleMs ?? DEFAULTS.lockStaleMs;
+    const deadline = now() + timeout;
+    for (;;) {
+        try {
+            mkdirSync(layout.lock);
+            return true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        // Someone holds it. Another process may have finished the fetch already.
+        if (resolveSdkPython(worldHome) !== undefined)
+            return false;
+        let ageMs = 0;
+        try {
+            ageMs = now() - statSync(layout.lock).mtimeMs;
+        }
+        catch {
+            continue; // released between the mkdir attempt and the stat — retry now
+        }
+        if (ageMs > staleMs) {
+            opts.trace?.(`sdk-venv: stealing stale lock (age ${Math.round(ageMs / 1000)}s)`);
+            rmSync(layout.lock, { recursive: true, force: true });
+            continue;
+        }
+        if (now() >= deadline) {
+            throw new Error(`agy-sdk: timed out waiting for a concurrent SDK venv fetch (lock ${layout.lock}). ` +
+                `Remove the lock directory if no fetch is running.`);
+        }
+        await sleep(poll);
+    }
+}

package/agent-agy-sdk/dist/world-plugin.d.ts

@@ -0,0 +1,10 @@
+export declare const name = "agent-agy-sdk";
+/** Structural slice of the ctx0 services the mount needs. */
+interface HostContext {
+    provide(name: string, value: unknown): void;
+    inject(deps: string[], callback: (ctx: unknown) => void): unknown;
+    effect?(callback: () => () => void, label?: string): unknown;
+    get(name: string): unknown;
+}
+export declare function apply(ctx: HostContext): void;
+export {};

package/agent-agy-sdk/dist/world-plugin.js

@@ -0,0 +1,82 @@
+/**
+ * agent-agy — the Antigravity (agy) adapter's WORLD plugin (spec S2):
+ * activation IS roster membership.
+ *
+ * AW-B data-plane shape (DL1–DL5 → path-separation T-D), mirroring
+ * `@pgmi-builds/agent-omp/world` and `@pgmi-builds/agent-codex/world` so the
+ * hub sees every foreign runtime through one shape: the world is spawned as a
+ * sibling ROOT context with NO listener and NO webui composition
+ * (`worldMountPatches`) — a pure data plane behind the hub's `/hub` family.
+ *
+ *   1. ctx0 publishes the host mount record (the world's addressability
+ *      entry — no webServer, no fence: those legs retired with the world
+ *      pages) before spawn;
+ *   2. the world's entry row provides the virtual `webServer` (a silent
+ *      sink) plus the neutral `webRuntime` facts its connection row injects;
+ *   3. the hub's `/hub` family answers `?agent=agy` traffic in ctx0's auth
+ *      domain and dispatches into this world's gateway instance (the
+ *      per-label `/<label>/api` + `/<label>/api/remote.mux` mounts retired
+ *      in T-C, `mountWorld` deleted in T-D).
+ */
+import { mkdirSync } from 'node:fs';
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths';
+import { join } from 'node:path';
+import { spawnWorld, registerAgent, setReady, registerForeignTarget, registerHostMount, worldMountPatches, provisionWorldProfile, resolveInstallAnchor, } from '../../superd-hub/dist/index.js';
+export const name = 'agent-agy-sdk';
+/**
+ * Runtime key — also the mount label. Deliberately NOT `agy`: the hub's roster
+ * (registerAgent) hard-throws on a duplicate key, and this row ships alongside
+ * the CLI row in the same composite. Distinct keys keep both independently
+ * toggleable and make the "both enabled" mistake survivable.
+ */
+const KEY = 'agy-sdk';
+export function apply(ctx) {
+    registerAgent({ key: KEY, label: 'Antigravity (SDK)', ready: false });
+    // Harness resolver (env → ~/.dsh): a consumer install has no DSH_HOME and
+    // no cwd contract — deriving the world root from cwd spawns worlds into a
+    // garbage tree or throws inside apply() and kills the whole host boot.
+    const root = resolveDshHome();
+    // Nested home: the world's DSH data lives INSIDE `agents/<label>` (sessions
+    // / settings / workspaces, and the adapter's dsh-sessions.json mapping).
+    // agy-sdk: the world home carries the DSH-side state AND the lazily fetched
+    // durable Python venv (sdk-venv.ts); nothing is nested for the SDK itself.
+    const worldHome = join(root, 'agents', KEY);
+    mkdirSync(join(worldHome, 'profiles'), { recursive: true });
+    // Publish story: a foreign install has no line bootstrap, so the nested
+    // profile + @pgmi-builds links are provisioned HERE (idempotent).
+    provisionWorldProfile({
+        key: KEY,
+        adapterPkg: '@pgmi-builds/agent-agy-sdk',
+        worldHome,
+    });
+    const world = (async () => {
+        // T-D: no ctx0 listening-stack wait — the mount record is addressability
+        // only and the /hub family wires its own gate in ctx0 (gateway.ts).
+        const dropHostMount = registerHostMount({ key: KEY, labelPath: `/${KEY}` });
+        const ctxW = await spawnWorld({
+            appName: `superd-${KEY}`,
+            profileName: 'web',
+            installAnchor: resolveInstallAnchor(ctx), // lazy: never at module scope — import must stay side-effect-free
+            home: worldHome,
+            dataHome: worldHome,
+            // The host's live table carries this world: spawnWorld republishes a
+            // widened successor before boot imports anything (spec §2.1), and
+            // @pgmi-builds rows resolve from the profile-local links written above.
+            host: ctx,
+            extraPatches: worldMountPatches(KEY),
+        });
+        const gateway = ctxW.get('typertGateway');
+        registerForeignTarget({ key: KEY, gateway });
+        setReady(KEY, true);
+        ctx.effect?.(() => () => {
+            dropHostMount();
+        }, `agent-${KEY}: mount`);
+        return ctxW;
+    })().catch((cause) => {
+        // A failed world degrades to a not-ready roster row; a rejected provided
+        // promise would fail the entire host boot (loader entry apply).
+        console.error(`[super-dsh] ${KEY} world failed:`, cause);
+        return null;
+    });
+    ctx.provide(`superd.world.${KEY}`, world);
+}

package/agent-agy-sdk/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@pgmi-builds/agent-agy-sdk",
+  "version": "0.1.0",
+  "description": "Google Antigravity (Gemini) provider for DeepSeek Harness (dsh) — the OPT-IN SDK transport: drives the google-antigravity Python SDK through a JSONL stdio bridge (bridge/agy_bridge.py, localharness embedded). Auth: adapter-side/GEMINI_API_KEY key, else Vertex over ADC. The agy CLI is never invoked — that is @pgmi-builds/agent-agy. Delivered DISABLED by default (roster key `agy-sdk`): the CLI adapter is the primary path because it reuses the user's existing Antigravity environment. No Python dependency is declared anywhere and there is no postinstall/allow-scripts hook — the durable venv is fetched into the world home on first real use (src/sdk-venv.ts, `npm run fetch-venv`).",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./world": "./dist/world-plugin.js"
+  },
+  "files": [
+    "dist",
+    "bridge",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.mjs",
+    "fetch-venv": "node scripts/fetch-venv.mjs"
+  },
+  "dependencies": {
+    "zod": "3.25.76"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.5-0 <0.3.0-0",
+    "@deepseek-ai/dsh-scope": ">=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"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-agent": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-llm": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-scope": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-persistence": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "dist/index.js"
+}

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