better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/chapters/ch22-i18n.md

@@ -0,0 +1,86 @@
+# Chapter 22: i18n & Translation
+
+## Core Idea
+Every in-scope dsh document is maintained as an equal-authority English/Simplified-Chinese pair of three sibling files (`foo.md`, `foo.zh.md`, `foo.i18n.yaml`), mechanically gated by blob-hash consistency records plus structural-signature checks, with terminology.md as the single source of truth for term rendering.
+
+## Frameworks Introduced
+- **Pairing contract**: both languages carry equal authority; a PR never lands one side without the other two files.
+  - When to use: any edit to an in-scope document.
+  - How: update the counterpart directly in one terminology-guided pass, then `pnpm run verify-translation-pairing --write <pair>` re-records both blob hashes; that yaml diff is the reviewable confirmation act.
+- **Consistency record (`foo.i18n.yaml`)**: full git blob hash (`git hash-object`) of each side at last confirmation — content comparison, computable within one PR; recovers exact last-confirmed text for minimal patch-style resync (never re-translate whole files).
+- **Structural signature**: heading depths/order, fenced code blocks (byte-identical incl. comments), table row/column counts, list kinds/starts/item counts, semantic link targets with exact query/fragment suffixes — must match 1:1 across the pair.
+- **Translation rules (RFC 2119 levels)**: MUST/MUST NOT gate-blocking, SHOULD needs stated deviation reason, MAY discretionary; register calibrated by style-samples gold pairs (sample wins over prose voice rules on conflict).
+- **Translation prompt pipeline**: `scripts/translation-prompt.ts` renders the committed template with only `{{source_lang}}`, `{{target_lang}}`, `{{terminology}}` placeholders; output is three XML sections (`<translation>` / `<review>` / `<final>`), pipeline takes `<final>`; 5 human-reviewed whole-document gold pairs injected as few-shot example conversations.
+
+## Key Concepts
+- **Language switcher**: Chinese file links back right after H1: `[English](foo.md) | 中文`; authored English files reciprocate; generated English sources omit it (stay byte-identical to generator output).
+- **Exclusions** (never paired): `cordis-api/inherited.md`, AGENTS.md/CLAUDE.md instruction files, `terminology.md` + `style-samples.md` (bilingual by construction), `translation-prompt.md` (machine-consumed verbatim), `.agents/notes/archived/` (frozen, sealed).
+- **Term classes**: 缩写类 (ACP, LLM, SSE — abbreviations in both languages); 英文类 (agent, seam, slot, fiber — keep English in Chinese prose); 双语类 (adapter→适配器, session→会话 — translate, with 不要译作 prohibitions).
+- **First-occurrence annotation**: write the 首次出现 value on first prose occurrence (e.g. `agent（智能体）`), bare form afterward; a term already glossed inside a compound needs no re-gloss.
+- **Pending terms**: unlisted terms without established major-OSS precedent (K8s/Vue/MDN/微软) stay English and go under 待定术语; no inline invention.
+- **Protected tokens**: inline code spans — commands, flags, paths, identifiers, API/event names, config keys, versions — verbatim, never translated; fenced code blocks byte-identical including comments.
+- **Chinese typography**: half-width space between Chinese and Latin/numerals; full-width punctuation `，。：；？！（）「」`; 顿号 for parallel lists; no full-width digits; 你 not 您; RFC 2119 → 必须/禁止/应当/可以 preserving emphasis strength.
+- **Merge driver**: `dsh-translation-pairing` composes records when both owner blobs merge cleanly; fails closed otherwise; `pnpm run resolve-translation-pairing-conflicts` for stopped merges.
+
+## Mental Models
+- Think of the gate as proof of confirmation, not soundness: green = hashes and structure match; whether the two sides truly say the same thing is the reviewer's half.
+- Use the lightweight path (translate directly, one pass, load terminology first) for routine agent work; the `dsh-translate-docs` skill workflow only on explicit user invocation.
+- Treat out-of-sync resync as patching: diff the edited side against its last-confirmed hash, apply the minimal counterpart patch — never re-translate the file.
+- Think of authority order in the prompt: source meaning/structure > terminology table > gold pairs > prompt guidance; gold pairs calibrate voice, they are not a translation memory.
+
+## Anti-patterns
+- **Editing one side of a pair without the other**: CI goes red; a scoped green (`verify-translation-pairing <pair>`) never substitutes for the corpus-wide run at PR level.
+- **Translating code identifiers or fence contents**: byte-identical requirement; ` ```ts ` fences also compile under doc-typecheck.
+- **Using a 不要译作 rendering** (e.g. 接缝 for seam, 智能体笔记 for Agent Note, 金丝雀测试 for canary): strictly forbidden.
+- **Conflating term pairs**: capability→能力 vs feature→功能; inference vs reasoning (gloss only when disambiguation needed); stale→陈旧 vs expired→过期.
+- **Copying the language switcher unchanged when translating**: flip it; if the source has none, don't invent a filename — the pipeline inserts the canonical switcher post-parse.
+
+## Code Examples
+```yaml
+# foo.i18n.yaml — consistency record (blob hashes)
+foo.md: 3f786850e387550fdab836ed7e6dc881de23001b
+foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b
+```
+```sh
+pnpm run verify-translation-pairing --list <pair>   # state: missing/out-of-sync/ok
+pnpm run verify-translation-pairing --write <pair>  # re-record after syncing
+pnpm run gen-translation-brief <pair>               # extended workflow only
+```
+```markdown
+<!-- Chinese file top: --> [English](foo.md) | 中文
+<!-- Authored English file top: --> English | [中文](foo.zh.md)
+```
+
+## Reference Tables
+| Key term | 中文 | Never render as |
+|---|---|---|
+| agent | agent (gloss 智能体 first use) | — |
+| seam | seam | 接缝 |
+| slot | slot | 坑位、孔位 |
+| postmortem | 事故复盘 | 事后分析、事故记录 |
+| Agent Note | Agent Note | 智能体注记/笔记 |
+| capability / feature | 能力 / 功能 | crossed: 能力↔功能 |
+| expected output | 预期输出 | 金标 |
+| source of truth | 真源 | 事实来源 |
+| counterpart | 对侧文件 | 对应物 |
+| canary test | canary 测试 | 金丝雀测试 |
+
+| Scope item | Rule |
+|---|---|
+| Docs in scope | root CONTRIBUTING/BRAND/SAFETY, non-vendor READMEs, `.agents/notes/**`, `docs/**`, `python/**` |
+| Pair granularity | three sibling files, same directory; no locale dirs |
+| Gate | part of `doc-sync`; run corpus-wide at PR level |
+| Generated sources | pair only when reviewed counterpart exists; English generator stays source of truth |
+
+## Key Takeaways
+1. A PR editing either side updates the counterpart and re-records the pair in the same change — the yaml hash diff is the reviewable act of confirming consistency.
+2. Load terminology.md before translating; every listed term follows its row, its 首次出现 annotation, and its 不要译作 prohibitions, in both directions.
+3. Structure mirrors one-to-one: headings, list shape, table dimensions, code fences, and link targets (with locale-swapped `.md`/`.zh.md` paths inside the corpus) must match.
+4. The prompt pipeline recognizes only three placeholders and whole-document translation; output framing escapes lines that look like wrapper tags with one extra backslash.
+5. Routine work never delegates translation to a subagent or runs a separate review pass — one direct terminology-guided pass, then the gate.
+6. Chinese register = institutional technical Chinese with explicit actors (系统/门禁/评审人) replacing vague passives; established engineering idiom (误报/漏检) over calques.
+
+## Connects To
+- **Ch 20**: doc-sync gates include pairing verification; Markdown rules apply to `.zh.md` unchanged.
+- **Ch 06/11/12**: generated references (architecture regions, tool/config/persistence catalogs) pair only with reviewed counterparts.
+- **Ch 21**: postmortem title terms (Executive summary→摘要, Summary→概述) come from the glossary.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/cheatsheet.md

@@ -0,0 +1,67 @@
+# Cheatsheet — dsh-dev-skill
+
+Decision rules and quick tables. Every line helps you decide something.
+
+## Which extension surface? (seam-selection)
+
+| You want to… | Use | Not |
+|---|---|---|
+| Add a model-facing tool | `defineTool` into `ctx.tools` | fork a core |
+| Change policy on existing tools | event gates (`tools/pre-execute`, monotonic guards) | rewrite tools |
+| Add policy w/o forking providers | companion plugin on `fs/*` or `tools/post-execute` | provider fork |
+| Swap a capability (shell/fs/llm) | provide at the seam (Definition+Provider+Consumer) | bundle a copy |
+| Contribute UI | `ctx.slots.inject` + fresh list id | runtime-import other plugins |
+| Change a plugin's config | later-layer row restatement (whole config) | field merge (doesn't exist) |
+| Iterate on a local plugin | `--patch` absolute-path insert row | install loops |
+| New provider backend | `LlmAdapter.stream()` + `registerAdapter` | wrap another adapter |
+| Stream to browser | Connection Fetch exact route | Remote method (unary only) |
+| Long-running tool work | `ctx.jobs.start` → `{kind:'background',jobId}` | prose ids |
+| Per-session derived state | `ProjectionDefinition` | manual `session/event` fold |
+| Plugin persistent data | `defineDomain` + `storageDomain.open` | ad-hoc files |
+| Model-visible input | extend `SessionEventMap` (log it) | inject outside the log |
+
+## Hard rules (fail-loud / fail-closed)
+
+- Sandbox mode unavailable ⇒ `SANDBOX_UNAVAILABLE` — never silent unconfined passthrough.
+- Approval absent/unanswerable ⇒ deny. Only `allowed-once` grants; escalation is one-shot, strictly wider.
+- `provide` throws on duplicate name within a scope — sibling shadowing doesn't exist (ancestor/isolate only).
+- Unrecognized session event type ⇒ treated required (refuse reconstruction); opt-in `ignorable:true` only for loss-safe records.
+- Non-JSON payload ⇒ rejected at `Session.append`.
+- Adapter can't honor a `GenerateOptions` field ⇒ throw `LlmError('UNSUPPORTED_OPTION')`, never drop silently.
+- Plugin reading undeclared optional service ⇒ `ctx.get(name)`, never `ctx.<name>` (ancestor-only walk throws).
+- Config row override ⇒ restate every key; whole-config replacement, no deep merge.
+- A config tree omitting an injected `Requires:` service fails to compose.
+- Model-visible means logged: model requests must be reconstructable from the session log.
+
+## Key defaults & thresholds
+
+| Thing | Default / value |
+|---|---|
+| `SandboxMode` | `read-only` |
+| `ApprovalPolicy` | `ask` (fail-closed); `never` for CI |
+| Retry policy | `ResolvedRetryPolicy` 5 retries, agent-level |
+| `dshHome` | `$DSH_HOME` → `~/.dsh` |
+| Session formats | v0 `session.jsonl[.zstd]`; v1+ `session.vN.jsonl[.zstd]`; committed paths never renamed |
+| Surface event types | exactly 3: `user/message`, `assistant/message`, `tool/result` |
+| Profiles | `web`, `headless`, `sdk`, `sdk-minimal`, `acp` |
+| Layer order | bundles → profile → home → `--patch`; later wins |
+| LLM usage counts | input + cacheRead + cacheWrite = billed input |
+| Env-var hygiene | scrub `*KEY*/*SECRET*/*TOKEN*/*PASSWORD*`; spill dirs 0700, files `'wx'` 0o600 |
+
+## Tells & smells
+
+- New plugin does nothing ⇒ check `FiberState.PENDING` (silent wait on missing service) and module-specifier spelling.
+- Plugin exports look dropped ⇒ `unwrapExports` trap: Loader prefers `exports.default` (postmortem 0001).
+- `!!js` in `disabled` always-truthy ⇒ expression objects are never falsy — silent permanent disable (postmortem 0002).
+- Tools suddenly ungated ⇒ observation-policy plugin not loaded beside fs tools.
+- Settings lost secrets ⇒ someone did `replace()` from a redacted descriptor.
+- Exit-code-based sandbox blame ⇒ use runnerFailureRules + denialSignatures, not exit status (postmortem 0004).
+- Git-installed plugin broke ⇒ missing `prepare` script or `allowBuilds` entry.
+
+## Workflow quickies
+
+- Verify composed config: `--dump-config` (grep your plugin).
+- Catalogs are generated: rerun `gen-tool-catalog`/`gen-config-catalog` style build steps; never hand-edit.
+- After changing client-visible signatures: rerun the strict build pipeline (`build:lib` faces) to regenerate Client declarations/codecs.
+- Stacked PR fix: fix the introducing PR, propagate up-stack.
+- i18n pair edited ⇒ update counterpart + re-record hashes in the same PR (CI red-flags drift).

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/glossary.md

@@ -0,0 +1,57 @@
+# Glossary — dsh-dev-skill
+
+Alphabetical key terms. Format: **Term** — definition (Ch N).
+
+- **Activation** — process-local period a continuable child Agent is resident; one per live child Session (Ch 14)
+- **asOfSeq** — snapshot watermark: seq of the last event a projection value reflects; −1 = empty log (Ch 16)
+- **BlockAssembler** — shared fold turning a `StreamChunk` stream back into `ContentBlock`s; reassembly is never each adapter's job (Ch 17)
+- **Bundle** — distribution format for Cordis config rows + code (`dsh.bundle` manifest); stays patchable by layers above (Ch 6)
+- **Capability seam** — swappable capability with three mandatory roles: Service Definition, Provider, Consumer (Ch 7)
+- **Compat block** — per-provider request-shape corrections in settings (`supportsDeveloperRole`, `maxTokensField`, `thinkingFormat`) (Ch 1)
+- **ConfinedArgv** — wrapped argv + enforcement fact, denialSignatures, runnerFailureRules returned by `ctx.sandbox.confine` (Ch 15)
+- **Continuable child** — durable child Session with optional live Activation; steerable/resumable, unlike one-shot SubagentRun (Ch 14)
+- **Declaration merging** — TS-only augmentation of the Cordis `Context`/`Events` interfaces; how plugins extend event maps (Ch 4)
+- **Derived history** — model transcript is folded from the session log (`deriveMessages()`), never stored separately (Ch 13)
+- **DomainSpec / defineDomain** — typed plugin persistence spec (zod, layout, compatibleVersions) opened via `storageDomain.open` (Ch 16)
+- **EpochHeader** — logged request state (config+system+tools) reconstructed from the latest `request/header` snapshot (Ch 13)
+- **Execution world** — fs + subprocess + sandbox move together on one provider swap (Ch 7)
+- **Fiber** — per-plugin runtime lifecycle instance (PENDING→LOADING→ACTIVE→…); the unit the registry loads/reloads (Ch 4)
+- **Fail-closed approval** — `approval/request` waterfall; absent or unanswerable asker = deny, never silent allow (Ch 7, 15)
+- **finalizeContent** — ToolDefinition-owned last content-only invariant run on a snapshotted result (Ch 8)
+- **FsObservation** — present@version / absent record per owner session; drives guarded write/edit decisions (Ch 15)
+- **InboxTarget** — `'next-turn' | 'next-step'` pending-message lists steering the agent loop (Ch 13)
+- **inheritedEventCount** — exact fork-inherited prefix length stored beside the fork header (Ch 16)
+- **inject** — hard service requirements on a plugin; entries start concurrently, ordering comes from inject not YAML position (Ch 4)
+- **InvariantInstaller** — package-attributed check bundle run in a dedicated child fiber via `ctx.invariants` (Ch 13)
+- **isolate** — Context scope label; service visibility is ancestor/isolate only — sibling shadowing does not exist (Ch 5)
+- **Layer order** — bundles (listed order) → profile patch → home patch → `--patch` argv; later layers win by whole-row restatement (Ch 2, 6)
+- **Live-preferred corpus** — session query prefers live `ctx.sessions`, falls back to persisted logs (Ch 16)
+- **LlmAdapter** — abstract provider contract: `stream()` emits `StreamChunk`s; one adapter call = one attempt (Ch 3, 17)
+- **LlmError** — stable-code error type; preserved by the agent loop; use for UNSUPPORTED_OPTION etc. (Ch 3, 17)
+- **Monotonic guard** — deny-or-abstain check with protected identity, registered after pre-execute allow, before execute; can never force-allow (Ch 8, 15)
+- **Peer dependency** — requirement for the host's shared service instance; bundling your own copy breaks identity (Ch 8)
+- **Persist-before-event** — attachments are durable before the owning session event is appended (Ch 16)
+- **PreToolDecision** — allow | deny(reason) | ask from `tools/pre-execute`; only `allowed-once` approval grants (Ch 15)
+- **Profile** — named composition in harness home listing bundles + user `cordis.patch.yml` (`web`, `headless`, `sdk`, `sdk-minimal`, `acp`) (Ch 6)
+- **ProjectionDefinition** — pure synchronous per-session state unit the projection registry drives, backfolds, and checkpoints (Ch 16)
+- **Remote controller** — API controller projecting a seam onto the Remote namespace; redaction/refusal live there (Ch 7)
+- **RemoteResult<T>** — client-remote result discriminated by `code`, never rejected; branch `if(!result.ok)` (Ch 19)
+- **Rescope** — vendored Cordis published as `@deepseek-ai/*` to avoid squatting upstream registry names (Ch 6)
+- **Reserved transport** — `run_code` (`ptc`/`both`): only wire-contribution tool, excluded from filterable layers (Ch 11)
+- **Revision token** — opaque settings/storage stat token; equal ⇒ unchanged, unequal promises nothing (Ch 16)
+- **SandboxMode** — default `read-only`; escalation is one-shot, strictly wider, needs justification (Ch 10, 15)
+- **session/end-seed** — constructor-only marker separating fork-inherited seed history from live work (Ch 12, 13)
+- **SessionEvent / SessionEventMap** — typed append-only log entry `{type, seq, time, data}`; vocabulary is merge-extensible (Ch 12)
+- **SettingsDescriptor** — `{ns, schema, value, revision, base, user, applies}` with mandatory `redactSecrets` on wire (Ch 18)
+- **Shadow price** — compaction metering: `shadowedRange`/`shadowedSeqs`/`shadowedTokenCount` on the replace op (Ch 12)
+- **Slot cardinality / priority** — single/list/keyed/chain dispatch axis; lower priority renders first; cell-id reuse = replacement (Ch 18)
+- **SpillRef** — `{locator, bytes, retrievalHint}` for tool text exceeding inline budget; locator opaque (Ch 14)
+- **Step / Turn** — step = one model request plus its tool calls; turn = zero+ steps, opens at first claim, closes when nothing is owed (Ch 6)
+- **StreamChunk** — closed 7-variant wire union (block-start/delta/block-end/usage/finish/…) adapters emit (Ch 17)
+- **SurfaceEventType** — the only three message-producing log types: `user/message`, `assistant/message`, `tool/result` (Ch 12, 13)
+- **TypertLookupMap** — wire↔object identity table for complex Host params crossing the Remote boundary (Ch 9)
+- **Vendoring** — pinned source under `vendor/<dir>/`, published as a release member (Ch 19)
+- **Waterfall veto** — returning without calling `next()` short-circuits the chain; observers must always call `next()` (Ch 4)
+- **WebBootGraph** — composed module graph written to `window.__DSH_BOOT__` before parser-preloaded scripts (Ch 17, 18)
+- **Whole-value event rule** — state-carrying log events carry complete post-change state, never deltas (Ch 16)
+- **unwrapExports trap** — Loader prefers `exports.default`, dropping sibling `inject`/`name`/`Config` (Ch 21)

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/patterns.md

@@ -0,0 +1,88 @@
+# Patterns — dsh-dev-skill
+
+Techniques and design patterns from the official docs. Format: name, when, how, trade-offs.
+
+## Three-Role Capability Seam
+**When to use**: a capability has ≥2 plausible implementations (shell backend, LLM provider, storage).
+**How**: abstract Service Definition (the seam, e.g. `ctx.fs`) + Provider subclass + thin provider-neutral Consumer tools. Keep model-facing tool names stable over providers.
+**Trade-offs**: more files/roles; pays off only for real replaceability — don't split a simple tool.
+
+## Request/Spec Split
+**When to use**: a seam has implementation defaults or caps.
+**How**: `resolve(request)` materializes a fully-resolved spec (workdir/timeout/stdoutMaxBytes…) before run/start; no hidden `??` inside execution.
+**Trade-offs**: one extra object; execution code becomes branch-free and testable.
+
+## Event-Gate Companion Plugin
+**When to use**: adding policy without forking providers (read-before-write, spill policy).
+**How**: listen at `fs/write-intent`/`fs/edit-intent` or `tools/post-execute` waterfalls instead of registering a provider.
+**Trade-offs**: policy lives beside, not inside, the provider — must be loaded alongside (bare fs tools lose the guard).
+
+## Framework-Drives-Domain-Computes (Projection)
+**When to use**: per-session derived state needed by host or clients.
+**How**: register a pure synchronous `ProjectionDefinition`; never subscribe to `session/event` and fold yourself.
+**Trade-offs**: constrained shape; the registry gives you backfolds, checkpoints, and `asOfSeq` for free.
+
+## Typed Domain over Routed Backend
+**When to use**: plugin persistence that is not a session event.
+**How**: `defineDomain` spec (zod, layout, compatibleVersions) + `storageDomain.open`; sync reads, write-chain durability before `domain/changed`.
+**Trade-offs**: schema discipline; backend routing becomes config (`storage-domain.backend`), not code.
+
+## One-Adapter-Call-One-Attempt
+**When to use**: writing an LLM adapter.
+**How**: disable provider-library retries; adapter `stream()` emits `StreamChunk`s; recovery happens at the agent-loop level; fold blocks with the shared `BlockAssembler`.
+**Trade-offs**: adapter stays thin; retry policy centralizes in `ResolvedRetryPolicy`.
+
+## Per-Operation Credential Read
+**When to use**: any code touching secrets.
+**How**: config holds a `CredentialRef` (env-var name); `resolve(ref)` on every call; never cache the value.
+**Trade-offs**: negligible cost; rotation reaches the next request with no restart.
+
+## Slot Injection with Fresh List Id
+**When to use**: contributing UI to a slot you don't own.
+**How**: `ctx.slots.inject(key, cb)` → `register({name, id, order}, Component)`; use a fresh list id; never runtime-import another plugin's client module.
+**Trade-offs**: single/keyed cells are replacement points — id reuse replaces, it does not merge.
+
+## Settings CAS Write
+**When to use**: any browser-side settings edit.
+**How**: `mutate()` with `SettingsPathOp` (set/unset) + expectedRevision; never `replace()` from a redacted view.
+**Trade-offs**: one extra round; wholesale replace from redacted descriptors silently deletes secrets.
+
+## Layer Restatement (Patch Override)
+**When to use**: changing a composed plugin's config.
+**How**: target the row by id in a later layer (profile/home/`--patch`) and restate every key — whole-config replacement, no deep merge.
+**Trade-offs**: verbose but explicit; partial restatement silently drops keys.
+
+## Dev Overlay via `--patch`
+**When to use**: iterating on a local plugin.
+**How**: absolute-path insert row + `--patch` flag (or persist in `cordis.patch.yml`); HMR hot-replaces on edit.
+**Trade-offs**: zero-install loop; remember it's a layer — shipping wants a bundle+profile.
+
+## Boot-and-Read Cataloging
+**When to use**: documenting tool/config surfaces.
+**How**: boot the real profile through the Loader and read `ctx.tools.schemas()` / generated catalogs; never hand-transcribe runtime-spread schemas.
+**Trade-offs**: needs a bootable environment; the generated+verified catalogs stay truthful.
+
+## Remote Non-Throw
+**When to use**: consuming client-remote calls.
+**How**: calls return `RemoteResult<T>`; branch `if(!result.ok)` and discriminate by `code`, never `instanceof`; assembly mistakes still crash loudly.
+**Trade-offs**: explicit error handling everywhere; no lost failures.
+
+## Background Job Gate
+**When to use**: a tool does long-running work.
+**How**: `ctx.jobs.start({kind, label, owner: exec.agent, run})` and return `{kind:'background', jobId}`; kill requests, never forces.
+**Trade-offs**: PTC mode must never parse prose for ids; job lifecycle (notices, `reported` flag) is managed.
+
+## Waterfall Discipline
+**When to use**: listening on any `@mode waterfall` event.
+**How**: observers always call `next()`; omitting it is a deliberate veto. Match the dispatch method to the event's declared mode.
+**Trade-offs**: misuse = accidental short-circuit; postmortem 0002 is the cautionary tale.
+
+## Dispose-to-Quiescence
+**When to use**: teardown of listeners + spawned work.
+**How**: close listener registries first, then kill → await done; keep ordered steps in ONE disposer (async disposers run concurrently).
+**Trade-offs**: returning early leaves orphans.
+
+## Conjunction-of-Evidence Classification
+**When to use**: attributing failed sandboxed runs.
+**How**: check `runnerFailureRules` first (runner never ran), then per-backend `denialSignatures` — never exit status or cross-backend unions.
+**Trade-offs**: requires exact signature tables; prevents SANDBOX_UNAVAILABLE mislabels (postmortem 0004).

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
+## Writing rules
+
+- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence.
+- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
+
+- The same rule stated in more than one home. Grep a distinctive phrase; keep one home and link the rest.
+- Narrated history or war stories: "previously", "now", "no longer", "used to", "renamed", "was moved", PRs, or commits. State the current fact; link an Agent Note or postmortem when needed.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Cross-reference with machine-checkable links, never free prose
+
+Link repository references with relative Markdown paths, never bare filenames or Agent Note numbers. `verify-md-links` rejects missing targets and dead `#fragment` anchors ([rationale](../.agents/notes/implemented/process/2026-06-18-markdown-cross-link-lint.md)).

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/agent-lifecycle.md

@@ -0,0 +1,84 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Agent Turn And Step Lifecycle
+
+This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>assistant/attempt</code>
+    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.
+
+`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.
+
+The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.
+
+SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.
+
+Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/src/docs/agent-lifecycle.zh.md

@@ -0,0 +1,86 @@
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
+
+# Agent 轮次与步骤生命周期
+
+[English](agent-lifecycle.md) | 中文
+
+此时序图是 [architecture.md](architecture.zh.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver-->>SDK: <code>agent/assistant-stream</code> chunk*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>assistant/attempt</code>
+    Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver-->>SDK: <code>agent/assistant-stream</code> committed end
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用，并嵌入精确的紧凑带时间 stream。空内容不会进入派生历史。失败、重试、取消或 stream error attempt 到达 settlement 时，如果没有 surface message，就会把 stream 记录为 `assistant/attempt`。实时 `agent/assistant-stream` chunk frame 是瞬态数据；回放读取任一种持久 settlement，如果进程在 settlement 前硬中断，则不会留下持久 attempt stream。
+
+`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
+
+以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息与 `startsRequestSeries`，除非有意替换。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
+
+需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
+
+维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。