@khorsheed/dsh-local-agent-codex 0.2.0-rc.1 → 0.2.0-rc.3

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 变更记录
 
+## 0.2.0-rc.3（2026-10-22）
+
+（版本号说明：家族的 dsh-headless 包 0.2.0-rc.2 曾被发布后又撤回，npm 永久烧掉该版本号；为守住家族「同一版本线」纪律（check:release-groups），本波家族整体上移 rc.3，内容即 rc.2 计划稿。）
+
+- **BREAKING：网页登录移除，端点 key 成为唯一认证方式**。部署级凭据为插件配置 `baseUrl` / `apiKey`；每个作用域可再以 `<scopedHome>/endpoint-auth.json`（0600）按字段覆盖——「scope 文件 > profile 配置」。spawn 时注入为自定义 provider 覆盖片段加进程环境变量，`config.toml` 不被改写；key 不带 `baseUrl` 时直连 OpenAI 官方端点。**升级前必须配好端点凭据**，否则升级后读作未认证（README 带迁移说明）；残留的 `auth.json` 由 provision 每次启动清扫，`/codex login` 不再存在。
+- **设置卡新增端点凭据表单与「验证端点并获取模型」按钮**：卡片编辑默认 scope 的 endpoint-auth.json；验证探测 `GET <baseUrl>/v1/models`（兼容带不带 `/v1` 后缀的 baseUrl），不可达 / HTTP 状态 / 形状不符各失败形态折进判定文本。
+- **「可用模型」有序短名单取代自由文本 model 字段**：与家族其他卡共用同一组件——`<scopedHome>/models.json`，首项即默认模型，端点目录弹窗勾选添加、拖拽排序。`model` 配置键作为回退静默生效（YAML、API 写入），`/codex status` 照报生效设置。
+- **模型目录切换为端点供给**：目录 = 端点 `/v1/models` 实际供应的模型，与验证按钮同一次探测；原生 app-server 注册表降级为元数据补全（label / description / 推理档位 / isDefault），端点不供应的注册表项被丢弃。无端点凭据时添加弹窗带原因空载，传输故障保留上次成功清单。
+- **设置卡并入「本机 Agent 委派」家族卡**：本包卡读作「本机 Codex 委派」，作为家族卡的一节呈现；家族卡随后修复为无条件注册——原先的命名空间门控让它在 prod 上永不挂载（2026-10-21）。与旧版家族核混装时回落为独立卡。
+- **适配宿主 0.2.1 线**：委派链路迁移到 subagent `startActivation`（宿主 0.2.1 删除旧的 `ctx.subagents.start()`）；加宽 `@deepseek-ai/dsh-*` peer 区间以覆盖宿主 0.2.1。
+
 ## 0.2.0-rc.1（2026-09-30）
 
 - **家族折叠：委派工具收进本包**。新增 `./tool` 组合入口（`src/tool.ts`）——`subagent_codex` 委派工具由 agent 预设点名 `name: '@khorsheed/dsh-local-agent-codex/tool'` 按会话授予，Config 两字段（`provider` / `toolName`）全部可选、默认即本包取值，预设行无需配置；行 id `tool-subagent-codex-local` 不变。bundle patch 不再插 profile 根工具行（官方 `tool-subagent-codex` 行的停用覆盖保留），本包自挂载恰好一行（provider 行）。实现共享自家族核 `@khorsheed/dsh-local-agent` 的 `./tool-factory` 导出；对 `@khorsheed/dsh-local-agent-tool-subagent` 的依赖移除（该包退役）。

package/README.en.md

@@ -2,9 +2,9 @@
 
 English | [中文](README.md)
 
-Hand coding tasks to the Codex CLI installed on your own machine — its own login, its own session records, and your `~/.codex` never gets touched.
+Hand coding tasks to the Codex CLI installed on your own machine — an endpoint credential or its own login, its own session records, and your `~/.codex` never gets touched.
 
-dsh agents already get work done, but some tasks you simply want to give to your local Codex CLI: its account, its models, the toolchain you know. This plugin wires Codex in as a dsh local subagent — any agent preset can delegate with one call through the `subagent_codex` tool; delegations run inside a plugin-scoped home (`$DSH_HOME/local-agent/codex`), so your personal config, credentials and sessions are never touched; the process details (reasoning, tool calls, file changes) mirror live into the child session, and the final answer comes back to the parent.
+dsh agents already get work done, but some tasks you simply want to give to your local Codex CLI: its account, its models, the toolchain you know. This plugin wires Codex in as a dsh local subagent — any agent preset can delegate with one call through the `subagent_codex` tool; delegations run inside a plugin-scoped home (`$DSH_HOME/local-agent/codex`), so your personal config, credentials and sessions are never touched; the process details (reasoning, tool calls, file changes) mirror live into the child session, and the final answer comes back to the parent. Authentication is endpoint-key only (`baseUrl` + `apiKey` — a relay or an official platform key alike): container rounds share the host's credential and nothing is authorized inside the unit. There is no web login and no device code — no OAuth flow exists in this package.
 
 <img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/08-local-agent.png" width="640" alt="the Local Agent · Codex card on the Settings → plugin configuration page, its header status dot showing the auth state at a glance">
 
@@ -12,11 +12,11 @@ dsh agents already get work done, but some tasks you simply want to give to your
 
 - **Per-session delegation grant** — the `subagent_codex` tool is this package's `./tool` composition entry, granted to the sessions of an agent preset that names it (e.g. dev mode); no per-preset setup.
 - **Scoped-home isolation** — all Codex state (config, credentials, rollout session records) lives in `$DSH_HOME/local-agent/codex`, separate from your `~/.codex`.
-- **In-session login** — `/codex login` runs `codex login` on a pseudo-terminal and the authorization page opens in your browser by itself; when the page hands you a code, paste it back with `/codex code <code>`. The settings card shows auth status and offers sign-out.
+- **Endpoint credential (the only auth mode)** — fill `baseUrl` + `apiKey` on the card's Authentication section (saved as the default scope's `endpoint-auth.json`, mode 0600, local only) or preconfigure the profile row, and the scope is authenticated; every named scope may override the deployment pair field by field with its own `endpoint-auth.json`. Every round routes at the endpoint through a custom provider (`wire_api=responses`, verified end-to-end against codex-cli 0.163.0 through a relay), the key riding the process environment. The host shell's environment is never read; there is no web login.
 - **Resident mode (live)** — one resident `codex app-server` process per member, one turn per round: output streams into the child session in real time, cancel does not kill the process, and a crash resumes the same thread; off — or a channel that cannot come up — means the one-shot `codex exec` path, hot-switched without a reload.
-- **Settings card** — the Codex card on the Plugins detail page (on 0.1.5, Settings → Plugins → 插件配置): sign-in, a default model (blank = follow the CLI default), and the resident switch; a save applies on the next round.
+- **Settings card** — a section of the core's「Local Agent Delegation」family card on the Plugins page (on an older core, this package's own Plugins detail-page card): sign-in, the available-models shortlist (ordered, the first entry is the default; empty = the legacy chain), and the resident switch; a save applies on the next round.
 - **Resume a thread** — pass `resume="<childSessionId>"` to continue the same codex thread in the same dsh child session, even across host restarts.
-- **Custom endpoint** — route Codex's LLM requests through your own router via a scoped `config.toml` provider.
+- **Custom endpoint** — configure the endpoint credential on the card or the profile row to route through your relay; a hand-edited custom provider in the scoped `config.toml` stays authoritative too (never overwritten).
 - **Read-back and per-cell working directory** — every settled round reads the model, CLI version and usage back out of its own rollout into the delegation record; the file is located by thread id, cwd and time window, so concurrent runs each read their own round. Orchestrators pass a `cwd` per cell, and a resume in a different directory is rejected.
 
 <img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-codex-card.png" width="640" alt="the expanded Codex settings card: auth status with sign-in and sign-out, the default model, and the resident-mode switch">
@@ -30,7 +30,7 @@ dsh plugin --profile web add @khorsheed/dsh-local-agent
 dsh plugin --profile web add @khorsheed/dsh-local-agent-codex
 ```
 
-Both packages must be named explicitly — `dsh plugin add` reconciles only direct dependencies, so the family core is never mounted by a transitive dependency. Restart the web instance to activate, then run `/codex login` once from any session to authorize.
+Both packages must be named explicitly — `dsh plugin add` reconciles only direct dependencies, so the family core is never mounted by a transitive dependency. Restart the web instance to activate, then fill the endpoint and key in the Codex section's Authentication block of the「Local Agent Delegation」family card (the Plugins page) — or preconfigure the profile row; with neither, the status reads unauthenticated.
 
 Uninstall:
 
@@ -48,11 +48,25 @@ Optional, in the profile patch layer:
 - id: local-agent-codex
   config:
     sandbox: workspace-write   # codex exec policy: read-only | workspace-write | danger-full-access
+    baseUrl: https://your-relay.example/openai/v1  # optional: deployment-level endpoint (an OpenAI-compatible /v1 root); absent leaves the scope file or the web login to decide
+    apiKey: sk-...             # optional: deployment-level endpoint key (Bearer); keep it local, never commit it
     model: gpt-5.2             # optional: every delegation round starts the CLI with it; absent passes no model flag at all (below)
     live: false                # live driver: one resident codex app-server process per member, one turn per round (runtime-level graceful interrupt, push-mode mirroring); off — or a channel that cannot come up — means the one-shot exec path
     liveIdleMs: 1800000        # idle lifetime of a resident runtime before reclaim (default 30 min)
 ```
 
+### Endpoint credential (`baseUrl` + `apiKey`)
+
+**A configured key = every round routes at the endpoint.** When the scope's resolution (the scope's own `endpoint-auth.json` merged field by field over the profile row) carries a non-empty key, every delegation injects a custom provider on the argv (`-c model_provider=… -c model_providers.…={base_url, env_key=OPENAI_API_KEY, wire_api=responses}`) and the key travels in the process environment — `config.toml` is never rewritten, `auth.json` never consulted, the web login never participates. The one-shot exec, the resident app-server, and the model-catalog probes all ride the same credential. A key without a `baseUrl` targets OpenAI's own endpoint (an official platform key needs no relay — the built-in provider reads the same variable). Clearing the key (save the field blank on the card) reads unauthenticated.
+
+**The card's Authentication section edits the default scope's `endpoint-auth.json`** (mode 0600, local only; through the family gateway's `endpointAuth`/`configureEndpoint` Remotes, so no session is needed) — keys never enter the profile document, and the file's name matches the evaluation contract hash's credential denylist, so it never enters a condition fingerprint either. The "Verify endpoint & list models" button next to it runs a token-free probe against the SAVED endpoint (`GET <baseUrl>/v1/models`, Bearer header) and answers with reachability plus the served model list. The file also accepts a hand-written `"wireApi": "chat"` (the card never edits it and preserves it on save) for relays that only speak chat/completions.
+
+> **A bad key costs retry time** — a dead key makes the CLI retry against the endpoint for minutes before reporting a 401; `/codex status` shows the `rejected` grade only after that round settles. Re-saving the key (rewriting endpoint-auth.json) is the recovery.
+
+> **Migration note (next release line, breaking)** — the web login is removed outright: `/codex login` no longer exists, and the device-code/browser grant with it; the first boot after the upgrade sweeps the scoped home's leftover `auth.json`, so a stale grant cannot keep authenticating while the status reads unauthenticated. Configure `baseUrl` + `apiKey` on the card or the profile row BEFORE upgrading (an official platform key works as well as a relay key), or the upgraded instance reads unauthenticated.
+>
+> **Logout clears only the scope's own file** — `/codex logout` removes the scope's `endpoint-auth.json`; when the credential comes entirely from the profile row, logout refuses and names the profile as the place to edit.
+
 **Legacy key migration.** Live runs always consume incremental output: the old `liveMirrorGranularity: event | token` key is accepted for existing profiles but ignored, and changing it never changes a running process. Exec remains available for evaluation; final provider items remain authoritative, including tool history and usage.
 
 ### Default model (`model`)
@@ -68,11 +82,11 @@ Optional, in the profile patch layer:
 
 The scoped `config.toml` is never rewritten: `-m` overrules it per round and the file stays exactly as you edited it.
 
-The settings card’s "Default model" writes the provider setting for subsequent rounds. Its shared picker displays the scoped model directory, discovery source and completeness, plus an explicit model-ID input when needed. Clearing the selection follows the effective configuration/default chain. Saving does not interrupt an active round and requires no reload. If the shared picker is unavailable, the card retains its text-input fallback. Per-member model and effort changes use the durable controls described below.
+The settings card's「Available models」section maintains an **ordered model shortlist**: "Add model" checks entries off the endpoint's served catalog, so the list can only hold what the endpoint actually serves; drag rows to reorder. **The first entry is the default model** — every delegation round starts the CLI with it (`codex exec -m` one-shot, `-c model=…` on the resident app-server), outranked only by member session overrides and delegation-level picks. The list persists in the scoped home's `models.json` (each named scope may carry its own, the same file mechanism as the endpoint credential), every edit saves immediately and applies to the next round. **Empty = the legacy chain** (the `model` key below → the scoped `config.toml` → the CLI built-in). Per-member model and effort changes use the durable controls described below.
 
-The rich directory read now preserves native display labels, hidden candidates and reasoning options, traverses pagination, and uses the core cache and refresh subscription. Its context follows the member's scope and cwd. Failed refreshes retain the last successful snapshot as stale; configuration and history suggestions retain their source labels. The shared model picker and member effort controls are connected. Busy selections apply at the next complete turn boundary, including tool continuations; core owns current/pending state, cancellation and retry, while frozen evaluation members reject changes. A native catalog candidate is not proof of account access.
+The rich directory's vocabulary comes from the endpoint itself (`GET <baseUrl>/v1/models` — the same probe the "Verify endpoint & list models" button runs): a local registry cannot prove what the endpoint serves, and a dead key can no longer hide behind the CLI's local list. The native app-server `model/list` probe is demoted to metadata enrichment, running concurrently: it alone carries the display names, hidden candidates, reasoning-effort options and the `isDefault` compiled default, so a served id that matches the registry carries those over, while an id only the endpoint serves stands as a plain entry; a native failure warns once and the endpoint data is a complete answer on its own. With no credential, a rejected credential, an unexpected HTTP status, or a non-`/v1/models`-shaped reply, the directory loads empty with the reason; a transport failure throws, so the cache keeps the last good snapshot marked stale and retries (the openproxy relay once 500'd and recovered on its own — exactly the case this semantics is for). The probe context follows the member's scope and cwd. The shared model picker and member effort controls are connected. Busy selections apply at the next complete turn boundary, including tool continuations; core owns current/pending state, cancellation and retry, while frozen evaluation members reject changes. A native catalog candidate is not proof of account access.
 
-**A delegation's own model outranks this key.** An orchestrator may name the model for ONE delegation through the facade's `DelegationCallOptions.model` (the fixed order: session override > delegation record > this key > scoped config > CLI built-in). The first round's request is recorded and every resume round re-requests it — `resume` takes no model of its own. In live mode such a round is no longer refused: the model becomes the member's **start model**, bound at the app-server spawn; a resident runtime bound to a different model is retired first (the same codex thread resumes via thread/resume) so the round respawns onto the asked-for model.
+**A delegation's own model outranks this key.** An orchestrator may name the model for ONE delegation through the facade's `DelegationCallOptions.model` (the fixed order: session override > delegation record > the shortlist's first entry > this key > scoped config > CLI built-in). The first round's request is recorded and every resume round re-requests it — `resume` takes no model of its own. In live mode such a round is no longer refused: the model becomes the member's **start model**, bound at the app-server spawn; a resident runtime bound to a different model is retired first (the same codex thread resumes via thread/resume) so the round respawns onto the asked-for model.
 
 **Member-level switching (the composer model picker).** A member session can switch its model per session: an in-memory session-level override, the highest-priority layer, deliberately lost on a host restart. A switch is refused while a round is in flight; when idle and the member has a resident runtime bound to a different model, the switch retires that runtime — the next round respawns onto the new model while the CLI session (rollout) itself carries over. On the one-shot (exec) drive there is no resident process, so the override simply decides the next round's `-m`.
 
@@ -80,7 +94,7 @@ The rich directory read now preserves native display labels, hidden candidates a
 
 ## Custom endpoint
 
-Route Codex's LLM requests through your own endpoint by adding a custom provider to the scoped `$DSH_HOME/local-agent/codex/config.toml` (built-in providers can't be overridden, `OPENAI_BASE_URL` is ignored, and provisioning never overwrites an existing config):
+The endpoint credential (the card or the profile row) is the only credentialed route. You may still add a custom provider to the scoped `$DSH_HOME/local-agent/codex/config.toml` (built-in providers can't be overridden, `OPENAI_BASE_URL` is ignored, and provisioning never overwrites an existing config) — but its `env_key` reads the CHILD's environment, the host shell's same-named variables are scrubbed, and only the endpoint credential's key rides along, so a hand-written provider is useful in practice only for endpoints that need no auth (e.g. a local router):
 
 ```toml
 [model_providers.dsh-router]
@@ -89,20 +103,20 @@ base_url = "https://your-router.example/v1"
 model_provider = "dsh-router"
 ```
 
-The last line selects the provider for delegations; keep the rest of the file intact.
+The last line selects the provider for delegations; keep the rest of the file intact. An endpoint credential with a key wins over the file's `model_provider` selection (the argv's provider overrides it).
 
-⚠️ **Credential exposure**: the scoped `auth.json` token is sent to whatever endpoint serves the request — only use endpoints you control or trust. Each delegation logs the effective endpoint at info level.
+⚠️ **Credential exposure**: the endpoint key is sent to whatever endpoint serves the request — only use endpoints you control or trust. Each delegation logs the effective endpoint at info level.
 
-**Evaluation snapshot (`effectiveSettings`).** The harness declares a live-read snapshot of its fairness-relevant settings for the evaluation condition hash: drive (exec/live), the sandbox policy (plugin config), the reasoning effort (the scoped config's top-level `model_reasoning_effort`), whether a custom endpoint is pinned (read from the scoped config's provider, hostname only), the configured model (the plugin config's `model` key first — it overrules the file on every argv — then the scoped config's top-level `model`; absent when neither names one — never guessed), and the CLI version (`codex --version`, cached against the executable's path + mtime; absent when the CLI cannot be asked). `/codex status` and the `LocalAgentStatus` Remote attach the same snapshot.
+**Evaluation snapshot (`effectiveSettings`).** The harness declares a live-read snapshot of its fairness-relevant settings for the evaluation condition hash: drive (exec/live), the sandbox policy (plugin config), the reasoning effort (the scoped config's top-level `model_reasoning_effort`), whether a custom endpoint is pinned (the endpoint credential first — the scope's `endpoint-auth.json` merged field by field over the plugin config; with no key, the scoped config's custom provider answers; hostname only, key material never enters the snapshot), the configured model (the scope's `models.json` first entry first, then the plugin config's `model` key — it overrules the file on every argv — then the scoped config's top-level `model`; absent when none names one — never guessed), and the CLI version (`codex --version`, cached against the executable's path + mtime; absent when the CLI cannot be asked). `/codex status` and the `LocalAgentStatus` Remote attach the same snapshot.
 
 ## Compatibility
 
-- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ public API compatible. Live generation uses the local-agent transient Remote and public Conversation nodes; incremental durable checkpoints provide recovery, and native final messages retain their transcript and usage semantics. End-to-end latency acceptance is tracked by the room coordinator proposal. minHost 0.1.5-rc.1 — older hosts stay on the previous release line.
-- source line (deepseek-harness master): ✅ (verifiedHost: 0.1.5-rc.1)
+- npm release line (`@deepseek-ai/dsh@0.1.5-rc.1`): ✅ public API compatible. Live generation uses the local-agent transient Remote and public Conversation nodes; incremental durable checkpoints provide recovery, and native final messages retain their transcript and usage semantics. End-to-end latency acceptance is tracked by the room coordinator proposal. minHost 0.1.5-rc.1 — older hosts stay on the previous release line. The settings card renders as a section of the core's「Local Agent Delegation」family card (the core's `plugins.item` entry on the Plugins page, 0.1.7-alpha.1+; on an older core this package falls back to its own `plugins.item` card), mounted through `configForms.whileServed` while the Host serves the `local-agent-codex` namespace; 0.1.5 renders no card (the host removed the `settings.plugin.item` seat) — every other surface is unchanged.
+- source line (deepseek-harness master): ✅ (verifiedHost: 0.2.1-rc.1) — host-021 wave: full build+test green against the 0.2.1-rc.1 tree; delegation moved to `ctx.subagents.startActivation` (managed activation), and run.id is now unique per execution.
 
 ## Known Limitations
 
-- **Login needs one browser authorization** — `/codex login` opens the authorization page itself, and when the CLI asks for a code you paste it back with `/codex code <code>`; there is no API-key path.
+- **No web login** — the endpoint credential is the only auth path (the card or the profile row; an official platform key works as well as a relay key). The ChatGPT-subscription OAuth path is not part of this package.
 - **`codex exec` is non-interactive** — actions the sandbox policy would approve are denied, not prompted; in resident mode approval-shaped requests are likewise auto-declined unattended (cancel/decline). See the `sandbox` config.
 - **Named scopes are exec-only** — the resident app-server binds the default scoped home, so a scoped delegation never enters live mode.
 - **Headless caveat** — `/codex` commands need a Web session; headless can still delegate via a composition mounting the tool row.
@@ -114,9 +128,9 @@ The last line selects the provider for delegations; keep the rest of the file in
 
 **Named scopes.** `/codex login --scope <name>` opens a second scoped home at `<homesRoot>/codex@<name>`: the directory is provisioned with the same `config.toml` that pins credential storage to a file rather than the macOS keychain, so that scope's login lands in its own `auth.json`. A scoped delegation runs `codex exec` there, writes its rollout there and reads it back from there — exec-only, because the resident app-server is bound to the default scoped home.
 
-**Bundle composition.** The patch registers the `codex` harness (scoped `CODEX_HOME`, PTY login, rollout-file session records) — exactly one provider row; since the family fold the `subagent_codex` tool is this package's `./tool` composition entry, granted per session by an agent preset that names it (the dev preset's `tool-subagent-codex-local` row), no longer mounted at the profile root. The family keeps the official model-facing name `subagent_codex`: the official preset row of that name already ships `disabled: true`, and the patch disables the profile-root row once more, so a community install can never register two `subagent_codex` tools; a user who deliberately re-enables the official row in their own preset layer gets a loud duplicate-name conflict and must choose one, by design. The `codex-local` provider spawns `codex exec` under that home (the one-shot drive when live is off). The browser half ships with this package's `./client`: the Codex settings card composes the family core's shared `ProviderAuthBlock`, landing on the Plugins page's per-package detail view (`plugins.bundle.config`, keyed by package name) for a standalone install, on the bundle detail view's row-level configure entry (`plugins.row.config`) when installed as a family-bundle member, and — on 0.1.5 — on the Settings → Plugins → 插件配置 tab (`settings.plugin.item`, keyed by the settings namespace); card writes ride the bound settingsScope and hot-apply without a reload. The core itself comes from `@khorsheed/dsh-local-agent`, declared as a dependency.
+**Bundle composition.** The patch registers the `codex` harness (scoped `CODEX_HOME`, PTY login, rollout-file session records) — exactly one provider row; since the family fold the `subagent_codex` tool is this package's `./tool` composition entry, granted per session by an agent preset that names it (the dev preset's `tool-subagent-codex-local` row), no longer mounted at the profile root. The family keeps the official model-facing name `subagent_codex`: the official preset row of that name already ships `disabled: true`, and the patch disables the profile-root row once more, so a community install can never register two `subagent_codex` tools; a user who deliberately re-enables the official row in their own preset layer gets a loud duplicate-name conflict and must choose one, by design. The `codex-local` provider spawns `codex exec` under that home (the one-shot drive when live is off). The browser half ships with this package's `./client`: the Codex settings card composes the family core's shared `ProviderAuthBlock`, rendering as a section of the core's「Local Agent Delegation」family card — mounted through `configForms.whileServed` while the Host serves the `local-agent-codex` namespace, one section for a standalone install, a family bundle, or a mode pack alike (on an older core, this package's own `plugins.item` card instead); card writes ride the bound settingsScope and hot-apply without a reload. The core itself comes from `@khorsheed/dsh-local-agent`, declared as a dependency.
 
-**Login and credentials.** `/codex login` runs `codex login` on a pseudo-terminal through the host's subprocess seam — the CLI starts its own localhost callback server and opens the browser itself, the first-class flow; the command reply carries the authorization URL captured from the output as a fallback link, and when the CLI asks for a code the user pastes it with `/codex code <code>` (written to the child's stdin). Completion is decided by a credential watch on the scoped home: `auth.json` present with a stamp newer than the watch start — a leftover credential is never mistaken for a fresh login. A browserless remote terminal can still run `codex login --device-auth` by hand with `CODEX_HOME` pointed at the scoped home, landing in the same `auth.json`. First start writes a minimal `config.toml` pinning `cli_auth_credentials_store = "file"` — Codex's default `auto` would resolve to the macOS keychain, leaking credentials outside the scoped home and defeating this package's `auth.json` presence check; an existing config is left untouched. `/codex logout` deletes the scoped `auth.json`, so a later login authorizes a fresh account.
+**Credentials.** Endpoint-key only, no login flow: the scope's `endpoint-auth.json` (mode 0600) merges field by field over the profile row's `baseUrl`/`apiKey`, and when the resolution carries a key, every round injects a custom provider on the argv (`wire_api=responses`, the key in the process environment — verified against codex-cli 0.163.0 on a fresh scope with no login file at all, straight through a relay). First start writes a minimal `config.toml` pinning `cli_auth_credentials_store = "file"` — Codex's default `auto` would resolve to the macOS keychain, so a hand-run `codex login` inside the scoped home would leak the grant outside it; an existing config is left untouched. Every boot also sweeps the web-login era's leftover `auth.json` — this package no longer reads it, and keeping it would let a stale grant authenticate while the status reads unauthenticated. `/codex logout` deletes the scoped `endpoint-auth.json`, so a later configuration rotates the key.
 
 **Session records.** `/codex sessions` lists the scoped home's `sessions/YYYY/MM/DD/rollout-*.jsonl` files — sessions this plugin's delegations created, never your personal ones. The records entry in the session header (provided by the family core's client) narrows the same list to records whose `workDir` matches the session cwd.
 

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/local-agent-codex/README.en.md
-packages/local-agent-codex/README.en.md: db346c4441e59ca802de149ec93b253a250e9cdd
-packages/local-agent-codex/README.md: 10d69741bf5034c13705231065546981d5596aaf
+packages/local-agent-codex/README.en.md: 3c6d3b8d99fb9689ab77216dad33308e80432f10
+packages/local-agent-codex/README.md: 868a96be66c115ee92f4ba3cce80d3efc3d50858

package/README.md

@@ -2,9 +2,9 @@
 
 [English](README.en.md) | 中文
 
-把编码任务甩给你本机装好的 Codex CLI 跑——它自己的登录、自己的会话记录,你的 `~/.codex` 一根手指都不碰。
+把编码任务甩给你本机装好的 Codex CLI 跑——端点凭据或它自己的登录、自己的会话记录,你的 `~/.codex` 一根手指都不碰。
 
-dsh 的 agent 已经能干活,但有些任务你就是想交给本机的 Codex CLI:它的账号、它的模型、你熟悉的工具链。这个插件把 Codex 接成 dsh 的本地子代理——任意 agent preset 都能经 `subagent_codex` 工具一句话委派;委派跑在插件隔离的作用域目录(`$DSH_HOME/local-agent/codex`)里,你的个人 config、凭据、会话完全不被触碰;过程细节(推理、工具调用、文件改动)实时镜像在子会话里,最终回答回到父会话。
+dsh 的 agent 已经能干活,但有些任务你就是想交给本机的 Codex CLI:它的账号、它的模型、你熟悉的工具链。这个插件把 Codex 接成 dsh 的本地子代理——任意 agent preset 都能经 `subagent_codex` 工具一句话委派;委派跑在插件隔离的作用域目录(`$DSH_HOME/local-agent/codex`)里,你的个人 config、凭据、会话完全不被触碰;过程细节(推理、工具调用、文件改动)实时镜像在子会话里,最终回答回到父会话。认证是端点凭据制(`baseUrl` + `apiKey`,中转/官方平台 key 均可):容器轮与宿主轮用同一套凭据,容器里不需要再授权一次。没有网页登录、没有设备码,OAuth 流程在本包不存在。
 
 <img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/08-local-agent.png" width="640" alt="设置 → 插件配置页里的 Local Agent · Codex 卡片,卡头状态点一眼可见授权状态">
 
@@ -12,11 +12,11 @@ dsh 的 agent 已经能干活,但有些任务你就是想交给本机的 Codex C
 
 - **按会话授予的委派**——`subagent_codex` 工具是本包的 `./tool` 组合入口,由点名它的 agent 预设(如开发模式)授予该预设的会话,无需逐 preset 配置。
 - **作用域目录隔离**——Codex 的全部状态(config、凭据、rollout 会话记录)留在 `$DSH_HOME/local-agent/codex`,与你的 `~/.codex` 互不干扰。
-- **会话内登录**——`/codex login` 在伪终端里跑 `codex login`,授权页自动在浏览器打开;页面给出 code 时用 `/codex code <code>` 粘贴回来。设置卡片显示认证状态并提供退出登录。
+- **端点凭据(唯一的认证方式)**——设置卡「认证」区填 `baseUrl` + `apiKey`(保存进默认 scope 的 `endpoint-auth.json`,0600,只存本机)或预配在 profile 配置行即已认证;每个命名 scope 可用自己的 `endpoint-auth.json` 按字段覆盖部署级配置。每轮委派以自定义 provider(`wire_api=responses`,实测 codex-cli 0.163.0 经中转直通)路由到端点,key 经进程环境传递。宿主 shell 的环境变量从不被读取;没有网页登录。
 - **常驻模式(live)**——每成员常驻一个 `codex app-server` 进程,按轮发 turn:输出实时流入子会话、取消不杀进程、崩溃后自动续上原线程;关闭或通道起不来即回一次性 `codex exec`,热切换无需重载。
-- **设置卡片**——Plugins 详情页(0.1.5 为 设置 → 插件 → 插件配置)里的 Codex 卡:登录授权、默认模型(留空 = 跟随 CLI 默认)、常驻开关,保存即于下一轮生效。
+- **设置卡片**——core 的「本机 Agent 委派」家族卡里的一节（Plugins 页；旧版 core 上回落为本包自己的 Plugins 详情页卡）:登录授权、可用模型（有序短名单，第一个为默认；留空 = 跟随旧链）、常驻开关,保存即于下一轮生效。
 - **线程续聊**——传入 `resume="<childSessionId>"` 在同一个 dsh 子会话里继续同一个 codex 线程,宿主重启后也续得上。
-- **自定义端点**——经作用域 `config.toml` 的自定义 provider 把 Codex 的 LLM 请求路由到你自己的路由端点。
+- **自定义端点**——设置卡或 profile 行配好端点凭据即路由到你的中转;也可手改作用域 `config.toml` 的自定义 provider(文件保持权威,不被覆盖)。
 - **回读与独立工作目录**——每轮从本轮 rollout 回读实际模型、CLI 版本与用量写进委派记录;定位按 threadId + cwd + 时间窗,并发跑也读的是自己那一轮。编排器可用 `cwd` 选项给每格独立目录,resume 换目录即拒绝。
 
 <img src="https://raw.githubusercontent.com/Khorsheed/dsh-basic/main/docs/screenshots/local-agent-codex-card.png" width="640" alt="展开的 Codex 设置卡:认证状态与登录/退出、默认模型、常驻模式开关">
@@ -30,7 +30,7 @@ dsh plugin --profile web add @khorsheed/dsh-local-agent
 dsh plugin --profile web add @khorsheed/dsh-local-agent-codex
 ```
 
-两个包必须同时点名——`dsh plugin add` 只调和**直接**依赖,家族 core 不会被传递依赖自动挂载。重启 web 实例后生效,然后在任意会话里跑一次 `/codex login` 完成授权。
+两个包必须同时点名——`dsh plugin add` 只调和**直接**依赖,家族 core 不会被传递依赖自动挂载。重启 web 实例后生效,然后在「本机 Agent 委派」家族卡（Plugins 页）的 Codex 一节「认证」区填端点与 key 即可(也可预配在 profile 的本包配置行);都不配则状态为未认证。
 
 卸载:
 
@@ -48,11 +48,25 @@ dsh plugin --profile web remove @khorsheed/dsh-local-agent-codex
 - id: local-agent-codex
   config:
     sandbox: workspace-write   # codex exec 策略:read-only | workspace-write | danger-full-access
+    baseUrl: https://your-relay.example/openai/v1  # 可选:部署级端点(OpenAI 兼容 /v1 根);不配则由 scope 文件或网页登录决定
+    apiKey: sk-...             # 可选:部署级端点 key(Bearer);只放本地,绝不入库
     model: gpt-5.2             # 可选:每轮委派以它起 CLI;不写就一个模型参数都不传(见下)
     live: false                # 常驻驱动:每成员常驻一个 codex app-server 进程,按轮发 turn(运行时级优雅中断、事件推送镜像);关闭或通道不可用即回一次性 exec
     liveIdleMs: 1800000        # 常驻 runtime 空闲回收时限(默认 30 分钟)
 ```
 
+### 端点凭据(`baseUrl` + `apiKey`)
+
+**配了 key = 每轮走端点。**scope 的解析结果(`<作用域目录>/endpoint-auth.json` 按字段覆盖 profile 配置行)带着非空 key 时,每轮委派在 argv 上注入一个自定义 provider(`-c model_provider=… -c model_providers.…={base_url, env_key=OPENAI_API_KEY, wire_api=responses}`),key 经进程环境传递——不写 `config.toml`、不读 `auth.json`,网页登录完全不参与;一次性 exec、常驻 app-server、模型目录探测同一套凭据。key 不带 `baseUrl` 时用 OpenAI 官方端点(官方平台 key 不需要中转,内置 provider 读同一个环境变量)。清掉 key(设置卡留空保存)即未认证。
+
+**设置卡「认证」区编辑的就是默认 scope 的 `endpoint-auth.json`**(0600,只存本机;经家族 gateway 的 `endpointAuth`/`configureEndpoint` Remote,会话不在场也能读写),密钥绝不写进 profile 文件,文件名也命中评测契约哈希的凭据拒绝名单、不进条件指纹。旁边的「验证端点并获取模型」按钮对**已保存**的端点跑一次无 token 探测(`GET <baseUrl>/v1/models`,Bearer 头),返回可达性与端点供应的模型列表。文件里还可手写 `"wireApi": "chat"`(卡片不编辑它,保存时保留)适配只支持 chat/completions 的中转。
+
+> **凭据错误的代价是重试时长**——一把失效的 key 会让 CLI 在端点前重试数分钟才报出 401;`/codex status` 的 `rejected` 等级在那一轮 settle 后才出现。重存 key(重写 endpoint-auth.json)即恢复。
+
+> **迁移说明(下一发布线,破坏性变更)**——网页登录整体移除:`/codex login` 不再存在,设备码/浏览器授权随之删除;升级后首次启动会清扫作用域目录里残留的 `auth.json`,避免一份陈旧授权在状态显示未认证时仍悄悄可用。升级前先在设置卡或 profile 行配好 `baseUrl` + `apiKey`(官方平台 key 同样可用),否则升级即未认证。
+>
+> **logout 只清 scope 自己的文件**——`/codex logout` 删除 scope 的 `endpoint-auth.json`;凭据完全来自 profile 配置行时 logout 拒绝并提示去改 profile。
+
 **旧键迁移。** live 轮次统一消费增量输出:旧 `liveMirrorGranularity: event | token` 配置继续兼容读取,但不再影响行为,也不会改变运行中的进程。评测继续保留 exec 驱动;最终内容仍以 provider 完成项为准,包括工具记录和用量。
 
 ### 默认模型(`model`)
@@ -68,11 +82,11 @@ dsh plugin --profile web remove @khorsheed/dsh-local-agent-codex
 
 作用域 `config.toml` 不会被改写——`-m` 每轮覆盖它,文件仍是你编辑的样子。
 
-设置卡「默认模型」修改后续轮次使用的 provider 配置。共享选择器展示当前作用域的模型目录、发现来源和完整性,并保留按需填写模型 ID 的入口。清空选择后跟随有效配置及默认值链。保存不会打断当前轮次,也无需重载;共享选择器不可用时,卡片保留文本输入兜底。成员级模型和推理强度修改使用下文的持久控制面。
+设置卡「可用模型」区维护一份**有序模型短名单**:点「添加模型」从端点当前供应的目录里勾选加入,列表里只会有端点真实供应的模型;拖动行调整顺序。**第一个模型就是默认模型**——每轮委派以它起 CLI(一次性 `codex exec -m`,常驻 app-server 的 `-c model=…`),优先级只低于成员会话级覆盖与委派级指定。列表保存在作用域目录的 `models.json`(每个命名 scope 可各有一份,与端点凭据同一套文件机制),编辑即保存,下一轮委派生效。**留空 = 回退旧链**(下面的 `model` 键 → 作用域 `config.toml` → CLI 内置)。成员级模型和推理强度修改使用下文的持久控制面。
 
-丰富目录读面现已保留原生显示名、隐藏候选和推理选项,遍历分页,并接入 core 缓存与刷新订阅。查询上下文跟随成员的 scope 和 cwd。刷新失败保留最后成功快照并标为过期;配置项和历史建议保留来源标识。共用模型菜单和成员 effort 控制已接入。运行中选择排到下一完整轮次(含工具续跑);core 统一持有当前/待生效配置、撤销与重试,冻结评测成员禁止变更。原生目录候选不等于账号权限证明。
+丰富目录的词汇来自端点本身(`GET <baseUrl>/v1/models`,与「验证端点并获取模型」按钮同一次探测)——本地注册表证明不了端点供应什么,失效的 key 再也不能躲在 CLI 本地列表后面。原生 app-server 的 `model/list` 探测降级为元数据补全,与端点探测并发:它独占显示名、隐藏候选、推理档位与 `isDefault` 编译默认,端点供应的 id 命中注册表即带走这些元数据,只被端点供应的 id 以裸条目列出;原生探测失败只警告一次,端点数据独自成完整答案。端点无凭据、拒绝凭据、状态异常或答非 `/v1/models` 形态时目录带原因空载;传输故障抛错,缓存保留最后一次成功快照并标过期重试(实测 openproxy 短暂 500 后自愈,正是这条语义)。查询上下文跟随成员的 scope 和 cwd。共用模型菜单和成员 effort 控制已接入。运行中选择排到下一完整轮次(含工具续跑);core 统一持有当前/待生效配置、撤销与重试,冻结评测成员禁止变更。原生目录候选不等于账号权限证明。
 
-**委派级的模型优先。**编排器可以经门面 `DelegationCallOptions.model` 给**某一次委派**点名模型,它排在这个键之前(固定顺序:会话覆盖 > 委派记录 > 本键 > 作用域 config > CLI 内置)。首轮请求的值记进委派记录,resume 轮照它重发——resume 不接受 model 参数。常驻模式下带模型的轮次不再被拒绝:它成为该成员的**起始模型**,在 app-server 起进程时绑定;若该成员的常驻 runtime 绑定的是另一个模型,先回收重生(同一 codex 线程经 thread/resume 续上),再以所点模型起新一轮。
+**委派级的模型优先。**编排器可以经门面 `DelegationCallOptions.model` 给**某一次委派**点名模型,它排在这个键之前(固定顺序:会话覆盖 > 委派记录 > 可用模型首项 > 本键 > 作用域 config > CLI 内置)。首轮请求的值记进委派记录,resume 轮照它重发——resume 不接受 model 参数。常驻模式下带模型的轮次不再被拒绝:它成为该成员的**起始模型**,在 app-server 起进程时绑定;若该成员的常驻 runtime 绑定的是另一个模型,先回收重生(同一 codex 线程经 thread/resume 续上),再以所点模型起新一轮。
 
 **成员级切换(作曲器模型选择器)。**成员会话里可以按会话切换模型:一个内存中的会话级覆盖,优先级最高,宿主重启即失。切换在有轮次进行中时被拒绝;空闲时若成员有常驻 runtime 且绑定模型不同,切换即回收该 runtime——下一轮以新模型重生,CLI 会话(rollout)本身延续。一次性(exec)驱动下没有常驻进程,覆盖直接决定下一轮的 `-m`。
 
@@ -80,7 +94,7 @@ dsh plugin --profile web remove @khorsheed/dsh-local-agent-codex
 
 ## 自定义端点
 
-把 Codex 的 LLM 请求路由到你自己的端点:在作用域 `$DSH_HOME/local-agent/codex/config.toml` 里**新增自定义 provider**(内置 provider 不可覆盖、`OPENAI_BASE_URL` 不生效、预置逻辑从不覆盖已存在的 config):
+端点凭据(设置卡/profile 行)是唯一带凭据的路线。仍可在作用域 `$DSH_HOME/local-agent/codex/config.toml` 里**新增自定义 provider**(内置 provider 不可覆盖、`OPENAI_BASE_URL` 不生效、预置逻辑从不覆盖已存在的 config),但它的 `env_key` 读的是子进程环境——宿主 shell 的同名变量会被清洗,只有端点凭据的 key 会随行,所以手工 provider 实际只对**不需要认证**的端点(如本地路由器)有用:
 
 ```toml
 [model_providers.dsh-router]
@@ -89,20 +103,20 @@ base_url = "https://your-router.example/v1"
 model_provider = "dsh-router"
 ```
 
-最后一行为委派选择该 provider;文件其余内容必须保留。
+最后一行为委派选择该 provider;文件其余内容必须保留。端点凭据带 key 时以它为准(argv 上的 provider 覆盖文件的 `model_provider` 选择)。
 
-⚠️ **凭据暴露**:作用域 `auth.json` token 会发送给处理请求的端点——只使用你控制或信任的端点。每次委派在 info 级别记录生效的端点。
+⚠️ **凭据暴露**:端点 key 会发送给处理请求的端点——只使用你控制或信任的端点。每次委派在 info 级别记录生效的端点。
 
-**评测快照(effectiveSettings)。** 本 harness 向注册表声明一份实时读取的公平性设置快照,供评测条件哈希使用:drive(exec/live)、sandbox 策略(插件配置)、推理强度(读作用域 config 的顶层 `model_reasoning_effort`)、端点是否固定(读作用域 config 的自定义 provider,只报主机名)、已配置模型(先看插件配置的 `model` 键——它每轮覆盖文件;没有才读作用域 config 的顶层 `model`;都没有就不给字段)、CLI 版本(`codex --version`,按可执行文件路径+mtime 缓存;探测不到即字段缺位)。`/codex status` 与 `LocalAgentStatus` Remote 附带同一份快照。
+**评测快照(effectiveSettings)。** 本 harness 向注册表声明一份实时读取的公平性设置快照,供评测条件哈希使用:drive(exec/live)、sandbox 策略(插件配置)、推理强度(读作用域 config 的顶层 `model_reasoning_effort`)、端点是否固定(端点凭据优先——scope 的 `endpoint-auth.json` 逐字段覆盖插件配置;没有 key 才读作用域 config 的自定义 provider;只报主机名,key 材料永远不进快照)、已配置模型(先看作用域 `models.json` 的首项,没有才看插件配置的 `model` 键——它每轮覆盖文件;再没有才读作用域 config 的顶层 `model`;都没有就不给字段)、CLI 版本(`codex --version`,按可执行文件路径+mtime 缓存;探测不到即字段缺位)。`/codex status` 与 `LocalAgentStatus` Remote 附带同一份快照。
 
 ## Compatibility
 
-- npm 发布线(`@deepseek-ai/dsh@0.1.5-rc.1`):✅ 公开 API 兼容。生成中的内容走 local-agent 瞬时 Remote 与公开 Conversation 节点;增量耐久检查点负责恢复,最终原生消息保留转写与用量语义。端到端延迟验收由 room 协调者提案跟踪。minHost 0.1.5-rc.1,更旧宿主请停留在旧发布线。
-- 源码线(deepseek-harness master):✅(verifiedHost: 0.1.5-rc.1)
+- npm 发布线(`@deepseek-ai/dsh@0.1.5-rc.1`):✅ 公开 API 兼容。生成中的内容走 local-agent 瞬时 Remote 与公开 Conversation 节点;增量耐久检查点负责恢复,最终原生消息保留转写与用量语义。端到端延迟验收由 room 协调者提案跟踪。minHost 0.1.5-rc.1,更旧宿主请停留在旧发布线。设置卡渲染为 core「本机 Agent 委派」家族卡的一节（Plugins 页 core 的 `plugins.item` 条目，0.1.7-alpha.1+；旧版 core 上回落为本包自己的 `plugins.item` 卡），`configForms.whileServed` 随宿主服务的 `local-agent-codex` 命名空间挂载;0.1.5 线不再呈现卡片(宿主删除了 `settings.plugin.item` 席位),其余表面不变。
+- 源码线(deepseek-harness master):✅(verifiedHost: 0.2.1-rc.1)——host-021 波对 0.2.1-rc.1 树全量 build+test 绿;委派迁移到 `ctx.subagents.startActivation`(受管 activation),run.id 改为每次执行唯一。
 
 ## 已知限制
 
-- **登录需要一次浏览器授权**——`/codex login` 自动打开授权页,CLI 追问 code 时以 `/codex code <code>` 粘贴回来;没有 API key 路径。
+- **没有网页登录**——认证只有端点凭据一条路(设置卡/profile 行,官方平台 key 与中转 key 均可);ChatGPT 订阅的 OAuth 路径不在本包。
 - **`codex exec` 非交互运行**——沙箱策略本需审批的动作会被拒绝而非弹提示;常驻模式下审批类请求同样按无人值守策略自动谢绝(cancel/decline)。见 `sandbox` 配置。
 - **命名 scope 只走一次性 exec**——常驻 app-server 绑定缺省作用域目录,带 scope 的委派不进 live。
 - **headless 注意**——`/codex` 命令需要 Web 会话;headless 仍可通过挂载工具行的组合进行委派。
@@ -114,9 +128,9 @@ model_provider = "dsh-router"
 
 **命名 scope。** `/codex login --scope <名>` 会在 `<homesRoot>/codex@<名>` 里另开一份作用域目录:目录建立时自动跑同一份 `config.toml` provision(把凭据存储钉在文件而非 macOS keychain),因此该 scope 的登录落在它自己的 `auth.json` 里。带 scope 的委派用它跑 `codex exec`、把 rollout 写进它、从它回读;只走 exec——常驻 app-server 绑的是缺省作用域目录。
 
-**bundle 组成。** patch 注册 `codex` harness(`CODEX_HOME` 作用域目录、PTY 登录、rollout 文件会话记录)——恰好一行 provider 行;`subagent_codex` 工具自家族折叠起是本包的 `./tool` 组合入口,由点名它的 agent 预设按会话授予(dev 预设的 `tool-subagent-codex-local` 行),不再挂 profile 根。家族沿用官方模型名 `subagent_codex`:官方 preset 的同名行本就 `disabled: true`,patch 对 profile 根的同名行再禁一次,社区安装永远不会注册出两个 `subagent_codex`;刻意在自有 preset 层重新启用官方行的用户会得到响亮的重名冲突,按设计必须二选一。`codex-local` provider 在该作用域目录下 spawn `codex exec`(live 未启用时的一次性驱动)。浏览器半部分随本包 `./client` 提供:Codex 设置卡组合家族 core 的共享 `ProviderAuthBlock`,独立安装落在 Plugins 页的包详情视图(`plugins.bundle.config`,按包名派发),作为家族 bundle 成员安装落在 bundle 详情页的行级配置入口(`plugins.row.config`),0.1.5 落在 设置 → 插件 → 插件配置(`settings.plugin.item`,按设置命名空间派发);卡片写入经绑定的 settingsScope 热生效,不用重载。core 本身来自声明为依赖的 `@khorsheed/dsh-local-agent`。
+**bundle 组成。** patch 注册 `codex` harness(`CODEX_HOME` 作用域目录、PTY 登录、rollout 文件会话记录)——恰好一行 provider 行;`subagent_codex` 工具自家族折叠起是本包的 `./tool` 组合入口,由点名它的 agent 预设按会话授予(dev 预设的 `tool-subagent-codex-local` 行),不再挂 profile 根。家族沿用官方模型名 `subagent_codex`:官方 preset 的同名行本就 `disabled: true`,patch 对 profile 根的同名行再禁一次,社区安装永远不会注册出两个 `subagent_codex`;刻意在自有 preset 层重新启用官方行的用户会得到响亮的重名冲突,按设计必须二选一。`codex-local` provider 在该作用域目录下 spawn `codex exec`(live 未启用时的一次性驱动)。浏览器半部分随本包 `./client` 提供:Codex 设置卡组合家族 core 的共享 `ProviderAuthBlock`,渲染为 core「本机 Agent 委派」家族卡的一节——宿主服务 `local-agent-codex` 命名空间时经 `configForms.whileServed` 挂载,独立安装、家族 bundle、模式包同一节(旧版 core 上回落为本包自己的 `plugins.item` 卡);卡片写入经绑定的 settingsScope 热生效,不用重载。core 本身来自声明为依赖的 `@khorsheed/dsh-local-agent`。
 
-**登录与凭据。** `/codex login` 经宿主 subprocess seam 在伪终端里跑 `codex login`——CLI 自己起 localhost 回调服务并打开浏览器,这是第一类流程;命令回复附带从输出里抓取的授权 URL 作兜底链接,CLI 追问 code 时用户以 `/codex code <code>` 粘贴(写入子进程 stdin)。完成由监听作用域目录的凭证 watch 判定:`auth.json` 出现且时间戳新于 watch 起点——残留的旧凭证不会被误认成新登录。无浏览器的远程终端可以手动以 `CODEX_HOME` 指向作用域目录跑 `codex login --device-auth`,凭据落在同一份 `auth.json`。首次启动写入一份最小 `config.toml`,固定 `cli_auth_credentials_store = "file"`——Codex 默认的 `auto` 会解析到 macOS keychain,把凭据泄漏到作用域目录之外并使本包的 `auth.json` 存在性检查失效;已存在的 config 保持不动。`/codex logout` 删除作用域 `auth.json`,之后重新登录即可换账号。
+**凭据。** 端点凭据制,没有登录流程:scope 的 `endpoint-auth.json`(0600)按字段覆盖 profile 配置行的 `baseUrl`/`apiKey`,解析结果带 key 时每轮在 argv 注入自定义 provider(`wire_api=responses`,key 经进程环境传递,实测 codex-cli 0.163.0 全新 scope 下无需任何登录文件直通中转)。首次启动写入一份最小 `config.toml`,固定 `cli_auth_credentials_store = "file"`——Codex 默认的 `auto` 会解析到 macOS keychain,在作用域目录里手跑 `codex login` 会把凭据泄漏到目录之外;已存在的 config 保持不动。每次启动还会清扫网页登录时代残留的 `auth.json`——本包不再读取它,留着只会让一份陈旧授权在状态显示未认证时仍悄悄可用。`/codex logout` 删除作用域 `endpoint-auth.json`,之后重新配置即可换 key。
 
 **会话记录。** `/codex sessions` 列出作用域目录的 `sessions/YYYY/MM/DD/rollout-*.jsonl` 文件——仅本插件委派产生的会话,绝不含你的私人会话。会话头部的记录入口(家族 core 的客户端提供)把同一份列表收窄到 `workDir` 与当前会话 cwd 一致的记录。