super-dsh 0.1.11 → 0.1.12

package/agent-hermes/README.md

@@ -1,145 +0,0 @@
-# @pgmi-builds/agent-hermes
-
-Hermes provider for DeepSeek Harness (dsh) — an AgentFactory that embeds the
-Nous Research Hermes Agent via the TUI gateway JSON-RPC (`python -m
-tui_gateway.entry`) and bridges its session surface into Dash Agent/Session
-contracts (Super D; parity round 2026-09-17 = Task M1 of
-`docs/superpowers/plans/2026-09-17-superd-five-adapter-parity-fixes.md`).
-
-## Layout
-
-- `src/models.ts` — gateway `model.options` → Dash model catalog (trim rules,
-  r4 id dedupe, provider-name cache, slug list). Pure + fail-soft.
-- `src/adapter.ts` — `HermesLlmAdapter`: one route per real gateway provider
-  slug; `providerInfo` display names; ids stay verbatim selection strings.
-- `src/index.ts` — `HermesProvider` (AgentFactory): creation transaction,
-  boot route registration + atomic swap, default-model push, session map.
-- `src/agent.ts` — `HermesAgent`: wire→DSH event bridge, usage conversion,
-  turn-error classification, resume self-heal, title/todo mirroring.
-- `src/hermes-events.ts` — PURE gateway-event → omp-wire projector.
-- `src/hermes-client.ts` — one client = one gateway child = one session
-  (spawn/env/ready/turn-settle/approval bridge; liveness getters; adoption
-  listener; opt-in idle-probe reaper).
-- `src/hermes-store.ts` — `<dshHome>/agents/hermes/dsh-sessions.json` map.
-- `test/` — imports `dist/`; build first (`npm run build`), then
-  `node --test test/*.test.mjs`. The world-plugin smoke needs the repo farm:
-  run with `DSH_HOME=<repo>/.tests` (it refuses prod homes).
-
-## Per-adapter rulings (2026-09-17 M1; recorded per dev-rules §4/§12)
-
-1. **Model grouping by real provider slug** (RC-3 fix). Boot registers the
-   single placeholder route `hermes` (the selector stays alive while the async
-   probe runs); when the first `model.options` probe resolves, the
-   registration atomically swaps to the DISTINCT surviving provider slugs
-   (`AdapterRegistrationHandle.replace` — validated in full, one synchronous
-   section). `listModels(provider)` filters by the entry's own `provider`;
-   `resolveModel` matches the (provider, id) pair. Model ids are NEVER
-   reformatted: they are the gateway's verbatim selection strings
-   (`session.create {model}` / `/model <id>` consume them as-is — wire
-   contract). The default-model push and the per-session route pin
-   (`model/selection`, `request/context`) carry `{provider: slug, model: id}`,
-   canonicalized through the catalog entry (the r4 dedupe gives every id ONE
-   provider route, so a pinned route always resolves).
-2. **Catalog trims** (the "579-model wall" fix), applied at mapping time in
-   `mapHermesModelOptions`:
-   - `source: "virtual"` rows drop (the `moa` synthesizer is not a selectable
-     endpoint);
-   - mirrored endpoints with IDENTICAL model-id sets collapse onto one row —
-     first in gateway order wins, except a later `is_current` mirror displaces
-     a non-current winner (fixture: `copilot`/`copilot-acp`,
-     `zai-plan`/`zhipu`; 17 providers → 14 groups, 579 → 526 listed ids);
-   - endpoints with MORE than 50 models reorder `featured_models` first
-     (gateway order), remainder alphabetically; smaller rows keep gateway
-     order (the 47-model openrouter row is untouched).
-   The `authenticated !== true` filter predates this ruling and is unchanged.
-3. **Cross-provider id dedupe stays (r4)**: an id listed under several slugs
-   keeps ONE canonical route (first surviving row, current-row preferred).
-   Rationale: the wire sends only the model id, so a duplicate listing would
-   fabricate provider-specific selection the gateway cannot honor; canonical
-   routes keep every pinned route resolvable. Consequence: multi-homed ids
-   (e.g. `kimi-k3` under copilot/qwen-cn/kimi-cn) list under their canonical
-   route only.
-4. **`todo/write`** (typed transcript): the gateway's whole-list
-   `todo.updated {todos, revision}` snapshot → wire `todo_updated` (projector;
-   DSH-shaped items: trimmed content, status ∈ {pending, in_progress,
-   completed}; `cancelled`/unknown statuses and duplicate/blank content drop —
-   the DSH `todo/write` invariant has no cancelled status and forbids
-   repeats) → the agent appends the log-only `todo/write {todos}` snapshot,
-   only inside an open turn (upstream invariant), latest-wins. Log-only
-   semantics kept (upstream `tool-todo` contract); the todo tool pair still
-   renders through `tool_execution_*` as before.
-5. **`session/title` mirror**: gateway `session.title {session_id, title}` →
-   wire `session_title` (pi wire parity) → `session/title
-   {title, messageSeqs: [], source:{kind:"provider", provider:"hermes"}}`,
-   deduped, fail-soft, never affects the turn. The client-side `session.info`
-   title capture stays (feeds `session.create`'s title + tracing).
-6. **Turn usage** (RC-6 fix). Fixture verdict (`gateway-events.sample.json`
-   index 13): the gateway's `total` is CONTEXT-WIDE, not per-message —
-   `total 26805 = prompt 26803 + completion 2` and `prompt === context_used`
-   (the whole re-sent window), so trusting it would inflate every turn.
-   `convertUsage` therefore synthesizes the per-attempt-provable
-   `totalTokens = inputTokens + outputTokens` (fixture: 19251 + 2 = 19253),
-   which the DSH token-meter fold accepts (`normalizeUsage` needs `totalTokens`
-   or BOTH cache buckets; the gateway shape has none — the pre-fix sample
-   folded to `undefined` every turn). `reasoningTokens` rides only when
-   `reasoning ≤ output` (Dash: reasoning ⊆ output; the fold rejects larger
-   values). No cache tokens are invented (the gateway reports none —
-   `cache_hit_pct` is a percentage).
-7. **Resume self-heal over lazy spawn** (RC-4 fix, ruling 4 of the plan; full
-   lazy spawn deferred):
-   - The client exposes `usable` / `closed` / `failure` liveness getters.
-   - On a CLIENT-TERMINAL failure (child exit, ready timeout, close — the
-     client's `usable` is false) the agent's failure path — and the cold-start
-     path — triggers the full idle-exit dispose (`#onIdleExit`), so the host
-     unregisters the dead agent and re-resumes a FRESH client on the next
-     prompt. Ordinary per-turn failures never dispose.
-   - The spawn-grace reaper is now OPT-IN (`spawn({spawnGraceMs})`) and only
-     the self-closing catalog-probe client arms it (env
-     `HERMES_SPAWN_GRACE_MS`, default 10 min, `0` disables). AGENT-HELD
-     clients never arm it: a view-time eager resume may legitimately sit
-     unprompted far beyond any grace, and reaping it stamped the terminal
-     "hermes gateway client closed" failure that wedged every later prompt
-     (the reported wedge). Accepted trade-off until full lazy spawn lands: a
-     resumed-but-never-prompted session pins its gateway child until the host
-     disposes the agent (session close / owner unload).
-   - Turn errors are CLASSIFIED instead of a bare UNKNOWN:
-     `GatewayRpcError` 4001/4006 → `NATIVE_SESSION_GONE` (message names the
-     stored gateway session), gateway child exit/error → `GATEWAY_CRASH`,
-     dead client → `CLIENT_CLOSED`. The code renders in the Web UI error chip
-     (`turn/end {kind:"error", error:{message, code}}`).
-   - `stored_session_id` DRIFT tolerance: adoption
-     (session.create/resume response) fires the client's `onAdopted` listener;
-     the provider's map upsert always tracks the latest adopted pair, so a
-     gateway that remints the durable key on resume cannot strand future
-     resumes on a stale key.
-8. **Model list / switching semantics** (unchanged, recorded): selection
-   applies to the session's pinned route immediately (next request); a fresh
-   session receives the model at `session.create`. The gateway resolves its
-   own provider from the model id; the adapter does not second-guess it.
-9. **Homes** (dev-rules §5/§13): the Hermes runtime keeps its native
-   `~/.hermes` home — never redirected, never seeded. `<dshHome>/agents/hermes/`
-   holds only the adapter's DSH-side state (`dsh-sessions.json`).
-
-## Testing
-
-```bash
-npm run build
-DSH_HOME=<repo>/.tests node --test test/*.test.mjs
-```
-
-All unit/fixture tests fake the gateway child (`setGatewayFactory`) — no real
-python child in any test (the opt-in live suite was retired with the
-2026-09-24 scenario retirement; whole-plugin scenarios run on the superd
-4999 pack line).
-
-## Trap: `npm install` materializes the hub link
-
-This package depends on `@pgmi-builds/superd-hub` via `file:../superd-hub`. A
-bare `npm install` replaces the symlink with a PHYSICAL copy → a second hub
-instance in the same process → every world webServer stays `pending` forever.
-After any `npm install` here, re-link it:
-
-```bash
-rm -rf node_modules/@pgmi-builds/superd-hub
-ln -s ../../../../super-dsh/superd-hub node_modules/@pgmi-builds/superd-hub
-```

package/agent-omp/README.md

@@ -1,94 +0,0 @@
-# @pgmi-builds/agent-omp（OMP adapter，RPC 线）
-
-OMP provider for DeepSeek Harness（[dsh](https://www.npmjs.com/package/@deepseek-ai/dsh)）。
-
-**不内嵌任何 OMP 代码副本**：适配器用操作员本机已在用的 `omp` binary，以 `omp --mode rpc` 子进程形态驱动，
-stdio 上跑 OMP 的 NDJSON 协议（v1），把 OMP 的 RPC 面（prompt / follow_up / steer / abort / get_state /
-get_messages / set_model / resume / compact）桥接进 Dash 的 Agent/Session 契约，标准 DSH Web UI 即可驱动 OMP 会话。
-模型选择由 OMP 数据面的 `LlmAdapter` 承接（`config.yml` 的 `modelRoles`）。
-
-## 集成形态
-
-```
-dsh 宿主 (Node 22, 本包 dist/)               操作员本机的 omp binary
-  omp-web 衔接层（agent/adapter/       ←→     `omp --mode rpc`（NDJSON v1 over stdio）
-  replay/store/supervisor）                    ~/.omp 是其唯一的 app home
-```
-
-- **没有 sidecar，没有 Bun，没有 SDK 依赖**：一会话一 `omp --mode rpc` 子进程，进程生命周期跟随会话。
-- **binary 解析**（`src/rpc-client.ts` 的 `resolveOmpExecutable()`）：
-  `$OMP_EXECUTABLE` → `PATH` 上的 `omp` → `~/.local/bin/omp` / `/usr/local/bin/omp` → 裸 `"omp"`（让 spawn 报 ENOENT）。
-- **进程组隔离**：子进程 `detached` 自成进程组，teardown 走 SIGTERM + 2s 宽限后 SIGKILL，保证 `omp` 及其工具子进程不残留。
-
-## 安装与启用
-
-本包是 `super-dsh` 单一交付包内的兄弟目录，**不单独安装**（`dsh plugin --profile <name> add super-dsh`），
-也不需要预装任何 OMP SDK。唯一的外部前置条件 = **操作员机器上有 `omp`**：
-
-- 缺失时不静默回落：adapter 在 `apply()` 做一次二进制可解析性探测并打显式诊断，首轮 prompt 以 spawn 错误 fail loud 冒到会话。
-- 启用由包内 `cordis.patch.yml` 承担（挂 OMP provider + 禁用原生 agent-loop / llm 路由），profile 无需手改。
-
-## Home 布局（两个 home，别混）
-
-| 名字 | 是什么 | 定义（`src/knobs.ts`） | 默认 |
-|---|---|---|---|
-| **`OMP_HOME`** | OMP runtime app home（`agent.db`/`models.db`/`sessions/` 的写入目标，也是数据面子进程的 cwd） | `$OMP_HOME ?? resolveOmpNativeHome()` | **原生 `~/.omp`**（`$OMP_HOME` 只作测试 / 适配器级隔离 knob） |
-| **`OMP_NATIVE_HOME`** | 操作员的原生 OMP 安装（TUI/CLI）读面：`agent/config.yml`、`agent/models.yml`、原生 session store | `$OMP_NATIVE_HOME ?? join(homedir(), ".omp")` | `~/.omp` |
-| `<DSH_HOME>/agents/omp/` | 该 world 的 **DSH** home（DSH 会话日志、storages、settings） | dsh 宿主解析 | 非 app home |
-
-- spawn **零重定向**：不把 `OMP_HOME` 喂给子进程；`~/.omp` 是唯一 OMP app home。
-- 绝不要把 `OMP_NATIVE_HOME` 指到空目录 / 测试 home——它是 models.yml 的读取来源，读空 ⇒ 适配器零 provider ⇒ `session/prompt` 报 `model-unavailable`。
-
-## 数据面（`omp` 子进程）
-
-`src/omp-cli.ts` 把操作员 binary 作为模型目录与 `modelRoles` 的**第一源**（不吃 RPC 帧）；原生 `~/.omp` 的文件只作失败回落与排序读面：
-
-- `omp models --json` → 凭证解析后的可用模型目录（含 agent.db 里的 OAuth/login key 等配置面看不见的凭证）；子进程失败才回落磁盘 `models.db` ∪ `models.yml`（并打 stderr 提示）。
-- `omp config get modelRoles --json` → role → `"provider/model[:effort]"` 映射（含持久化的 `default` 选择），每次现读。
-- `omp config set modelRoles --json <obj>` → 整对象回写（拒绝点号 key），OMP 自己持久化 `modelRoles.default`。
-- provider 排序与 boot 期默认模型仍首选 `agent/config.yml` 磁盘读（`omp-store.ts` 的 mini-YAML 扫描），`ompModelRolesSync` 兜底。
-- 每次调用都按 `resolveOmpExecutable()` 现解析、`cwd = OMP_HOME`；**fail-soft**：binary 缺失/损坏/无响应 → 读 `undefined`、写 `false`，provider 永因 CLI 挂掉而 boot 失败。
-
-## 实现要点
-
-- **传输**：`src/rpc-client.ts` 的 `OmpRpcClient` —— NDJSON 读取（按 `\n` 切帧）、`ready` 握手（默认 120s 上限，`OMP_READY_TIMEOUT_MS`）、
-  per-command 响应 deadline（默认 30s，`OMP_COMMAND_TIMEOUT_MS`）、`on`/`onTitle`/`onFailure` 事件分发。
-- **不协商协议**：不发 `negotiate_protocol`，停在 v1 = 纯 NDJSON（旧读取器即正确）。协商到 v2 会切换到 >1MiB 分帧，需要重组器——列为已知 gap。
-- **lazy 铁律**：`src/lazy-rpc.ts` 的 `LazyOmpRpc` 是唯一 spawn 点，构造零 spawn；`prompt`/`followUp`/`steer`/`ensureStarted` 才拉起子进程，
-  被动查询（`getState`/`getSubagents`/`getSessionStats`/`getSystemPrompt`/`abort`/`sendRaw`）合成应答、绝不 spawn。
-  `createAgent` 与 `resume` 两条路径都走它（resume 有映射时加 `--resume <ompFile>`），生成参数 `--approval-mode <mode>`。
-- **两平面**：dsh 原生 session log 是 WebUI 唯一读面（插件当 producer：OMP RPC 事件 → SessionEvent → `ctx.sessionPersistence`）；
-  OMP 原生会话文件是 runtime 权威（插件当 bridge：`bridge-store.sqlite` 只存 dsh↔omp 映射）。双份存储显式接受，单向阀 = 不回读。
-- **已删除面**（本 RPC 轮，2026-10-03）：`src/sdk-client.ts`、`src/sidecar-client.ts`、`src/protocol.ts`、`sidecar/`，以及 SDK/Bun 依赖与 `test/sidecar-*.test.mjs`；`scripts/build-client.ts` 与 `src/client/`、`src/mobile/` 保留（client 半边与 sidecar 无关）。
-
-## 协议与实测记录（2026-10-03）
-
-`ready` 帧实测：
-
-```json
-{"type":"ready","protocolVersion":1,"supportedProtocolVersions":[1,2],
- "maxFrameBytes":1048576,"maxReassembledFrameBytes":67108864}
-```
-
-- 只要求 `type === "ready"`；`protocolVersion` / `supportedProtocolVersions` / `maxFrameBytes` / `maxReassembledFrameBytes` 记录不校验。
-- 不协商的路径实测停在 v1；`get_state` / `get_available_models` 未协商也照常应答；事件词表
-  （`agent_start` / `turn_start` / `message_start` / `message_update` / `message_end` / `tool_execution_start` / `tool_execution_end` / `turn_end` / `agent_end`）与 `agent.ts` 的 switch 对齐。
-- 已知 gap：v2 分帧未实现（单帧 >1MiB 靠大行承载）；对 `omp` 版本门仅实测 v18.4.9。
-
-## 测试
-
-```bash
-npm run build                  # tsc -p tsconfig.json && tsc -p tsconfig.client.json
-node --test test/*.test.mjs    # 全 fakes / 源级断言，零真 runtime、零真 omp spawn
-```
-
-- `test/no-sidecar.test.mjs` = RPC 轮的删除面 + tick 门双重把守（源级断言：`src/` 不得再出现 SDK/sidecar client；
-  `index.ts` 只能 `new LazyOmpRpc(`；tick 的目录刷新必须挂在 `liveOmpSessionExists` 上，并对编译后的 `dist/index.js` 跑行为真值表）。
-- `rpc-client` / `lazy-rpc` / `omp-cli-rpc` / `resolve-executable` / `package-contract` 覆盖传输、lazy 不变量、数据面与交付清单。
-- **场景级验证只走整包**：`super-dsh` 的 4999 pack 线（`test/start-4999.sh`）+ dev3 目标机实装；本目录不再有 per-agent 场景 rig。
-
-## 历史
-
-本包在 2026-10-03 前是内嵌 SDK + Bun 子进程（sidecar）线（SDK 事件 → SessionEvent，单进程多路复用）；该线连同
-762M SDK 树 + 76M bun 二进制一起从交付面删除，改用操作员本机 binary 的 RPC 传输（设计正本：
-`docs/specs/omp-rpc-transport/spec.md`）。

package/agent-omp-sdk/README.md

@@ -1,103 +0,0 @@
-# @pgmi-builds/agent-omp-sdk — OMP (SDK) adapter (opt-in)
-
-The **second** OMP adapter package, alongside `@pgmi-builds/agent-omp` (the RPC
-line). It is a complete, standalone copy of the pre-RPC-era OMP bridge — no
-shared code with the RPC package.
-
-- **World key** `omp-sdk`, roster label `OMP (SDK)`, world home
-  `<dshHome>/agents/omp-sdk` (deliberately not `agents/omp`).
-- **Off by default**: the `agent-omp-sdk` row in the super-dsh composite carries
-  `disabled: true`, so while the row is off not one byte of this package is
-  imported and nothing is fetched. Turning the row on (plugin manager
-  `setPluginEnabled` / `dsh plugin`) IS the switch — no env var, no config key.
-- **Why it exists**: the RPC shape is one `omp` child per Dash session
-  (~240 MB private each). This shape hosts **N sessions in one bun sidecar**
-  and shares `authStorage` / `modelRegistry` across them, so the marginal cost
-  per extra session is far lower.
-
-## No dependency is declared, and nothing is fetched at install time
-
-`package.json` declares an **empty `dependencies`** — no coding-agent package,
-no `bun`, no `optionalDependencies`, no `postinstall`. `dsh plugin add` only
-unpacks this package; `npm pack` contains no SDK bytes (only our own
-`sidecar/main.ts` source, which imports the package *inside the fetched
-runtime*).
-
-The durable runtime is fetched **lazily**, on the first real prompt of an
-`omp-sdk` session (draft / browse / passive queries stay at zero action, the
-same zero-spawn window the RPC line holds):
-
-```
-<worldHome>/sdk-runtime/
-  bin/bun                        bun release (linux-x64) unzipped into place
-  package.json / node_modules/   the pinned coding-agent package, installed with that bun
-  sidecar/main.ts                this package's sidecar (bun resolves node_modules from here)
-  dist/protocol.js               the compiled protocol module the sidecar imports
-<worldHome>/sdk-runtime.json     marker: {pluginVersion, packageVersion, bunVersion, bunPath, installedAt}
-<worldHome>/sdk-runtime.lock     atomic (mkdir) bootstrap lock
-<worldHome>/sdk-runtime.error.log  written only by a failed fetch
-```
-
-The marker is written **last**; a marker whose identity (`pluginVersion`,
-`packageVersion`, `bunVersion`) does not match the running adapter is treated as
-absent and refetched. The install is deliberately **slim**: `bun add --exact
---ignore-scripts --omit=optional @oh-my-pi/pi-coding-agent@<pin>
-@oh-my-pi/pi-natives-<platform>@<pin>` — `--ignore-scripts` blocks package build
-scripts, `--omit=optional` drops the ~234 MB `@huggingface/transformers` +
-`onnxruntime-*` weight whose native postinstall is blocked anyway, and the
-platform binding package is re-added explicitly because `@oh-my-pi/pi-natives`
-needs it to load (`OMP_SDK_KEEP_OPTIONAL=1` reinstates the full tree). After the
-install the fetcher copies the sidecar and the compiled protocol module in, then
-runs a **post-install smoke import** (`<bun> -e 'await import("@oh-my-pi/pi-coding-agent")'`,
-agent dir redirected inside the runtime tree) and only then writes the marker —
-a pin that cannot be imported (18.4.9 is such a pin) fails loud here instead of
-at the first prompt.
-
-A failed fetch writes the error log and throws a single actionable error naming
-`OMP_SDK_PACKAGE_VERSION`; it never degrades silently into a confusing sidecar
-crash, and it never falls back to the RPC line (that is another row the user did
-not enable).
-
-## Wiring (where the fetch is triggered, and where it is not)
-
-- `world-plugin.ts` mounts the world and prints ONE report-only diagnostic when
-  the runtime is not on disk yet. It never fetches, spawns or imports the
-  runtime.
-- `index.ts` (`OmpProvider`) builds its transport in the constructor — that
-  builds a pool object, nothing else.
-- `transport.ts` / `lazy-rpc.ts` (`LazyOmpRpc`) construct per-session wrappers
-  with **zero** side effects; a new-chat draft leaves nothing server-side.
-- `sidecar-client.ts` (`OmpSdkSidecar#start`) is the ONE place `ensureSdkRuntime`
-  is awaited. `start()` is reached only from `LazyOmpRpc#ensure()`, i.e. from the
-  first `prompt` / `followUp` / `steer` / `ensureStarted`.
-- `sdk-client.ts` (`createOmpSdkSidecarPool`) holds the refcounted singleton:
-  two sessions of one dsh process share one bun child, and the pool releases
-  (and stops) it when the last client closes.
-
-## Manual warm-up
-
-```sh
-node scripts/fetch-sdk-runtime.mjs <dsh-home>      # world home = <dsh-home>/agents/omp-sdk
-# or, with the home in the environment:
-DSH_HOME=<dsh-home> npm run fetch-sdk-runtime
-```
-
-The script is a dev/test tool: it refuses any home outside this repository's
-`.tests` tree (the launcher red line) and has no `~/.dsh` default. It shares
-`createSdkRuntimeDeps` with the adapter's first-prompt fetch, so the two paths
-cannot drift.
-
-Pins: `OMP_SDK_PACKAGE_VERSION` (default `18.5.0` — do not use 18.4.9, whose
-source-level import is broken; `18.2.11` is the last known-good fallback) and
-`OMP_SDK_BUN_VERSION` (default `1.4.2`).
-
-## Build & test
-
-```sh
-npm run build     # tsc -p tsconfig.json
-npm test          # node --test test/*.test.mjs  (imports dist/, zero network, zero real bun)
-```
-
-The suite is fakes-only: the runtime bootstrap is driven through its injected
-`SdkRuntimeDeps`, and the sidecar spawn path through an injected `runtimeFetch`.
-No test downloads, spawns bun or touches a real home.

package/agent-pi/README.md

@@ -1,67 +0,0 @@
-# @pgmi-builds/agent-pi (Super D)
-
-pi coding agent provider for DeepSeek Harness — an `AgentFactory` dsh plugin that embeds the
-**pi coding agent** (`@earendil-works/pi-coding-agent@0.84.2`) **in-process via its SDK**
-(`createAgentSession` / `AgentSession` / `ModelRuntime`) and bridges pi's session surface into
-the Dash Agent/Session contracts. Structure follows `agent-omp` (same pi-agent-core lineage);
-lifecycle follows `agent-codex` (AW-E SDK line, DSH-native session persistence).
-
-## Per-adapter rulings (2026-09-17 user; decisions recorded per dev-rules §4/§12)
-
-1. **Native data home `~/.pi`.** Unlike every prior adapter (codex `<dshHome>/agents/codex`,
-   omp `<dshHome>/agents/omp/.omp`), pi keeps its **native home**: the adapter passes no
-   `agentDir` override, so the SDK's `getAgentDir()` default applies — auth, models, settings,
-   skills, extensions and project trust are exactly what the user's pi CLI sees. No app-home
-   seeding, no config one-way-valve. Dev-rules §5/§13's app-home ruling is superseded for pi's
-   runtime data by this directive. Tests redirect via `PI_CODING_AGENT_DIR` /
-   `PI_CODING_AGENT_SESSION_DIR` env only.
-2. **`<dshHome>/agents/pi/` = adapter-owned DSH state only** — currently the mapping file
-   `dsh-sessions.json`. pi never reads it; it is DSH-side bookkeeping in the same class as the
-   DSH session log itself.
-3. **Session storage duplication accepted**: pi writes its native session JSONL under
-   `~/.pi/agent/sessions/<encoded-cwd>/`; the adapter writes the DSH log through upstream
-   `session-persistence-jsonl` (factory holds the write channel). The WebUI reads the DSH copy;
-   the native copy stays pi's authority; no back-read of pi transcripts for list/replay.
-4. **Session identity = "mapping only"** (codex model): the DSH session id is the authority;
-   the pi session file path is `null` in the map until the first prompt materializes it; resume
-   resolves through the map and **fails closed** when unknown. Lazy iron law: zero pi objects
-   before the first real prompt.
-5. **In-process SDK** (user choice "sdk, refer to omp agent adapter"): no sidecar, no
-   `--mode rpc` subprocess. Shared module-level `ModelRuntime`; one `AgentSession` per session.
-6. **Model route**: single provider id `pi` on `ctx.llm`; model ids are composite
-   `<provider>/<modelId>` (pi is multi-provider). Selection is live (`session.setModel`) — an
-   upgrade over the codex SDK line's next-turn-only switch. `steer` is also real (pi supports it).
-7. **Permission presets → launch-only toolsets** (pi has no per-action approval):
-   `danger-full-access` / `workspace-write` → pi default tools (`read,bash,edit,write`);
-   `read-only` → `read,grep,find,ls`. `/permission` is shadowed per-session with a clean
-   refusal; `PI_APPROVAL_MODE=<preset-name>` overrides for headless runs.
-8. **Compaction is wired** (unlike codex): `/compact` works via `session.compact()`;
-   pi `compaction_start|end` → DSH `compaction/start|end` with a generated `compactionId`.
-9. **Titles**: pi owns them — `session_info_changed` → DSH `session/title`
-   (`source: {kind:"provider", provider:"pi"}`); the dsh `session-title-llm` row stays disabled.
-
-## Layout
-
-`src/`: `index.ts` (PiProvider + `setupAndPublish` transaction), `agent.ts` (PiAgent shim),
-`pi-client.ts` (SDK client seam + lazy start), `pi-events.ts` (pi → wire vocabulary projection),
-`session-map.ts`, `models.ts` (ModelRuntime singleton + catalog memo), `adapter.ts` (LlmAdapter),
-`permission.ts`, `agent-preset-pi.ts` + `agent-preset-projection.ts` (roster/chip), `pi-home.ts`
-(state dir), `knobs.ts`, `inbox.ts`, `world-plugin.ts` (hub bridge).
-
-## Testing
-
-`npm run build` then `node --test test/*.test.mjs` — tests import `dist/`, use temp homes, and
-inject fake pi sessions via `setPiSessionFactory`; the SDK seam is never hit by unit tests.
-Acceptance = standalone `dsh + adapter` real instance (form A) with a real pi turn, then the
-world form (form B) via the hub.
-
-## Trap: `npm install` materializes the hub link
-
-`dependencies["file:../superd-hub"]` gets materialized by `npm install` as a
-**physical copy** under `node_modules/@pgmi-builds/superd-hub` — a second hub
-module instance whose rosters/mount-registry are dead. Symptom in world form:
-the world's virtual webServer never appears (`9 entries did not activate`,
-everything pending on webServer). After ANY `npm install` in this package,
-re-link: `rm -rf node_modules/@pgmi-builds/superd-hub && ln -sfn ../../../superd-hub
-node_modules/@pgmi-builds/superd-hub` (codex symlink discipline; same class as
-the `@deepseek-ai/*` heal).