Merge pull request #2922 from deepseek-harness/worktree/trim-cot-skill-followup-20260822

docs: harden chain-of-thought leakage audits
2026-08-29 04:26:38 +00:00 · 2026-08-22 14:43:09 +08:00
parent 43c30bf063 7f93f65ca9
commit 7476b0495d
17 changed files with 64 additions and 27 deletions
@@ -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:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-13-feedback-note-editor-popover.md
-2026-08-13-feedback-note-editor-popover.md: cfb0d7c8a91909fde1213be0fe2cbce5ec3ad834
-2026-08-13-feedback-note-editor-popover.zh.md: 9886f4fcaaa145977c701ef0d3fe76aea2fac135
+2026-08-13-feedback-note-editor-popover.md: 42c08e39cfb054db689503e23306c5049a97b6cb
+2026-08-13-feedback-note-editor-popover.zh.md: 553029f8a42dae42a38e909d716b41e2c6dd252e
@@ -40,4 +40,4 @@ The `ui-message-feedback` package adds `@types/react-dom` so the `createPortal`

 Known limitations are accepted rather than fixed here. A rating click while the panel is open closes it, and the close path returns focus to the note trigger rather than leaving it on the rating button the human just pressed; the same happens when an outside click lands on another focusable control, which the browser focuses before the close returns focus to the trigger. A pointer user does not notice either; a keyboard user feels the focus move. The clamp assumes the panel fits: a panel taller than the viewport makes the upper bound `innerHeight - height - margin` smaller than `margin`, so `top` goes negative and the panel's head is cut off rather than its foot. The panel's three-row textarea carries `resize: vertical`, so a human can drag past that size; `.notePanel` therefore bounds its height at `calc(100vh - 24px)` and scrolls its own content, the counterpart of the existing `max-width` and the same 12px margin the clamp uses. If the rating disappears while the editor is open, the panel unmounts on the `rating !== undefined` guard but `noteOpen` stays true, so the document-level Escape and pointer-down listeners remain attached; should the item reappear through a later resync, the panel returns with the previous draft and without refocusing the textarea. The window is one click or Escape wide, and the save failure it could hide already falls back to the row, so it is left as it is. A failure that lands after the panel was closed and reopened is not written into the new session's panel: its draft was reseeded from the stored note, so an old attempt's error would mislabel it, and the uncommitted content is already gone — the failure is dropped rather than shown. And while the placement replays on scroll, window resize, and the panel's own size changes, jsdom has no layout, so the real geometry is proven by the browser scenario while the unit spec covers the wiring through a `ResizeObserver` stub.

-A residual narrow-viewport clock overflow remains below 520px from the clock string alone, unrelated to the feedback surface. The repository has no gate for undefined design tokens.
+A residual narrow-viewport clock overflow remains below 520px from the clock string alone, unrelated to the feedback surface. Undefined design-token references remain in `ui-agent-preset`, `ui-conversation`, `ui-jobs`, `ui-settings-plugins`, and `ui-tool`; the repository has no gate that rejects them.
@@ -40,4 +40,4 @@ Status: implemented

 有若干已知限制在此接受而非修复。面板打开时点击评分会关闭它，而关闭路径把焦点归还给备注触发按钮，而不是留在用户刚按下的评分按钮上；外部点击落在另一个可聚焦控件上时同理——浏览器先把焦点给该控件，随后关闭路径又把它拉回触发按钮。指针用户对两者都无感，键盘用户会察觉焦点移动。钳制假定面板放得下：面板高于视口时，上界 `innerHeight - height - margin` 会小于 `margin`，于是 `top` 变为负值、被裁掉的是面板顶部而非底部。面板里的三行 textarea 带 `resize: vertical`，用户可以拖过这个尺寸，因此 `.notePanel` 把自身高度限制在 `calc(100vh - 24px)` 并自行滚动内容——这是既有 `max-width` 的对应项，用的是与钳制相同的 12px 边距。编辑器打开时若评分消失，面板会因 `rating !== undefined` 守卫卸载，但 `noteOpen` 仍为 true，因此 document 级的 Escape 与 pointer-down 监听继续挂着；若该 item 之后经 resync 重新出现，浮层会带着上一次的草稿回来且不重新聚焦 textarea。该窗口只有一次点击或一次 Escape 那么宽，而它可能遮住的保存失败已经有行内回退，因此保持现状。若失败在面板关闭并重开后才到达，不会写入新会话的面板：其草稿已按已存备注重新播种，旧尝试的错误会误标新草稿，而未提交的内容本就不存在——该失败被丢弃而不展示。以及，定位虽然会在滚动、窗口缩放与面板自身尺寸变化时重放，但 jsdom 没有布局，因此真实几何由浏览器场景证明，单测则通过 `ResizeObserver` stub 覆盖其接线。

-520px 以下仍残留仅来自时钟字符串的窄视口溢出，与本界面无关。仓库没有针对未定义设计 token 的门禁。
+520px 以下仍残留仅来自时钟字符串的窄视口溢出，与本界面无关。`ui-agent-preset`、`ui-conversation`、`ui-jobs`、`ui-settings-plugins` 与 `ui-tool` 仍引用未定义的 design token；仓库没有拒绝此类引用的门禁。
@@ -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:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-09-committed-artifact-citations.md
-2026-08-09-committed-artifact-citations.md: 044f7683d51ebf2038f56d2b5a27755ecc9be6d5
-2026-08-09-committed-artifact-citations.zh.md: 620a99195f9a9c0337b1145d87ba1f8a042eb430
+2026-08-09-committed-artifact-citations.md: a84b25545b97b6df62b3d51da895b4c7f8887ccf
+2026-08-09-committed-artifact-citations.zh.md: 8cff257fd22d449d965067343e6aed4413b8eae7
@@ -17,6 +17,8 @@ Durable prose — comments, JSDoc, docs, notes, test comments and titles — cit
 - Fixed regressions are pinned as present-tense counterfactuals ("without X, Y happens"; "a naive X would…"), never as repo history ("used to Y").
 - Implemented notes state shipped reality: a "deferred to a later PR" claim whose target shipped names the shipped note instead.
 - Recorded fixtures, snapshots, and archived notes are exempt: recorded model output and sealed history keep their original voice. Inside a note's change-story sections, a historical stage name ("the first cut shipped X") is current-state-safe; indexical stamps ("this cut") stay banned everywhere.
+- Recall probes use lexical boundaries and are calibrated against a known positive and a near-miss negative. Authoring-language probes target the opposite-language surface instead of treating the complete Chinese corpus as untranslated residue.
+- Owner-first edits trace every generated consumer. Verbatim code fences are copied byte-for-byte across bilingual pairs; model- or user-visible wording changes only with its owning behavior evidence, otherwise the audit leaves it unchanged and reports the deferral.

 One repo-wide purge applied these rules across the prose surfaces, including the generator-owned templates (`scripts/gen-doc-graphs.ts`, `scripts/gen-tool-catalog.ts`, the typert generator's page notice) with regeneration, the type-equiv source JSDoc with page re-pastes, and the bilingual counterparts with pair re-records. The [dsh-trim-cot-leakage skill](../../../skills/dsh-trim-cot-leakage/SKILL.md) operationalizes these rules: the audit taxonomy, the committed recall batteries, and few-shot examples for deciding what to keep or delete.

@@ -17,6 +17,8 @@ Status: implemented
 - 已修复的回归以现在时反事实句固定下来（「没有 X 就会发生 Y」、「朴素的 X 会……」），绝不写成仓库历史（「过去曾 Y」）。
 - 已实现的 Agent Note 陈述已交付的现实：「推迟到后续 PR」的说法若其目标已经交付，就改为点名那篇已交付的 note。
 - 已录制的 fixture（测试前置数据）、快照与已归档的 Agent Note 不受此约束：已录制的模型输出与封存的历史保持原有行文。在 note 的变更故事段落内，历史阶段名称（「首版交付了 X」）符合只描述当前状态的要求；「this cut」这类指示当前版本的标记在任何地方都仍被禁止。
+- 召回检索使用词法边界，并以一个已知正例和一个近似反例校准。写作语言残留检索仅在另一语言的行文表面运行，不把整个中文语料库当作未翻译残留。
+- 先改归属源时追踪每个生成消费方。围栏代码块在双语配对中逐字节复制；模型或用户可见的文字只有在归属场景的行为证据随同更新时才改，否则审计保持原文并报告推迟项。

 一次全仓库清理把这些规则应用到了各个行文表面，包括生成器持有的模板（`scripts/gen-doc-graphs.ts`、`scripts/gen-tool-catalog.ts`、typert 生成器的页面提示语，改后重新生成）、type-equiv 源码中的 JSDoc（改后重新同步到文档页）以及双语对侧文件（改后重新记录配对）。[dsh-trim-cot-leakage 技能](../../../skills/dsh-trim-cot-leakage/SKILL.md)把这些规则落地为可执行工作流：审计分类法、已提交的成批召回检索，以及用于判断保留或删除内容的少样本示例。

@@ -27,7 +27,7 @@ Apply the standard's authoring order to every human-facing document in scope. Do

 Then check constraints that make placement expensive or wrong:

- Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn.
+- Paired docs (`pnpm run verify-translation-pairing --list`) cost a zh counterpart update and a `--write` re-record on every edit — prefer an unpaired home for content that will churn. Verbatim code blocks are byte-exact across the pair: copy a corrected fence into both files instead of translating its comments independently.
 - Generated catalogs are never hand-edited; if the fact belongs there, change the generator's source.
 - Before renaming or moving any doc, grep for inbound references: `verify-md-links` catches Markdown link targets AND `#fragment` anchors onto Markdown files (heading slugs and explicit `<a id>`), and `verify-doc-refs` catches `docs/*.md` citations in TypeScript comments; anchors cited from TypeScript strings still need a manual grep when their output never reaches gate-scanned Markdown.
 - A move is atomic: remove from the old home, add to the new home, and fix every inbound link in the same change.
@@ -23,7 +23,7 @@ Always exclude `vendor/` from discovery, review, and edits, even when the reques

 Also exclude `.agents/notes/archived/` from prose review and edits. Archived Agent Notes are frozen snapshots; inspect an exact target only to understand a historical inbound citation, never to modernize its prose or outbound links.

-Treat generated catalogs, snapshots, and fixtures as derivative. Edit the owning source or scenario first, then regenerate the artifact. When a generator extracts a summary from owner prose, make the extracted sentence complete for that surface. Bilingual pairs have no permanent owner: either language may be the authored side for an update. Follow the [lightweight routine path](../../../docs/AGENTS.md#writing-rules), update the counterpart minimally, and re-record the pair.
+Treat generated catalogs, snapshots, and fixtures as derivative. Trace every consumer before editing: source JSDoc may also feed a generated model-visible catalog. Edit the owning source or scenario first, then regenerate every derivative. When a generator extracts a summary from owner prose, make the extracted sentence complete for that surface. Bilingual pairs have no permanent owner: either language may be the authored side for an update. Follow the [lightweight routine path](../../../docs/AGENTS.md#writing-rules), update the counterpart minimally, and re-record the pair.

 ## Preserve the complete proposition

@@ -55,7 +55,7 @@ This is not a one-way shortening pass. Add or restore prose when code, types, an
 - **Postmortems:** retain the incident sequence, evidence, causal chain, impact, and prevention. Remove repeated persuasion or implementation detail that does not establish causality.
 - **Skills and agent instructions:** state behavioral guardrails and explicit scope limitations such as “guidance, not a script/checklist.” Keep the workflow concise and link its source of truth.
 - **Examples and configuration comments:** explain access limits, non-obvious wiring or load order, security stance, replay behavior, exceptions, and likely misuse. Do not narrate entries that the configuration already shows.
- **Prompts and visible strings:** treat wording as behavior. Inspect generated output and run behavior validation or state why no snapshot applies.
+- **Prompts and visible strings:** treat wording as behavior. Update the owning runnable snapshot for model-visible text and the repository-required behavior evidence for GUI text. If the authorized scope has no owning scenario, leave the wording unchanged and report the deferral; do not silently fold it into a prose-only edit.
 - **Diagnostics:** name the failing subject or path, violated rule, and correction when it is non-obvious. Remove internal execution narration.

 Preserve searchable mechanism names and meaningful modal, temporal, or negative emphasis. Normalize decorative emphasis only.
@@ -146,6 +146,8 @@ Keep the consequence of order, a surprising scope rule, or a security boundary.

 Wording that reaches a model is behavior, but duplication still drifts. Exactness belongs at the owner.

+A prose-only audit may identify suspect wording but must not silently change it when no owning runnable snapshot exists. Leave it unchanged and report the deferral, or expand the authorized change to include the owner scenario and required GUI evidence.
+
 ## Generated summaries must stand alone

 **Over-trimmed:** “Approval request and policy service.” The owner explains policy order and audit logging later, but the catalog exports only its first sentence.
@@ -38,8 +38,8 @@ Unaided citation passes fail in both directions by deleting durable references a

 ## Workflow

-1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/`, `.agents/notes/archived/`, or recorded fixtures and snapshots — recorded model output and sealed history keep their original voice.
-2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge found cases the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
-3. Fix owner-first per surface: generated catalogs → fix the source JSDoc or generator template, then regenerate; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual pairs → update the counterpart and re-record per [dsh-translate-docs](../dsh-translate-docs/SKILL.md); model-visible strings → wording is behavior, so flag for a snapshot-backed change instead of silently rewording.
+1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/` or `.agents/notes/archived/`. Recorded fixtures and snapshots are derivatives, not prose targets: change the owning source or scenario and regenerate them only when an authorized behavior change requires new evidence.
+2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), calibrating each probe against a known positive and a near-miss negative before trusting its output, then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge found cases the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand.
+3. Fix owner-first per surface: generated catalogs → trace every consumer, fix the source JSDoc or generator template, then regenerate all derivatives; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual prose → update the counterpart minimally and re-record it through the [lightweight routine](../../../docs/AGENTS.md#writing-rules); bilingual fences → copy the corrected verbatim block byte-for-byte into both sides per [dsh-doc-standards](../dsh-doc-standards/SKILL.md), then re-record the pair; model- or user-visible strings → route through [dsh-prose-standard](../dsh-prose-standard/SKILL.md) and change only with owning behavior evidence, otherwise leave unchanged and report the deferral.
 4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop provenance.
 5. Verify: re-run the batteries expecting only sanctioned keeps, this skill's own directory, and the owning note's quoted evidence; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`).
@@ -176,6 +176,22 @@ Replace the hedge with the actual bound and the failure behavior when it is exce

 Working-language fragments and session separators are transcription residue. The Figma frame name stays: external provenance that resolves outside the repo by design.

+### Authoring-language slip inside a paired fence
+
+**Leaked in both files:** `// 更新这里 before returning` inside a verbatim code block.
+
+**Fixed in both files:** `// Update this before returning.`
+
+Correct the block once and copy that byte-exact fence into both language files. Translating the code comment differently in the Chinese counterpart breaks the pairing contract even when both comments are individually fluent.
+
+## Behavior-visible candidates
+
+**Suspect:** An exported JSDoc sentence says "available for now," and a generator copies that sentence into a model-visible catalog.
+
+**Wrong:** Rewrite only the source sentence during a prose-only purge, or hand-edit only the generated catalog.
+
+**Right:** Trace the source's generated fan-out, update the owner, regenerate every derivative, and update the owning runnable snapshot. For a GUI string, include the repository-required behavior evidence. If the authorized scope has no owning scenario, leave the wording unchanged and report the deferral.
+
 ## Keeps

 ### Issue references are durable on every surface
@@ -208,6 +224,12 @@ The measurement pins the constant against uninformed retuning, and "measured" is

 "Old" and "new" here name two live runtime objects during handover, not repository states. The change-narration ban is about repo history, not lifecycle vocabulary.

+### Runtime natural time is not a version stamp
+
+**Keep:** "What is today's date?"
+
+The prompt asks about the runtime clock; "today" does not contrast repository states. Because the text reaches a model, any rewrite still requires its owning behavior evidence.
+
 ## Overcorrection traps

 Every trap below shipped in the original purge and was caught in review. Enumerate a passage's propositions before trimming it.
@@ -7,25 +7,34 @@ Probes for [the taxonomy](../SKILL.md#taxonomy), tuned during the 2026-08 purge.
 - Add `--hidden --glob '!.git/**'` so `.agents/` is searched; ripgrep skips dot-directories by default and the purge's biggest miss risk was Agent Notes.
 - Exclusions go last so a later include cannot re-admit them: `--glob '!vendor/**' --glob '!node_modules/**' --glob '!.agents/notes/archived/**' --glob '!.agents/skills/dsh-trim-cot-leakage/**'` (the skill's own files quote leaked wording as calibration), plus recorded fixture and snapshot directories in scope. The [owning note](../../../notes/implemented/process/2026-08-09-committed-artifact-citations.md) also self-hits through its quoted evidence; judge it as evidence, not usage.
 - Natural-language lines carry `-i` so sentence-initial capitals hit ("This PR adds…", "Probably fine…"); the first line, which matches code patterns, stays case-sensitive — `-i` would turn `\bT\d\b` and `\bP-I\b` into noise.
- A zero-hit pattern proves nothing until you have seen it match: test it against a known-positive string before trusting the negative.
+- Bound complete phrases. `\bthis PR\b` must match "this PR adds" without matching "this project", "this process", or "this provider".
+- A zero-hit pattern proves nothing until it matches a known positive, and a noisy pattern proves nothing until it rejects a near-miss negative. Calibrate both before trusting a corpus result.
+- Target authoring-language probes at the opposite-language surface: search Chinese residue in otherwise-English Markdown and code comments/JSDoc, and search Chinese change narration within `*.zh.md`. A generic ASCII search for English residue in Chinese prose is too noisy around code and identifiers; compare the prose additions against their counterpart instead.

 ## English battery

 ```sh
 rg -n --hidden '\(decision \d|\(audit [A-Z]\d|design §|plan §|design ledger|\(B ruling|\bP-I\b|\bW\d\b|\bT\d\b' ...
-rg -n --hidden -i 'this PR|this branch|this stack|later PR|previous commit|this commit' ...
-rg -n --hidden -i 'used to |no longer|previously|the old |was renamed|was moved' ...
+rg -n --hidden -i '\bthis PR\b|\bthis branch\b|\bthis stack\b|\blater PRs?\b|\bprevious commits?\b|\bthis commit\b' ...
+rg -n --hidden -i '\bused to\b|\bno longer\b|\bpreviously\b|\bthe old\b|\bwas renamed\b|\bwas moved\b' ...
 rg -n --hidden -i '\bv1\b|this cut|\bcut \d|\btoday\b|\bfor now\b|roadmap' ...
 rg -n --hidden -i 'rejected in review|review round|reviewer|as of v\d' ...
 rg -n --hidden -i 'probably |should be enough|should suffice|it simply|is safe —|is safe --' ...
 rg -n --hidden '§\d' ...
 ```

-## Chinese battery
+## Chinese batteries

 ```sh
-rg -n --hidden '设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有' ...
-rg -n --hidden '(^|[^a-zA-Z])端([^a-zA-Z]|$)' --glob '*.md' ...
+# Change or review narration in Chinese counterparts.
+rg -n --hidden '评审|上一?轮|旧版|老的|不再|以前|本版|遗留' --glob '*.zh.md' ...
+
+# Chinese authoring-language slips in English Markdown.
+rg -n --hidden '设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有|(^|[^a-zA-Z])端([^a-zA-Z]|$)' --glob '*.md' --glob '!*.zh.md' ...
+
+# Chinese authoring-language slips in English code comments and JSDoc.
+rg -n --hidden '(^[[:space:]]*(//|/\*|\*)|//|/\*)[^\r\n]*(设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有|端)' --glob '*.{ts,tsx,js,jsx,mjs,cjs,css}' ...
+rg -n --hidden '#[^\r\n]*(设计稿|评审|上一?轮|旧版|老的|不再|以前|本版|遗留|私有|端)' --glob '*.py' ...
 ```

 ## Known false-positive families
@@ -38,6 +47,6 @@ Judged and kept during the purge; expect them again:
 - **`v1` as protocol or path segment** — `/v1/chat` endpoints and wire-format names are identifiers, not version stamps.
 - **`§N` with a committed owner** — external standards (RFC 9110 §10.1.5) and committed docs that own their §-numbering stay citable by section.
 - **Contrastive "actually" and noun "wait"** — ordinary English, not hedging; no committed line probes them, so they surface only when you extend the battery with broader hedging patterns.
- **"Today" in generated timestamps and CLI output samples** — recorded output keeps its voice.
+- **Runtime "today" and recorded timestamps** — prompts or tests that ask for the current date use natural time, not a repository version stamp; recorded CLI output keeps its voice. Wording that reaches a model or user still follows the behavior-evidence rule before any edit.
 - **本版本 in zh prose** — a legitimate rendering of "this release" in versioned-artifact contexts; the banned indexical is 本版 as a bare stamp mirroring "this cut".
 - **Alternatives-considered sections** — "rejected" inside an Agent Note's genre slot is the sanctioned home, not review choreography.
@@ -165,7 +165,7 @@ export function ProjectRowItem({ group, onToggle, onCreate, actions, drag, home,
              setMenuOpen(false)
              // Unknown ids leave before the dispatch: a future menu row must
              // not inherit the destructive branch as an else fallback.
-              /* v8 ignore next -- workspaceMenuItems is a closed two-row union. */
+              /* v8 ignore next -- Menu can emit only the rename and delete rows supplied above. */
              if (id !== 'rename' && id !== 'delete') return
              if (id === 'rename') actions.rename()
              else actions.delete()
@@ -233,8 +233,8 @@ interface SessionLogScan {
 /**
 * Refuse a header carrying a format version this build does not read BEFORE
 * validating the current header shape or decoding any event row: a future
- * format need not satisfy this format version's structural checks at all, and its user must
- * see "upgrade the harness", never "corrupt session log".
+ * format need not satisfy this build's structural checks at all, and its user
+ * must see "upgrade the harness", never "corrupt session log".
 * @param parsed - the JSON-parsed first line of a session artifact.
 */
 function refuseForeignFormatVersion(parsed: unknown): void {
@@ -191,7 +191,7 @@ describe('JsonlSessionPersistence: format helpers', () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)
    const fiber = await ctx.plugin(JsonlSessionPersistence, { root: absoluteRoot, compression: 'none' })
-    // A future format need not satisfy this format version's header shape at all (no
+    // A future format need not satisfy this build's header shape at all (no
    // createdAt, unknown fields): the version must be refused before shape
    // validation, so the user sees the upgrade direction.
    const id = SessionId('future-shape')
@@ -68,7 +68,7 @@ export class SessionFormatUnsupportedError extends Error {
 * Direction-aware refusal text for a stored session whose format version this
 * build does not read. Shared by the coordinator's load-time check and by
 * backends that must refuse BEFORE decoding version-dependent structure (a
- * future format may not satisfy this format version's structural checks at all, and the
+ * future format may not satisfy this build's structural checks at all, and the
 * user must see "upgrade the harness", never "corrupt").
 * @param id - the stored session id, for message context.
 * @param version - the stored format version.
@@ -180,9 +180,9 @@ for line in sys.stdin:
            },
        })
    elif method == "tools/list":
-        # Keep discovery pending beyond 100 ms. An SDK runtime that answers
-        # initialize too early will make
-        # its first model request without this tool and fail deterministically.
+        # Keep discovery pending long enough that an SDK runtime answering
+        # initialize before discovery completes makes its first model request
+        # without this tool and fails deterministically.
        time.sleep(0.25)
        send({
            "jsonrpc": "2.0",