dsh-codex-connect 0.1.0-alpha.4.51 → 0.1.0-alpha.4.52

package/INSTALL.md

@@ -1,10 +1,10 @@
 # Installation Runbook for CLI Agents
 
-Published Alpha 4.50 is verified with either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` and pi-ai `0.85.1`, using a consistent host package set. Earlier DSH pairings retain their separately published plugin versions below.
+Published Alpha 4.51 is verified with either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` and pi-ai `0.85.1`, using a consistent host package set. Earlier DSH pairings retain their separately published plugin versions below.
 
 Install `dsh-codex-connect` into one requested DeepSeek Harness profile without changing its current default model, search route, global configuration, or OAuth state.
 
-Channel snapshot on 2026-09-26: npm `alpha` points to `0.1.0-alpha.4.50`; `latest` remains `0.1.0-alpha.4.47`. Use the exact-version command for the installed DSH version; moving npm tags are not compatibility guarantees.
+Channel snapshot on 2026-09-28: npm `alpha` points to `0.1.0-alpha.4.51`; `latest` remains `0.1.0-alpha.4.50`. Use the exact-version command for the installed DSH version; moving npm tags are not compatibility guarantees.
 
 ## Safety requirements
 
@@ -30,12 +30,20 @@ Check `dsh --version` before changing the requested profile. Use `dsh --help` to
 | `0.1.5-alpha.1` | `0.1.0-alpha.4.41` |
 | `0.1.5-rc.1` | `0.1.0-alpha.4.41` |
 | `0.1.5-rc.2` | `0.1.0-alpha.4.41` |
-| `0.1.7-rc.1` | `0.1.0-alpha.4.50` |
-| `0.1.7-rc.2` | `0.1.0-alpha.4.50` |
+| `0.1.7-rc.1` | `0.1.0-alpha.4.51` |
+| `0.1.7-rc.2` | `0.1.0-alpha.4.51` |
 
 If your exact DSH version is unknown or not listed, preserve the installed host, report that the combination is unverified, and verify it before making installation changes. A missing record does not prove incompatibility, and the catalog's latest verified DSH version is not the latest upstream release. Do not recommend upgrading or downgrading DSH merely to match a row. Investigate any specific failure and seek verification of the installed combination. Do not blindly install `dsh-codex-connect@alpha`: `alpha` is a moving tag, not a compatibility guarantee. Do not infer support for newer DSH versions from these rows.
 
-Alpha 4.50 requires one consistent DSH `0.1.7-rc.1` or `0.1.7-rc.2` plugin API and pi-ai `0.85.1`; its direct runtime imports include `@deepseek-ai/schemastery` `3.18.4` and `@earendil-works/pi-ai` `0.85.1` so an isolated profile need not already provide them. Node.js remains `^22.19.0 || >=24.0.0`. It does not support the older DSH rows. Alpha 4.41 remains the choice for DSH `0.1.2-rc.1` with pi-ai `^0.84.2`, or `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` with pi-ai `0.85.1`. Mixed host versions and other DSH/pi-ai combinations remain unverified. Alpha 4.25 remains the verified choice for DSH `0.1.2-alpha.5`, Alpha 4.23 for DSH `0.1.2-alpha.2`, Alpha 4.21 for DSH `0.1.1-rc.2`, and Alpha 4.14 for DSH `0.1.0-rc.7`. Changing DSH is a separate operation requiring the user's explicit request; a plugin update request does not authorize it. The repository's `pnpm --silent run check:compatibility` remains a strict development/release dependency gate, not a recommendation to change a user's host.
+Alpha 4.51 requires one consistent DSH `0.1.7-rc.1` or `0.1.7-rc.2` plugin API and pi-ai `0.85.1`; its direct runtime imports include `@deepseek-ai/schemastery` `3.18.4` and `@earendil-works/pi-ai` `0.85.1` so an isolated profile need not already provide them. Node.js remains `^22.19.0 || >=24.0.0`. It does not support the older DSH rows. Alpha 4.41 remains the choice for DSH `0.1.2-rc.1` with pi-ai `^0.84.2`, or `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` with pi-ai `0.85.1`. Mixed host versions and other DSH/pi-ai combinations remain unverified. Alpha 4.25 remains the verified choice for DSH `0.1.2-alpha.5`, Alpha 4.23 for DSH `0.1.2-alpha.2`, Alpha 4.21 for DSH `0.1.1-rc.2`, and Alpha 4.14 for DSH `0.1.0-rc.7`. Changing DSH is a separate operation requiring the user's explicit request; a plugin update request does not authorize it. The repository's `pnpm --silent run check:compatibility` remains a strict development/release dependency gate, not a recommendation to change a user's host.
+
+### Alpha 4.51 published maintenance delivery
+
+The current recommendation follows [PR #283](https://github.com/franksong2702/dsh-codex-connect/pull/283), successful [exact-main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36362680011), and independent final source review of the diagnostic type/lifecycle repair. Frozen local checks passed 127 files / 1,466 tests, Chromium 73 tests, and stock rc.1/rc.2 same-artifact installation/runtime checks. Experimental defaults and Task pause remain unchanged; no draft metrics/evaluation feature is included.
+
+The [original protected publication](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36363043413) uploaded npm successfully but failed public readback. It was not rerun. Recovery-only verification matched the public package byte-for-byte to the original artifact (SHA-256 `6d8ffe3b9335e0f874592f6d5f67d2fe872e809a24a4ae4e2c1d8f14e29857e6`), then created only the missing tag and [prerelease](https://github.com/franksong2702/dsh-codex-connect/releases/tag/v0.1.0-alpha.4.51). Final independent verification returned `already-complete`: version, alpha, tag and release match commit `2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a`; latest remains 4.50. See [the publication record](docs/experiments/evidence/alpha-451-publication.json). No duplicate npm upload, old-tag movement, daily-service upgrade or new real-model/image acceptance occurred.
+
+### Historical Alpha 4.50 delivery evidence
 
 The Alpha 4.50 recommendation follows [PR #275](https://github.com/franksong2702/dsh-codex-connect/pull/275), [exact-release main CI](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36222707376) and a successful [protected publication run](https://github.com/franksong2702/dsh-codex-connect/actions/runs/36222974006) at `6baa422b7b9cd513340948f659b51b0b9d76a724`. The same candidate passed unmodified rc.1 and rc.2 isolated installations without exemptions; Chromium passed 73 tests on each host. The rc.1 frozen full check passed 1,452 tests; rc.2 source types and focused image/auth/transport/compaction suites passed. An independent source reviewer found a mandatory UI-peer consistency gap; five red/green controls covered the correction before the final source review passed. See [the exact scope and evidence](docs/experiments/dsh-017rc2-compatibility.md).
 
@@ -92,10 +100,10 @@ Alpha 4.33 omits the `modelErrors` profile field required by RC model packages,
    dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.41
    ```
 
-   For either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, use Alpha 4.50:
+   For either exact DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, use Alpha 4.51:
 
    ```sh
-   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.50
+   dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.51
    ```
 
    For DSH `0.1.2-alpha.5`, use Alpha 4.25:
@@ -106,7 +114,7 @@ Alpha 4.33 omits the `modelErrors` profile field required by RC model packages,
 
    If npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.21'` only for the DSH `0.1.1-rc.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.23'` only for the DSH `0.1.2-alpha.2` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.25'` only for the DSH `0.1.2-alpha.5` combination, `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.41'` only for the DSH `0.1.2-rc.1`, `0.1.5-alpha.1`, `0.1.5-rc.1`, and `0.1.5-rc.2` combinations, or `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.46'` only for DSH `0.1.7-rc.1`.
 
-   For the current DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, if npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.50'`.
+   For the current DSH `0.1.7-rc.1` or `0.1.7-rc.2` pairing, if npm is unavailable after the matching GitHub prerelease is created, use `dsh plugin --profile web add 'github:franksong2702/dsh-codex-connect#v0.1.0-alpha.4.51'`.
 
 3. Run `dsh web --help` once to compose the installed profile without starting the server. DSH `0.1.2-rc.1` prepares profile plugin dependency fallback during this step.
 4. Run `dsh --profile web --dump-config` and require exactly one `llm-openai-codex` row loading `dsh-codex-connect`.

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   git hash-object README.md docs/README.zh.md
-README.md: 042cbc25138136fb6086b74b9174e560c7dcdd26
-docs/README.zh.md: 394fa85a66eccbdee1adbfe2b859dd51b73ab785
+README.md: 7b9aa304f7d633e074693082becafbb1c8bd7df4
+docs/README.zh.md: 70da4c6c973097893074cc57e5b7f8e1b411c535

package/README.md

@@ -16,19 +16,21 @@ This guide describes the published pairing below. Check `dsh --version` first an
 
 | Requirement | Verified pairing |
 |---|---|
-| Codex Connect | `0.1.0-alpha.4.50` |
+| Codex Connect | `0.1.0-alpha.4.51` |
 | DeepSeek Harness | `0.1.7-rc.1` or `0.1.7-rc.2` (consistent package set) |
 | Node.js | `^22.19.0 \|\| >=24.0.0` |
 | Account | ChatGPT OAuth with access to the requested Codex model; availability is decided by OpenAI |
 
-As of 2026-09-26, npm `alpha` points to 4.50 while `latest` remains 4.47; publishing this release did not promote `latest`. Use the exact version below for this DSH pairing; a moving npm tag is not a compatibility guarantee for other hosts.
+As of 2026-09-28, npm `alpha` points to 4.51 while `latest` remains 4.50; this maintenance publication did not promote `latest`. Use the exact version below for this DSH pairing; a moving npm tag is not a compatibility guarantee for other hosts.
+
+Alpha 4.51 prevents malformed diagnostic event types from interrupting responses and forwards cancellation/network errors through unread or paused responses. It does not include the draft request-metrics or evaluation functionality.
 
 On stock DSH `0.1.7-rc.1` and `0.1.7-rc.2`, the package is installation/runtime-regression verified; Task controls remain paused: activation is rejected and fresh Sessions do not show them. Migration of earlier Task grants across a Harness upgrade is not verified. Older supported pairings and their task behavior are documented in [Installation and upgrades](INSTALL.md).
 
 ### 1. Install
 
 ```sh
-dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.50
+dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.51
 dsh web
 ```
 

package/docs/README.zh.md

@@ -16,19 +16,21 @@ Codex Connect 为标准 Harness agent loop 添加 `openai-codex` 模型提供方
 
 | 要求 | 已验证组合 |
 |---|---|
-| Codex Connect | `0.1.0-alpha.4.50` |
+| Codex Connect | `0.1.0-alpha.4.51` |
 | DeepSeek Harness | `0.1.7-rc.1` 或 `0.1.7-rc.2`（包版本必须一致） |
 | Node.js | `^22.19.0 \|\| >=24.0.0` |
 | 账户 | 通过 ChatGPT OAuth 使用所请求的 Codex 模型；可用性由 OpenAI 决定 |
 
-截至 2026-09-26，npm `alpha` 指向 4.50，`latest` 仍为 4.47；本次发布没有提升 `latest`。安装此 DSH 组合请使用下方精确版本命令；会移动的 npm tag 不保证其他宿主版本的兼容性。
+截至 2026-09-28，npm `alpha` 指向 4.51，`latest` 仍为 4.50；本次维护发布没有提升 `latest`。安装此 DSH 组合请使用下方精确版本命令；会移动的 npm tag 不保证其他宿主版本的兼容性。
+
+Alpha 4.51 修复异常诊断事件类型导致请求中断，以及未读取／暂停读取时取消或网络错误未及时传到外层的问题。本版本不包含草稿中的请求计量或评测功能。
 
 该安装包已通过原版 DSH `0.1.7-rc.1` 和 `0.1.7-rc.2` 的安装及运行回归验证；Task 控件仍暂停：激活请求会被拒绝，新 Session 不显示这些控件。跨 Harness 升级迁移旧任务授权尚未验证。较旧组合及其任务行为见[安装与升级](../INSTALL.md)。
 
 ### 1. 安装
 
 ```sh
-dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.50
+dsh plugin --profile web add dsh-codex-connect@0.1.0-alpha.4.51
 dsh web
 ```
 

package/docs/agent-notes/request-metrics-runtime-candidate.md

@@ -0,0 +1,27 @@
+# Request metrics: standalone runtime candidate history
+
+## Scope
+
+This candidate is based on maintenance main `2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a`. It extracts only the opt-in metrics collector, offline reporting CLI, minimal adapter/backend integration and tests. It excludes the internal evaluation runner, task catalog, local project documents, private journals and machine paths. The unchanged package version identifies the base release, not publication of these new features.
+
+Collection is disabled when no metrics directory is configured. It records bounded local operational metadata, preserves missing usage as unknown, and never calculates subscription cost or uploads telemetry. No UI, Task activation, account changes, real experiment or deployment is included. See [the measurement contract](../request-metrics.md).
+
+## Review
+
+An independent ephemeral GPT-6 Astra process reviewed the complete selected metrics/diagnostic/backend sources and integrations. Final static verdict: PASS, no findings. The exact reviewed file bytes match this extraction; see [the original report and fingerprints](../experiments/evidence/request-metrics-runtime-review-20260928.json). This does not certify unprovided dependencies or replace candidate installation tests.
+
+Earlier review findings were reproduced and repaired: untrusted SSE type coercion, enum coercion, invalid journal lifecycle/pairing, diagnostic unread-reader error forwarding, and pending-read cancellation misclassification. The first diagnostic repairs are already isolated in the maintenance base. The candidate retains the original governor policy of prompt logical cancellation, not a new physical socket cleanup guarantee; that scope and the review disposition remain explicit.
+
+## Remaining gate
+
+Frozen install, full check, Chromium and the exact rc.1/rc.2 same-artifact installation matrix are required on this standalone tree. A draft PR makes this scope reviewable; it does not authorize merging the entire internal research archive or publishing metrics under the existing version. No efficiency, token-saving or autonomous-delegation benefit is claimed.
+
+## Standalone verification completed
+
+On the extracted candidate, frozen install and full check passed (131 files / 1,529 tests); Chromium passed (13 files / 73 tests). Both stock DSH rc.1 and rc.2 passed the same-artifact installed runtime checks with defaults unchanged. The tested archive SHA-256 is `43d87c178d16792d674ce3878dc8ab3b9f98541145a91aaae6e16fe61d6f1a9d`; it predates only the final evidence-note update and is not the published 4.51 archive. Existing image/compaction paths and the installed metrics checker were exercised with synthetic responses. No real experiment or account acceptance was run.
+
+At that historical checkpoint the product remained a draft, with no new release number or daily service installation. The promotion section below and current PR record supersede that release status; the recorded test/archive identity remains historical.
+
+## Product promotion — 2026-09-28
+
+The maintainer approved advancing this isolated product scope. Alpha 4.52 is now prepared from the reviewed runtime and current main documentation, with a new independent static source review (no blocker), public English/Chinese operational guides, and no internal evaluation runner. Historical candidate evidence above remains unchanged. Current exact-version checks and release outcome are recorded in the PR and release-readiness record; preparation is not publication. No automatic collection, Task activation or daily-service change is included.

package/docs/experiments/evidence/alpha-451-publication.json

@@ -0,0 +1,41 @@
+{
+  "schemaVersion": 1,
+  "checkedAt": "2026-09-28",
+  "version": "0.1.0-alpha.4.51",
+  "channels": {
+    "latest": "0.1.0-alpha.4.50",
+    "alpha": "0.1.0-alpha.4.51"
+  },
+  "tagCommit": "2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a",
+  "release": {
+    "isDraft": false,
+    "isPrerelease": true,
+    "publishedAt": "2026-09-28T00:46:17Z",
+    "tagName": "v0.1.0-alpha.4.51",
+    "targetCommitish": "2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a",
+    "url": "https://github.com/franksong2702/dsh-codex-connect/releases/tag/v0.1.0-alpha.4.51"
+  },
+  "originalRun": "36363043413",
+  "originalRunConclusion": "failure after npm publication, at public readback",
+  "recovery": {
+    "status": "recovered",
+    "version": "0.1.0-alpha.4.51",
+    "runId": "36363043413",
+    "sha": "2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a",
+    "sha256": "6d8ffe3b9335e0f874592f6d5f67d2fe872e809a24a4ae4e2c1d8f14e29857e6",
+    "npmRepublished": false,
+    "tagsPromoted": false,
+    "releaseId": 397876473
+  },
+  "finalReadOnlyVerification": {
+    "status": "already-complete",
+    "version": "0.1.0-alpha.4.51",
+    "runId": "36363043413",
+    "sha": "2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a",
+    "sha256": "6d8ffe3b9335e0f874592f6d5f67d2fe872e809a24a4ae4e2c1d8f14e29857e6",
+    "npmRepublished": false,
+    "tagsPromoted": false,
+    "releaseId": 397876473
+  },
+  "dailyServicesChanged": false
+}

package/docs/experiments/evidence/request-metrics-runtime-review-20260928.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": 1,
+  "recordedAt": "2026-09-28",
+  "scope": "M1 opt-in local request metrics only",
+  "base": "2ac612385ea3c3fcfc1078dc18619d7b1dc49b9a",
+  "reviewerModel": "gpt-6-astra",
+  "ephemeralIndependentProcess": true,
+  "inputSha256": "042bc8e326ace2364ce0272ee24b9d9a7a6d17f27871f7cc23fedddd2eb31ff5",
+  "reportSha256": "ae64ddccd26a24568f79e90314311f7ef061f3ceab41e17e14e021692dfa06bc",
+  "reviewedSourceDigests": {
+    "src/request-metrics.ts": "b54d634b5a8cdd6fd563126da6bab30d66f92fa14c2dcacc62986bb871613531",
+    "src/request-metrics-report.ts": "654e16dff53e265315d63364a08276835b99a56d9a43f7452b173a24dd3b8781",
+    "src/request-metrics-cli.ts": "58f8e282a4c879da41b63b3761bf0c2a335284d1796a711d12ba266f52cb6af6",
+    "src/backend-request.ts": "ed1183c9129f17c50cac07ff3e0708441e795f40e79f9de169ca57748bf4c010",
+    "src/request-diagnostics.ts": "48d2b83f2ef0166296c3ca9d817c0f784c913579c1f872e3e4a984f10bb5f768",
+    "tests/metrics-pending-cancel.spec.ts": "c936380765d73dfb18a5d2f849e1f0081042bdfe8e687a1b0c87d59d9221e641",
+    "tests/metrics-response-lifecycle.spec.ts": "bd00752aebfd8400e843d931f165cd702aa04f59af5ab811f70e11b7c7c4b8db",
+    "tests/request-metrics-review.spec.ts": "c479d1da7cbeafe5c01c129699c61c16725c4807b456adbbf135dcb5ad916886",
+    "docs/request-metrics.md": "4ac1cae37431c67c5637d2d6acce54421511cc71ed27a931793872a021533f2b"
+  },
+  "review": {
+    "verdict": "PASS",
+    "findings": [],
+    "residual_limits": [
+      "结论仅覆盖所提供代码、集成差异、文档和基线；未调用工具、访问网络或执行测试。测试源码不构成通过证据。",
+      "所示解析与聚合逻辑检查字段类型、重复记录、同文件先 start 后 finish 配对及 collection 生命周期；允许未完成请求和明确披露的部分尾行。日志不是经过认证的完整消费凭证。",
+      "响应观察未发现新增的字节改写或取消分类回归；真实传输、宿主集成及运行时行为仍未经执行验证。",
+      "所示持久化路径未发现直接写入请求体、响应内容或凭据的代码；未提供的 backend-request-policy.ts 中 clientRequestId 的生成与保留规则不在本次核验范围内。会话哈希不是匿名化，Windows ACL 也未校验。"
+    ],
+    "prior_finding_disposition": {
+      "status": "non-blocking",
+      "description": "接受维护者的处置。信号 abort 和响应 hook 失败后请求取消、随即释放逻辑 admission 的行为已存在于所提供基线。当前 backend-request.ts:85-90、252-256 保留该政策，与 docs/request-metrics.md:54-58 明确声明的逻辑请求契约一致；未发现其新增物理连接清理保证或构成指标回归。",
+      "explicit_consumer_cancel": "backend-request.ts:102、110-115 使用 cancelling 标记抑制取消产生的 pending-read 合成 EOF，并在清理结束后记录一次 cancelled；若期间发生信号 abort，则按文档提前结束逻辑请求。此前观察到的 provider terminal 仍按 request-metrics.ts:236-239 保持优先。",
+      "validation_needed": "执行所提供的取消和生命周期测试以验证运行时行为；本次静态审查不声称这些测试已通过。"
+    }
+  },
+  "runtimeFilesMatchReviewedSources": true,
+  "candidateValidation": {
+    "fullCheck": {
+      "files": 131,
+      "tests": 1529,
+      "passed": true
+    },
+    "chromium": {
+      "files": 13,
+      "tests": 73,
+      "passed": true
+    },
+    "matrix": {
+      "sameArtifact": true,
+      "hosts": [
+        "0.1.7-rc.1",
+        "0.1.7-rc.2"
+      ],
+      "artifactSha256": "43d87c178d16792d674ce3878dc8ab3b9f98541145a91aaae6e16fe61d6f1a9d",
+      "defaultsUnchanged": true,
+      "scope": "standalone draft candidate, not the published base package; archive before final evidence-note updates"
+    }
+  },
+  "releaseStatus": "unpublished draft; package version follows base, not release identity",
+  "realAcceptanceRequests": 0
+}

package/docs/reference.i18n.yaml

@@ -1,4 +1,4 @@
 # Bilingual-pair consistency record for the operational reference. Re-record with:
 #   git hash-object docs/reference.md docs/reference.zh.md
-docs/reference.md: 824fad33dad0fe6e3b1bb7ab5ec10629e5d31459
-docs/reference.zh.md: ebd88277a1177598016e51566aabbee78f7a46b0
+docs/reference.md: 0700f6001d8ffb5fbc029ff24039229c04cabe98
+docs/reference.zh.md: a4630017b51cfe8087e2f420d040c3404c8638c0

package/docs/reference.md

@@ -147,6 +147,8 @@ The main plugin options are:
 | `searchMode` | `cached` | `cached`, `indexed`, or `live` |
 | `searchContextSize` | `medium` | `low`, `medium`, or `high` |
 | `searchMaxOutputTokens` | `10000` | Positive integer output budget for search |
+| `requestMetricsDirectory` | absent / off | Startup-only private absolute directory for [local request evidence](request-metrics.md); no telemetry upload |
+| `requestMetricsMaxBytes` | `16777216` | Startup-only per-process journal cap, integer `4096`–`67108864`; no directory means no collection |
 
 `contextWindowOverrides` changes the client budget, not OpenAI's server capacity. Unknown model ids and values above the plugin's documented configuration ceiling fail explicitly. Use `null` for the whole field to mask inherited overrides, or `null` for one model to restore its catalog default while preserving other entries. Leave room for output and protocol overhead, and treat larger values as deployment-specific experiments rather than entitlement evidence. [Alpha design](design.md) documents the ownership and persistence rules.
 

package/docs/reference.zh.md

@@ -147,6 +147,8 @@ Alpha 4.49 中，完整 `attachment` 选择器匹配到实际用户上传记录
 | `searchMode` | `cached` | `cached`、`indexed` 或 `live` |
 | `searchContextSize` | `medium` | `low`、`medium` 或 `high` |
 | `searchMaxOutputTokens` | `10000` | 搜索使用的正整数输出预算 |
+| `requestMetricsDirectory` | 不设置／关闭 | 启动配置中的私有绝对路径，记录[本地请求计量](request-metrics.zh.md)，不上传遥测 |
+| `requestMetricsMaxBytes` | `16777216` | 每进程单日志上限，整数 `4096`–`67108864`；不配置目录则不采集 |
 
 `contextWindowOverrides` 修改的是客户端预算，不是 OpenAI 服务端容量。未知模型 ID 或超过插件文档配置上限的值会明确失败。将整个字段设为 `null` 可屏蔽继承的全部覆盖值；将单个模型设为 `null` 可恢复其目录默认值，同时保留其他条目。请为输出和协议开销预留空间，并把更大的数值视为特定部署的实验，不能当作账户权限证据。所有权与持久化规则见 [Alpha 设计](design.zh.md)。
 

package/docs/request-metrics.md

@@ -0,0 +1,64 @@
+# Local request metrics
+
+English | [中文](request-metrics.zh.md)
+
+This source adds opt-in, local-only HTTP-attempt evidence and a boot-free report command. It does not enable task orchestration, change model requests, call a model for measurement, or convert API prices to subscription quota. This guide describes the Alpha 4.52 candidate; Alpha 4.51 and earlier packages do not contain this feature. A candidate is not publication evidence.
+
+The internal evaluation program is not part of the installed package. This feature supplies evidence for diagnostics and separately designed comparisons; it is not a task-quality evaluator, a user-facing metrics panel or a proven efficiency improvement.
+
+## Enable in an isolated profile
+
+Add these fields to the existing `llm-openai-codex` plugin's `config` in the intended profile, then restart that profile through its normal lifecycle. Do not add a second copy of the plugin. These are startup configuration fields, not fields in the browser settings card.
+
+```yaml
+requestMetricsDirectory: /absolute/private/path/codex-request-metrics
+requestMetricsMaxBytes: 16777216
+```
+
+The byte limit must be an integer from `4096` to `67108864`; the default is `16777216` (16 MiB). Setting only this limit does not enable collection. Use the native absolute path syntax on each OS; for example, a Windows YAML single-quoted value may be `'C:\Private\CodexMetrics'`. Configure access so only the intended account can read the directory.
+
+Omitting `requestMetricsDirectory` disables recording. The directory must be absolute and, on POSIX, owner-only; a new directory is created with mode `0700`. Each process creates its own exclusive `requests-<uuid>.jsonl` with mode `0600`. Windows uses the directory's inherited ACL, which the plugin does not validate or change. Choose a private, nonsynchronized directory. Removing the configuration and restarting stops new collection without deleting evidence.
+
+The size limit applies to one process journal, not the entire directory. Reaching the limit or encountering a write failure stops recording, warns once, and attempts to retain a stop marker; model execution continues. Crashes, disk failures and recordings disabled between processes can leave incomplete evidence. Retention and deletion are manual: no files are automatically removed.
+
+## Read without network or credentials
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect metrics --file /absolute/private/path/codex-request-metrics/requests-UUID.jsonl --json
+```
+
+Repeat `--file` to combine explicitly selected journals across restarts. Repeat `--session <DSH-session-id>` to select known sessions, including any children you explicitly want to include. Without a session filter, unattributed auxiliary traffic is included. The standalone equivalent is `node lib/bin.js metrics --file <journal> --json`; omitting `--json` prints a human-readable summary. The command reads only the named journal files, never credentials, and makes no network requests. Duplicate inputs, conflicting records and invalid schemas fail instead of silently doubling or dropping spend. A partial final line is disclosed and excluded. The version 1 journal format requires one collection-start header per file; request records before that header or after a closed/stopped marker, cross-file request pairing, non-string enum fields and impossible terminal-state changes are rejected. These checks do not make a journal an authenticated proof of task completion.
+
+## What the numbers mean
+
+Every admitted backend HTTP dispatch receives a start record immediately before fetch. A finish record reports response consumption, cancellation or transport failure, not merely header arrival. An observed terminal provider result takes precedence over subsequent reader cancellation or transport cleanup; cancellation before a terminal result remains cancellation. A start without a finish is pending or interrupted, never a successful zero-token request. Stream bytes, headers, retry policy, admission, cancellation and provider identity remain unchanged.
+
+Adapter calls carry an independent call id, a SHA-256 session grouping key, selected model/effort and conversation/compaction/session-title purpose. Multiple HTTP attempts in the same adapter call are reported as additional attempts within that call. Tool-level or task-level retries across calls are not inferred. Standalone search, images, quota and Auto-review are counted by governor lane; they remain unattributed when no adapter scope exists. This is not a complete task ledger, a parent-child graph, user-turn counting or a task-quality result.
+
+Usage is observed directly from bounded Responses terminal SSE events or JSON usage, before provider libraries can default missing counters to zero. Reports retain observed subtotals and unknown-attempt counts for input, cached input, cache writes, output and reasoning output. Responses input includes cached input; reasoning is a subset of output and is never added again. Missing, invalid and internally inconsistent fields remain unknown. Unsupported payload formats or oversized terminal frames can therefore produce unknown usage even when the provider library displays a value.
+
+Cache hit ratio is the sum of cached input divided by the sum of input for attempts that report both, with the excluded-attempt count alongside it. It is not the average of request percentages. Latency covers HTTP dispatch through body completion; it excludes admission/authentication wait, and summed concurrent durations are not task wall-clock time.
+
+Neither API dollar cost nor subscription quota cost is calculated. No unknown price or missing usage is treated as free. Reports exclude other providers, OAuth, public image downloads, pre-dispatch failures and past requests before collection. A completed provider response does not imply an accepted task. Even a cleanly closed journal cannot prove that every request in a task was observed.
+
+Only allowlisted numerical/status metadata and bounded model identifiers are written. No request bodies, response content, tool arguments, system prompts, headers, credential values, account ids or server response ids are retained. Session hashes support correlation, not anonymization; treat journals as private operational data.
+
+The Codex streaming caller explicitly declares SSE for successful responses whose media type is absent. This observation hint does not modify the response, override an explicit media type or apply to error responses. Other callers without a protocol hint retain unknown usage for unsupported or missing media types.
+
+## Troubleshooting and stopping collection
+
+If no journal appears, check that the directory is configured on the intended profile and that the profile restarted. On POSIX, the existing directory must be private (no group/other permission bits), writable, and a real directory rather than a symlink. A fixed warning means recording stopped; it does not mean the model request failed. Correct the path/permissions or disk condition before restarting. Do not share private journals publicly.
+
+A `stoppedEarly` value or partial tail means the evidence is incomplete. Reaching the per-file limit does not rotate or delete files, and restarting creates another file; plan retention outside the plugin. To disable, remove `requestMetricsDirectory` from the effective startup config and restart the intended profile. Existing journals remain for explicit export or manual deletion.
+
+If the report rejects a journal, use the original regular JSONL files from the configured directory. Do not splice multiple processes into one file or supply the same journal twice. Pass multiple files using repeated `--file` options. The command returns exit code 1 with a fixed, content-free error rather than printing private records. An unfinished final line is reported, not repaired.
+
+## Validation limits
+
+Automated tests use synthetic provider responses and verify configuration, observed values, cancellation, reporting and recovery. They do not prove current account availability, complete task cost, cache savings or server-side enforcement of client token limits. Any future real-account experiment needs its own bounded scope; installing or enabling the collector does not run an experiment or send an extra model request.
+
+## Logical cancellation versus transport cleanup
+
+This journal measures logical backend attempts, not the lifetime of every underlying socket or asynchronous cleanup operation. Existing governor behavior releases logical admission promptly after caller abort/disposal or a response-hook failure has requested body cancellation; it does not wait indefinitely for a custom transport's cancellation promise. An explicit consumer `body.cancel()` normally awaits source cleanup, unless a caller abort terminates the logical attempt first. The metrics observer does not change that abort policy.
+
+A pending read resolved by consumer cancellation is not a successful EOF: without a previously observed terminal event, it must be recorded once as cancelled. An observed provider terminal remains authoritative even if its reader is cancelled during cleanup. Cancellation never refunds a research request reservation or proves that server-side work/billing has ceased. Concurrency limits apply to admitted logical requests, not a hard upper bound on sockets still cleaning up after cancellation. Strengthening physical cleanup policy would be a separate governor change with its own timeout/availability design.

package/docs/request-metrics.zh.md

@@ -0,0 +1,52 @@
+# 本地请求计量
+
+[English](request-metrics.md) | 中文
+
+本文对应 Alpha 4.52 候选；已发布的 4.51 及更早版本不含此功能，候选记录不代表已经发布。请求计量默认关闭，只在本机记录有限的请求元数据；不上传遥测，不为计量额外调用模型，不恢复 Task，也不提供统计面板或订阅费用估算。内部评测程序和任务样本不随插件发布。
+
+## 在指定 profile 中启用
+
+在现有 `llm-openai-codex` 插件的 `config` 下增加字段，再按宿主正常流程重启这个 profile。不要创建第二个同名插件。这是启动配置，不是浏览器设置卡片中的开关。
+
+```yaml
+requestMetricsDirectory: /absolute/private/path/codex-request-metrics
+requestMetricsMaxBytes: 16777216
+```
+
+目录必须是绝对路径。Windows 可使用 YAML 单引号字符串，例如 `'C:\Private\CodexMetrics'`，并自行配置仅供当前账户读取的 ACL；插件不检查或修改 Windows ACL。POSIX 下，新目录权限为 `0700`，已有目录不能含 group/other 权限，不能是符号链接；每个进程创建独占的 `0600` 日志。请选择私有、不参与云同步的目录。
+
+`requestMetricsMaxBytes` 默认 `16777216`（16 MiB），允许 `4096` 至 `67108864` 的整数。它限制一个进程的单个日志，不是整个目录；只设置大小而不配置目录，不会开启计量。达到限额或写入失败时停止记录并提示一次，模型请求继续，不自动轮转或删除日志。停止标记也可能因磁盘错误无法写入，不能把记录不完整理解为没有消耗。
+
+## 离线查看
+
+```sh
+dsh plugin --profile web exec dsh-codex-connect metrics --file /absolute/private/path/codex-request-metrics/requests-UUID.jsonl --json
+```
+
+命令只读取明确指定的普通 JSONL 文件，不读取账户凭据、不联网。去掉 `--json` 可看文本摘要。独立命令为 `node lib/bin.js metrics --file <journal> --json`。可重复 `--file` 合并最多 32 份不同日志，也可重复 `--session <DSH-session-id>` 筛选已知会话；子会话不会被自动加入，需要明确列出。没有筛选时，无会话归属的辅助请求也包括在内。
+
+格式错误、重复输入、数组冒充枚举、同文件先开始后结束的请求配对错误、采集开始前或结束后的请求，以及互相矛盾的结束标记都会被拒绝。错误返回码为 1，仅显示固定提示，不回显记录内容。未写完的末行会标明并排除，既有日志不会被修补。
+
+## 数字表示什么
+
+每次实际进入后端 fetch 的 HTTP 尝试计数一次；结束记录覆盖响应读取、取消或传输失败，而不只是收到响应头。仅有开始记录的请求保持待完成／中断，不算成功或零 token。已经观察到提供方终止结果时，该结果优先于后续清理时的取消。
+
+记录包括请求类别、所选模型／强度、会话 SHA-256 分组值、适用时的 adapter 调用编号，以及数值用量和状态。不记录请求体、响应正文、工具参数、提示词、请求头、账户 ID、token 或服务端响应 ID。会话哈希用于关联，并不等于匿名化；日志应当按私有运行数据管理。
+
+输入、缓存读取、缓存写入、输出和推理输出仅使用响应中实际观察到的值；缺失或无效数据保持未知，不自动补零。输入包含缓存读取，推理输出属于输出的一部分，不会再次相加。缓存命中率按同时具有输入及缓存数据的请求，以总缓存输入除以总输入计算，并显示未知请求数，不是各请求百分比的平均。
+
+耗时从实际 HTTP 发送到响应生命周期结束，不含排队或鉴权等待；并发请求耗时相加不是任务墙钟时间。同一次 adapter 调用的额外 HTTP 尝试可以计数，跨调用的任务重试不会凭空推断。搜索、图片、额度和自动审阅按请求类别记录；缺少 adapter 作用域时归属保持未知。其他 provider、OAuth、公用图片下载、发出请求前的失败和启用之前的历史均不在覆盖范围内。
+
+报告不是完整任务账本、质量验收或费用凭证；不计算 API 美元费用或订阅额度。即使日志正常关闭，也不能证明任务的所有请求都已被观察。
+
+## 故障处理与停用
+
+没有日志时，先核对目标 profile、启动配置和是否重启；再核对目录权限、可写性和磁盘空间。固定的计量警告表示采集失败，不代表模型请求失败。`stoppedEarly` 或截断末行表示证据不完整。不要拼接多个进程的原始文件，使用重复 `--file` 交给报告命令合并。
+
+停用时，从有效启动配置中移除 `requestMetricsDirectory`，再重启目标 profile。旧日志保留，由用户自行导出、保留或删除。每次重启都会创建新文件，因此单文件限额不等于目录容量上限。
+
+## 取消与验证边界
+
+这里记录逻辑请求，不保证物理连接清理完成。原有 governor 在信号取消、服务释放或响应钩子失败后请求取消并及时释放逻辑名额，不无限等待自定义传输的清理 Promise。显式消费者取消通常等待清理；若随后收到信号取消，可先结束逻辑请求。取消产生的挂起读取结束不能冒充正常 EOF，且不能证明服务端工作或计费已经停止。
+
+自动测试采用合成响应，验证配置、取值、取消、恢复与离线报告，不证明真实账户可用性、任务收益或缓存节约。任何真实实验需单独明确范围；安装或启用采集不会自动运行实验。Task 暂停和所有原有可选功能默认状态不变。