docs: fix four factual errors found by Codex review round 1

- plan.md/.zh.md (+ plan-mode module JSDoc and README pair): the sole
  flush point is the prepended agent/step listener; prompt admission is
  pre-turn and never flushes — the pages had it backwards.
- workspace.md/.zh.md: pending-mutation recovery deletes the marked
  table row — completing an interrupted delete but rolling back an
  interrupted create; 'completes exactly the marked mutation' oversold.
- telemetry.md/.zh.md: delivery is best-effort with possible loss AND
  duplication, not at-most-once; TelemetryRecord.attributes JSDoc (source
  + both fences) now lists session.seed_length, which the coordinator
  emits for forked sessions.
- Agent Note consequence bullet: nine pages cover ten services (storage
  owns two keys); client-modules.zh.md wire-single-source phrasing.

Pairs re-recorded; plan-mode and telemetry suites green.
This commit is contained in:
Tianyi Cui
2026-07-28 00:20:38 +08:00
parent a8cf78630c
commit 061100f6f2
15 changed files with 30 additions and 30 deletions
+1 -1
View File
@@ -14,7 +14,7 @@ Source: [`packages/plan/plan-mode/src/index.ts`](../../packages/plan/plan-mode/s
Because every session event is turn-enclosed, a user selection is held as pending intent until a turn boundary. `set(agent, active)` records the pending selection (a no-op when the target equals the logged-or-already-pending state), and `get(agent)` returns `{ active: boolean; pending?: boolean }` — the logged state shaping the current step, plus the optimistic selection awaiting a boundary.
The service flushes one pending selection before the affected request assembly at three boundaries: prompt submission, ordinary turn continuation, and request-recovery retry. The flush runs after the downstream listener chain, so a selection arriving while an async listener awaits still shapes the request that boundary precedes. A flush failure is contained — plan policy can never block a prompt or turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
The sole flush point is a prepended `agent/step` listener — the loop's in-turn interception seam that runs before every request derivation, including turn 1 step 1 and request-recovery retries. Prompt admission itself never flushes: it happens pre-turn, where a `plan/mode` append would land outside any open turn, so a selection made at the prompt is landed by the first step boundary inside the turn it starts. The prepend means the flush runs before the downstream `agent/step` listener chain. A flush failure is contained — plan policy can never block a turn — and the failed append stays pending for a later boundary. A flushed user selection also narrates the switch as one plugin-sourced `user/message` notice, but only when the last logged request header described the other state, so the model is told exactly when its context changed and never redundantly. A pending selection made while idle is process-local and lost on exit before the next boundary ([README limitation](../../packages/plan/plan-mode/README.md#known-limitations-and-deferred-work)).
## Configuration