Merge remote-tracking branch 'origin/master' into feat/acp-2-bridge

# Conflicts:
#	.agents/skills/dsh-code-review/SKILL.md
#	AGENTS.md
#	docs/rfc/proposed/2026-06-14-acp-agent-client-protocol.md

packages/README.md

@@ -20,7 +20,7 @@ dsh-invariants    ← dsh-llm, dsh-session, dsh-agent (dev-mode contract checks)
 dsh-acp           ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence  (ACP JSON-RPC bridge)
 ```
 
-The rule: plugins depend on interfaces, never on the concrete loop. `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [ADR 0009](../docs/adr/0009-capability-seams.md)).
+The rule: plugins depend on interfaces, never on the concrete loop. `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/2026-06-13-capability-seams.md)).
 
 ## What goes where
 

packages/acp/README.md

@@ -2,7 +2,7 @@
 
 The **Agent Client Protocol (ACP)** bridge: exposes the DeepSeek Harness coding agent as an ACP server over JSON-RPC stdio, so editors (Zed and other ACP clients) can drive it — streaming render, tool-call display, and resumable sessions.
 
-It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT an [ADR 0009](../../docs/adr/0009-capability-seams.md) capability seam. It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.
+It is a **client-driver / UI plugin**, the structured analogue of the readline `stdio-chat` plugin — NOT a loop change and NOT a [capability seam](../../docs/rfc/implemented/2026-06-13-capability-seams.md). It consumes the existing `agent/*` event taxonomy, the `dsh-agent` create/resume factory, and `dsh-session-persistence`.
 
 ## Service / plugin
 

packages/agent-loop/README.md

@@ -13,7 +13,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 `AgentLoop` also implements the `AgentFactory` seam and registers itself via `ctx.agents.setFactory(this)`, so plugins create/resume agents through `ctx.agents` (the interface):
 
 - `ctx.agents.create({ agentId, sessionId, meta?, agentOptions? })` — programmatic create on a caller-supplied `sessionId` (e.g. an ACP-generated id), NOT `${id}-session`.
-- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? })` — load a persisted session via `ctx.sessionPersistence` (RFC 009) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent).
+- `ctx.agents.resume({ agentId, resumeSessionId, agentOptions? })` — load a persisted session via `ctx.sessionPersistence` ([session persistence](../../docs/rfc/implemented/2026-06-14-session-persistence.md)) and resume an agent on it. The live session id is the resumed id; turn numbering and derived history continue from the loaded log. Requires a session-persistence backend (NOT hard-injected — non-persistent demos still work; `resume` rejects with a clear error when persistence is absent).
 
 ### Injected services
 

packages/agent-loop/src/loop.ts

@@ -119,7 +119,7 @@ export interface LoopHandle {
  *     drain queued → 'turn/start' → session('user/message'…) → emit agent/turn-start
  *     STEP loop:
  *       drain steering → session('steering/message')  ⟵ catches late steering
- *       session('step/start'); emit agent/step-start    ⟵ append before emit (ADR 0003)
+ *       session('step/start'); emit agent/step-start    ⟵ append before emit (the event-sourcing RFC)
  *       assembly = ctx.systemPrompt.assemble()        ⟵ waterfall system-prompt/assemble
  *       req = {model, system, tools, messages: session.deriveMessages(), signal}
  *       req = waterfall agent/request                 ⟵ hooks/compaction/model-switch
@@ -161,7 +161,7 @@ export async function runLoop(ctx: Context, agent: LoopAgent, handle: LoopHandle
       // before turn/start) — no turn/start was appended, so no turn is open and
       // none is owed. A session `error` here would land outside any turn (after
       // the previous turn/end), where the persistence backend drops it as a
-      // crash tail (ADR 0017). Report via agent/error + the logger only; the
+      // crash tail (the turn-enclosure RFC). Report via agent/error + the logger only; the
       // driver survives and moves on.
       const err = toError(error)
       ctx.logger.warn(`agent "${agent.id}": turn ${turn} failed before it started: ${err.message}`)
@@ -202,7 +202,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
   // Close the open step exactly once (idempotent via stepOpen). The
   // agent/step-end emit is contained: a throwing step-end listener must not
   // abort finalization and strand the turn open (turn/end balance > notifying
-  // one bad listener). Appended before the emit (ADR 0003 append-before-emit).
+  // one bad listener). Appended before the emit (the event-sourcing RFC append-before-emit).
   const closeStep = (): void => {
     if (!stepOpen) return
     stepOpen = false
@@ -241,7 +241,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // turn has already ended — the only way here is a throwing agent/turn-end
     // listener after closeTurn(true) already appended turn/end — appending now
     // would land the error AFTER the last turn/end, where the persistence
-    // backend treats it as a crash tail and drops it on resume (ADR 0017). In
+    // backend treats it as a crash tail and drops it on resume (the turn-enclosure RFC). In
     // that case report via agent/error + the logger only; the turn is balanced.
     if (!turnEnded) {
       // Set `reason` BEFORE the append: Session.append pushes the error event
@@ -346,7 +346,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
       }
 
       // The successful step's finish reason carries forward: a `max-tokens`
-      // step makes the whole turn end `max-tokens` (RFC 010's rule "any
+      // step makes the whole turn end `max-tokens` (the ACP RFC's rule "any
       // max-tokens step surfaces as max-tokens"). `stepFinishReason` returns
       // `max-tokens` or `undefined`, so a later ordinary step never resets a
       // max-tokens turn back to completed, and a never-truncated turn keeps the
@@ -393,7 +393,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // so a throwing listener on the `turn/start` append leaves turn/start in the
     // log even though execution never reached the lines after that append.
     // Gating on a "turn started" boolean would skip turn/end and leave a
-    // permanently OPEN turn that poisons the next turn/replay (ADR 0017). We
+    // permanently OPEN turn that poisons the next turn/replay (the turn-enclosure RFC). We
     // check the log for THIS turn's turn/start: present means a turn/end is owed
     // (or was already appended — closeTurn/failTurn are idempotent, so running
     // them again is a safe no-op that still preserves the disposed/error reason
@@ -428,7 +428,7 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // AFTER turn/end to be a checkpoint — so there is no in-turn position left
     // for a session `error` event. Appending one here would land it after the
     // last turn/end, where the persistence backend treats it as a crash tail
-    // and drops it on resume (ADR 0017: every event is turn-enclosed). Report
+    // and drops it on resume (the turn-enclosure RFC: every event is turn-enclosed). Report
     // the failure via agent/error + the logger only; persistence keeps the
     // buffered events for the next flush/dispose, so nothing is lost.
     const err = toError(error)
@@ -568,7 +568,7 @@ export function lastTurnNumber(session: Session): number {
  * before `turn/start`, or the post-`turn/end` flush window before status
  * returns to idle), so status is not a reliable open-turn signal. Used by
  * `inject()` to choose between appending into an open turn vs. wrapping the
- * injection in its own one-shot turn (ADR 0017).
+ * injection in its own one-shot turn (the turn-enclosure RFC).
  */
 export function isTurnOpen(session: Session): boolean {
   const last = session.events.findLast(e => e.type === 'turn/start' || e.type === 'turn/end')

packages/agent-loop/tests/coverage-edges.spec.ts

@@ -301,7 +301,7 @@ describe('disposed vs aborted branching', () => {
   })
 })
 
-describe('structured tool error propagation (RFC 005 pt 2)', () => {
+describe('structured tool error propagation (the runtime-validation RFC, part 2)', () => {
   it('forwards a tool HarnessError onto the tool/result session event', async () => {
     const { HarnessError } = await import('@deepseek-ai/dsh-llm')
     // First model turn calls the tool; second turn (after the tool result is

packages/agent-loop/tests/properties.spec.ts

@@ -1,8 +1,8 @@
 /**
- * Property-based tests for the agent loop's inbox/turn scheduling (RFC 001 →
- * ADR 0013). Deterministic by construction: schedules are driven through the
- * `agent/status` settle signal (no wall-clock sleeps), so a flake is a finding,
- * not timing noise.
+ * Property-based tests for the agent loop's inbox/turn scheduling (the
+ * property-testing RFC). Deterministic by construction: schedules are driven
+ * through the `agent/status` settle signal (no wall-clock sleeps), so a flake
+ * is a finding, not timing noise.
  *
  * Invariants: every sent message appears exactly once in the log (none lost);
  * turn numbers strictly increase; status transitions follow the legal machine

packages/agent-loop/tests/resume.spec.ts

@@ -39,7 +39,7 @@ function waitForIdle(ctx: Context, agent: LoopAgent): Promise<void> {
   })
 }
 
-describe('RFC 009: AgentLoop factory create/resume', () => {
+describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
   it('createAgent uses the caller-supplied sessionId (not ${id}-session)', async () => {
     const adapter = new MockAdapter([textResponse('hi')])
     const { ctx } = await persistentHarness(adapter)
@@ -128,7 +128,7 @@ describe('RFC 009: AgentLoop factory create/resume', () => {
 
   it('an idle inject() is flushed durably on its own (survives without explicit flush/dispose)', async () => {
     // Lifecycle 1: run a turn, then inject context while idle. The idle inject
-    // wraps its context/message in a one-shot turn AND checkpoints it (ADR 0017)
+    // wraps its context/message in a one-shot turn AND checkpoints it (the turn-enclosure RFC)
     // — without an explicit flush or clean dispose, the notice must still reach
     // disk, since a crash before the next turn would otherwise lose it.
     const adapter1 = new MockAdapter([textResponse('answer')])

packages/agent-loop/tests/review-fixes.spec.ts

@@ -619,7 +619,7 @@ describe('P1-6: step/start is appended before agent/step-start is emitted', () =
     const agent = ctx.agentLoop.create('a-step-order', { model: 'mock' })
 
     // Capture, at the moment agent/step-start fires, whether the matching
-    // step/start event is already in the log (append-before-emit, ADR 0003).
+    // step/start event is already in the log (append-before-emit, the event-sourcing RFC).
     const observed: { turn: number; step: number; lastEventType: string | undefined; sawStepStart: boolean }[] = []
     ctx.on('agent/step-start', (subject, turn, step) => {
       if (subject !== agent) return
@@ -828,7 +828,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
     // loop must therefore still owe (and append) a turn/end — deciding "owed"
     // from the log via isTurnOpen, not a "turn started" flag that the throw
     // skipped. Otherwise the turn stays permanently open and poisons the next
-    // turn/replay (ADR 0017). (Uses the plain harness — NOT the invariants
+    // turn/replay (the turn-enclosure RFC). (Uses the plain harness — NOT the invariants
     // oracle — because the throwing listener is itself a session/event
     // subscriber.)
     const adapter = new MockAdapter([textResponse('turn 2')])
@@ -868,7 +868,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
     // Regression: a normal turn completes, closeTurn(true) appends turn/end and
     // emits agent/turn-end whose listener throws. The error must NOT be appended
     // as a session event after turn/end — that would sit past the commit
-    // boundary and be dropped as a crash tail on resume (ADR 0017). It is
+    // boundary and be dropped as a crash tail on resume (the turn-enclosure RFC). It is
     // surfaced via agent/error instead, and the log's last event is turn/end.
     const adapter = new MockAdapter([textResponse('done'), textResponse('next ok')])
     const ctx = await balancedHarness(adapter)

packages/agent/README.md

@@ -18,7 +18,7 @@ Agent *creation* is provided by whichever plugin implements `AgentFactory` (phas
 
 - `ctx.agents.setFactory(factory: AgentFactory): () => void` — register the creation factory (the loop calls this on construction). Throws on a second factory; the slot clears on dispose.
 - `ctx.agents.create(options: CreateAgentOptions): Agent` — construct, start, AND register a new agent on a caller-supplied `sessionId` (with optional `meta.cwd`). Distinct from `register` (which only records). Throws if no factory is registered.
-- `ctx.agents.resume(options: ResumeAgentOptions): Promise<Agent>` — load a persisted session (RFC 009) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
+- `ctx.agents.resume(options: ResumeAgentOptions): Promise<Agent>` — load a persisted session ([session persistence](../../docs/rfc/implemented/2026-06-14-session-persistence.md)) and resume an agent on it. Async; rejects if no factory is registered, or if the factory finds session persistence unconfigured.
 
 ### Events
 
@@ -53,7 +53,7 @@ The handle every plugin programs against:
 
 - `agent.send(content, options?)` — queue a message; starts a turn when idle
 - `agent.steer(content, options?)` — steer a running turn (inject between steps); behaves like `send` when idle
-- `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed (ADR 0017)
+- `agent.inject(content, options?)` — inject in-session context (context/message event); the next request sees it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../docs/rfc/implemented/2026-06-15-turn-enclosure-invariant.md))
 - `agent.abort(reason?)` — abort the in-flight step
 - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit), the signal a teardown awaits (`abort()` then `await whenIdle()`). Observes the transition without disposing the agent.
 - `agent.session`, `agent.status`, `agent.options`, `agent.id`

packages/agent/src/types.ts

@@ -64,7 +64,7 @@ export interface Agent {
    * request sees at its chronological position, rendered as tagged synthetic
    * context rather than a user prompt. Does not run the model.
    *
-   * Turn-enclosure (ADR 0017): an inject while a turn is open joins that turn;
+   * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn;
    * an inject while idle wraps its `context/message` in a one-shot `injection`
    * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for
    * durability, so every event stays inside a turn and a persistence backend

packages/invariants/README.md

@@ -44,7 +44,7 @@ On any violation it throws `InvariantError` (`code: 'INVARIANT'`).
 
 ## Why runtime, not deep-readonly types
 
-A `DeepReadonly<SessionEvent>` is high type-noise across every log consumer, and a plugin can cast straight through it. A dev-mode freeze plus these assertions catch real corruption at zero production cost and zero type noise. The always-on half of that defense — cloning derived messages so request/adapter mutation can't reach back into the log — lives in `dsh-session`'s `deriveMessages`. This package is the dev-mode tripwire. See [ADR 0012](../../docs/adr/0012-dev-invariants-over-deep-readonly.md).
+A `DeepReadonly<SessionEvent>` is high type-noise across every log consumer, and a plugin can cast straight through it. A dev-mode freeze plus these assertions catch real corruption at zero production cost and zero type noise. The always-on half of that defense — cloning derived messages so request/adapter mutation can't reach back into the log — lives in `dsh-session`'s `deriveMessages`. This package is the dev-mode tripwire. See [dev-mode invariants](../../docs/rfc/implemented/2026-06-11-dev-invariants-over-deep-readonly.md).
 
 ## Seeded sessions
 

packages/invariants/src/index.ts

@@ -10,7 +10,7 @@
  * taxonomy: the assertions below ARE the contract.
  *
  * Why runtime assertions instead of compile-time deep-readonly types? See
- * ADR 0012. Briefly: a `DeepReadonly<SessionEvent>` is high type-noise across
+ * the dev-invariants RFC. Briefly: a `DeepReadonly<SessionEvent>` is high type-noise across
  * every log consumer and a plugin casts straight through it; a dev-mode freeze
  * + assertions catch real corruption at zero production cost and zero type
  * noise. The always-on half of that defense (cloning derived messages) lives
@@ -71,7 +71,7 @@ interface SessionTrace {
  * frozen: `Session.append()` accepts event data from arbitrary plugins/tools,
  * so a caller can hand us a SHALLOW-frozen object whose descendants are still
  * mutable. Skipping an already-frozen node (the obvious idempotence shortcut)
- * would leave exactly the kind of mutable history ADR 0012 means to catch. A
+ * would leave exactly the kind of mutable history the dev-invariants RFC means to catch. A
  * `WeakSet` of visited objects keeps it terminating on cycles and avoids
  * re-walking shared subtrees / already-processed seed events.
  */
@@ -107,7 +107,7 @@ function checkEvent(trace: SessionTrace, event: SessionEvent): void {
 
   // Boundary/step-scoped events have explicit cases; every OTHER event type —
   // including plugin-added (merge-extensible) SessionEventMap keys — is caught
-  // by the `default` and must be turn-enclosed (ADR 0017). No assertNever: an
+  // by the `default` and must be turn-enclosed (the turn-enclosure RFC). No assertNever: an
   // unknown variant is valid, not a compile error.
   switch (event.type) {
     case 'turn/start': {
@@ -168,7 +168,7 @@ function checkEvent(trace: SessionTrace, event: SessionEvent): void {
       }
       break
     }
-    // Turn-enclosure (ADR 0017): EVERY session event not handled by a boundary
+    // Turn-enclosure (the turn-enclosure RFC): EVERY session event not handled by a boundary
     // case above must sit inside an open turn. The durable session log uses the
     // turn as its commit/replay boundary (the JSONL backend treats anything
     // after the last turn/end as a crash tail), so a bare event between turns is

packages/invariants/tests/invariants.spec.ts

@@ -88,7 +88,7 @@ describe('session-log invariants', () => {
   it('rejects a message event appended outside any open turn (turn-enclosure)', async () => {
     const { ctx } = await setup({ freeze: false })
     const session = ctx.sessions.create()
-    // No turn open: every message-bearing event must be turn-enclosed (ADR 0017).
+    // No turn open: every message-bearing event must be turn-enclosed (the turn-enclosure RFC).
     expect(() => session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }))
       .toThrow(/outside any open turn/)
     expect(() => session.append('context/message', { content: [{ type: 'text', text: 'ctx' }], source: { kind: 'user' } }))
@@ -99,7 +99,7 @@ describe('session-log invariants', () => {
     const { ctx } = await setup({ freeze: false })
     const session = ctx.sessions.create()
     // usage and error are turn-scoped: outside a turn they would land past the
-    // commit boundary and be dropped on resume (ADR 0017).
+    // commit boundary and be dropped on resume (the turn-enclosure RFC).
     expect(() => session.append('usage', { turn: 1, step: 1, usage: { inputTokens: 1, outputTokens: 1 } }))
       .toThrow(/outside any open turn/)
     expect(() => session.append('error', { turn: 1, step: 1, message: 'boom' }))
@@ -276,7 +276,7 @@ describe('dev-freeze', () => {
     // A caller hands in a SHALLOW-frozen block whose nested array is still
     // mutable. deepFreeze must descend into the already-frozen object and
     // freeze the descendant, not short-circuit on the frozen container —
-    // otherwise dev-mode misses exactly the history mutation ADR 0012 catches.
+    // otherwise dev-mode misses exactly the history mutation the dev-invariants RFC catches.
     // `append` snapshots `data`, so the freeze applies to the LOGGED clone, not
     // the caller's input — read the event back and assert on its data.
     const innerContent: { type: 'text'; text: string }[] = [{ type: 'text', text: 'inner' }]

packages/llm/README.md

@@ -43,4 +43,4 @@ Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta
 
 ### Real adapters
 
-Two adapters implement `LlmAdapter` against this vocabulary, deliberately built on different internals to keep the contract honest (see [ADR 0010](../../docs/adr/0010-twin-llm-adapters.md)): [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) (hand-rolled fetch/SSE) and [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) (via `@earendil-works/pi-ai`). The pair pinned down the `StreamChunk` conventions now documented in `types.ts` (usage before finish, raw-string tool arguments, the two sanctioned error paths).
+Two adapters implement `LlmAdapter` against this vocabulary, deliberately built on different internals to keep the contract honest (see [the twin LLM adapters](../../docs/rfc/implemented/2026-06-13-twin-llm-adapters.md)): [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) (hand-rolled fetch/SSE) and [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) (via `@earendil-works/pi-ai`). The pair pinned down the `StreamChunk` conventions now documented in `types.ts` (usage before finish, raw-string tool arguments, the two sanctioned error paths).

packages/llm/src/error.ts

@@ -6,7 +6,7 @@
  * event so retry/sandbox plugins and replay can distinguish failure classes.
  *
  * Lives in dsh-llm (the leaf package every other imports) so a single base is
- * shared without a new dependency edge. See ADR 0015.
+ * shared without a new dependency edge. See the error-taxonomy RFC.
  *
  * @module @deepseek-ai/dsh-llm/error
  */

packages/llm/tests/assembler.spec.ts

@@ -169,7 +169,7 @@ describe('assertNever', () => {
 
 describe('BlockAssembler regressions (property-test findings)', () => {
   it('first block-end wins: a duplicate block-end for a closed index is ignored', () => {
-    // Found by fast-check (RFC 001): two block-ends at the same index made the
+    // Found by fast-check (the property-testing RFC): two block-ends at the same index made the
     // streamed prefix (first block) disagree with final blocks() (second
     // block). The first close must win — same straggler rule as post-close
     // deltas — so streaming and one-shot assembly stay identical.

packages/llm/tests/properties.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Property-based tests for the BlockAssembler (RFC 001 → ADR 0013).
+ * Property-based tests for the BlockAssembler (the property-testing RFC).
  *
  * The assembler is protocol-shaped: arbitrary interleavings of block-start,
  * deltas, block-end, usage, and finish — valid and malformed (duplicate

packages/session-persistence-jsonl/README.md

@@ -24,7 +24,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence
 
 - **Lazy materialization.** `create(meta)` writes nothing; the `.jsonl` (header + first batch) is written atomically (temp-write + `fsync` + rename) on the first `append`. A created-but-never-appended session leaves nothing on disk and is absent from `has`/`list`.
 - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`.
-- **Crash recovery — close, don't truncate.** A crash can leave a log whose final turn never closed (real events after the last `turn/end`). `load` PRESERVES those events (a turn can be huge — they are real work) and closes the orphaned turn by durably appending synthetic boundary events: an error `tool/result` for every `tool-call` the crash left unanswered (the loop logs the assistant message before running the tools, so a mid-tool crash leaves dangling calls — and `deriveMessages()` would replay an assistant tool-call with no result, which providers reject), then a `step/end` if a step was open, then `turn/end {kind:'interrupted'}`, returning a balanced log. Only a never-fully-written **torn tail fragment** (a final line with no newline / unparseable) is `ftruncate`d away before the closers are written. See ADR 0018.
+- **Crash recovery — close, don't truncate.** A crash can leave a log whose final turn never closed (real events after the last `turn/end`). `load` PRESERVES those events (a turn can be huge — they are real work) and closes the orphaned turn by durably appending synthetic boundary events: an error `tool/result` for every `tool-call` the crash left unanswered (the loop logs the assistant message before running the tools, so a mid-tool crash leaves dangling calls — and `deriveMessages()` would replay an assistant tool-call with no result, which providers reject), then a `step/end` if a step was open, then `turn/end {kind:'interrupted'}`, returning a balanced log. Only a never-fully-written **torn tail fragment** (a final line with no newline / unparseable) is `ftruncate`d away before the closers are written. See [session persistence](../../docs/rfc/implemented/2026-06-14-session-persistence.md).
 - **Contiguous-seq.** `load` rejects a mid-log parse error or `seq` gap (unloadable); `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
 - **Format version.** Only v1 is supported; `load` rejects an unknown version. A future format change requires a version bump + migration.
 

packages/session-persistence-jsonl/src/format.ts

@@ -128,7 +128,7 @@ export function eventLine(event: SessionEvent): string {
  * fully-written events sit after the last `turn/end`. Those are PRESERVED (a
  * single turn can be huge in a long-horizon task — truncating it would destroy
  * real work); the backend closes the orphaned open turn with a synthetic
- * `turn/end {kind:'interrupted'}` on reload (ADR 0018). Only a TORN trailing
+ * `turn/end {kind:'interrupted'}` on reload (the session-persistence RFC). Only a TORN trailing
  * fragment — a final line never fully flushed (no newline, unparseable, or a
  * seq gap) — is excluded; it bounds the preserved region. A parse error or seq
  * gap AT OR BEFORE the last committed `turn/end` is committed-data corruption
@@ -208,7 +208,7 @@ export function scanLog(buffer: Buffer): { meta: SessionMeta; events: SessionEve
   // last turn/end — those are real, durably-written work and must NOT be
   // truncated (a single turn can be huge in a long-horizon task; the orphaned
   // open turn is closed with a synthetic turn/end on reload, not discarded —
-  // ADR 0018). The walk stops at the first hole (unparseable line or seq gap):
+  // the session-persistence RFC). The walk stops at the first hole (unparseable line or seq gap):
   //   - if that hole is AT OR BEFORE the last committed turn/end, committed data
   //     was damaged → the session is unloadable (throw);
   //   - if it is AFTER (or there is no committed turn/end yet), it is the

packages/session-persistence-jsonl/src/index.ts

@@ -274,7 +274,7 @@ export class SessionPersistenceJsonl extends SessionPersistence {
     // continue with no special-casing. Synthesize the boundary events (a
     // step/end if a step was open, then a turn/end {kind:'interrupted'}); the
     // interrupted turn's real events are preserved, never truncated (a turn can
-    // be huge — ADR 0018).
+    // be huge — the session-persistence RFC).
     const closers = interruptedTurnClosers(events)
     const balanced = [...events, ...closers]
 

packages/session-persistence-sqlite/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-session-persistence-sqlite
 
-A SQLite durable session-persistence backend — a second `SessionPersistence` implementation ([ADR 0018](../../docs/adr/0018-session-persistence.md)), built to validate that the abstract seam and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
+A SQLite durable session-persistence backend — a second `SessionPersistence` implementation ([session persistence](../../docs/rfc/implemented/2026-06-14-session-persistence.md)), built to validate that the abstract seam and the shared `runPersistenceContract` suite are genuinely backend-agnostic. It satisfies the SAME contract as `dsh-session-persistence-jsonl` (append-only, contiguous-seq, lazy materialization, interrupted-turn close on load), expressed over `node:sqlite` rows instead of file bytes.
 
 > **TODO:** this backend talks to `node:sqlite` directly. If a cordis database service (`cordis/db` / a `@cordisjs` SQL driver plugin) is adopted, route through that instead of holding a raw `DatabaseSync` here — the contract surface (`SessionPersistence`) would not change, only the storage driver.
 

packages/session-persistence-sqlite/src/index.ts

@@ -229,7 +229,7 @@ export class SessionPersistenceSqlite extends SessionPersistence {
     // agree — both append routes then continue with no special-casing. Synthesize
     // the boundary events (a step/end if a step was open, then a
     // turn/end {kind:'interrupted'}); the interrupted turn's real events are
-    // preserved, never truncated (ADR 0018).
+    // preserved, never truncated (the session-persistence RFC).
     const closers = interruptedTurnClosers(preserved)
     const balanced = [...preserved, ...closers]
 

packages/session-persistence-sqlite/src/schema.ts

@@ -131,7 +131,7 @@ export function rowToEvent(row: EventRow): SessionEvent {
  * fully-written rows sit after the last `turn/end`. Those are PRESERVED — a
  * single turn can be huge in a long-horizon task, so truncating it would
  * destroy real work; the backend closes the orphaned open turn with a synthetic
- * `turn/end {kind:'interrupted'}` on load (ADR 0018). The ONLY thing excluded is
+ * `turn/end {kind:'interrupted'}` on load (the session-persistence RFC). The ONLY thing excluded is
  * a torn trailing fragment — a row whose `data` never parses, or a seq gap —
  * AFTER the last committed `turn/end`; that bounds the preserved region and its
  * seq is returned as `tornFrom` so `load` can physically delete it.

packages/session-persistence/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-session-persistence
 
-The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, list, and update sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([ADR 0009](../../docs/adr/0009-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
+The abstract durable session-persistence seam (`ctx.sessionPersistence`). Defines WHAT a persistence backend does — durably store, reload, list, and update sessions — without saying HOW. Mirrors the `dsh-bash` capability-seam template ([capability seams](../../docs/rfc/implemented/2026-06-13-capability-seams.md)): an abstract service here, a concrete implementation in a sibling package, consumers that inject the interface.
 
 The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage) travels separately as `SessionMeta`, owned by `dsh-session` and re-exported here.
 

packages/session-persistence/src/index.ts

@@ -102,7 +102,7 @@ export abstract class SessionPersistence extends Service {
    * fragment (a half-written final record) is discarded. Returned events are
    * contiguous (`events[i].seq === i`); a parse error or a `seq` gap in the
    * COMMITTED region (at or before the last real `turn/end`) makes the session
-   * unloadable (reject). Rejects an unknown format `version`. See ADR 0018 for
+   * unloadable (reject). Rejects an unknown format `version`. See the session-persistence RFC for
    * the crash-recovery contract.
    */
   abstract load(id: SessionId): Promise<{ meta: SessionMeta; events: SessionEvent[] }>

packages/session/src/json.ts

@@ -1,7 +1,7 @@
 /**
  * JSON-serializability validation for session event data.
  *
- * The session event log is the durable source of truth (ADR 0003/0018): every
+ * The session event log is the durable source of truth (the event-sourcing / session-persistence RFCs): every
  * `event.data` must round-trip losslessly through JSON so any persistence
  * backend can store and reload it byte-identically. This invariant belongs to
  * the log itself — `Session.append` enforces it at the source, so a

packages/session/src/repair.ts

@@ -16,7 +16,7 @@
  *   3. a `turn/end` carrying the merge-extensible `{ kind: 'interrupted' }` reason.
  *
  * The marker records that the turn was cut short by a crash, not completed by
- * the model. See ADR 0018.
+ * the model. See the session-persistence RFC.
  *
  * Why the synthetic tool results matter: `deriveMessages()` renders the
  * `tool-call` blocks inside a durable `assistant/message` but only emits a

packages/session/src/types.ts

@@ -102,7 +102,7 @@ export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap]
  * still wins). It is distinct from `completed` so a consumer (e.g. the ACP
  * bridge mapping to `StopReason: 'max_tokens'`) can tell a clean stop from a
  * truncated one. The next variants to add — when an adapter/loop first emits
- * them — are `refusal` and `max_turn_requests` (both named by RFC 010 as ACP
+ * them — are `refusal` and `max_turn_requests` (both named by the ACP RFC as ACP
  * stop reasons); no current adapter produces a `refusal` finish (unknown
  * DeepSeek finish reasons collapse to `error`), so it is deliberately omitted
  * until one does.
@@ -121,7 +121,7 @@ export interface TurnEndReasonMap {
    * the crash) and are PRESERVED, not discarded: a single turn can be huge in a
    * long-horizon task (many steps, large tool output), so truncating it would
    * lose real work. The marker records that the turn was cut short, not that the
-   * model completed it. See ADR 0018.
+   * model completed it. See the session-persistence RFC.
    */
   interrupted: { kind: 'interrupted' }
 }

packages/session/tests/properties.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Property-based tests for the Session event log (RFC 001 → ADR 0013).
+ * Property-based tests for the Session event log (the property-testing RFC).
  *
  * Generates arbitrary event logs and asserts the derivation invariants the
  * agent loop and replay depend on: deriveMessages is deterministic and

packages/tool-bash/src/index.ts

@@ -29,10 +29,11 @@ export const inject = ['tools', 'bash']
 
 /**
  * Validate the constraints the SchemaSpec can't express. `defineTool` now
- * validates parsed args against the SchemaSpec before `execute` runs (RFC 005
- * → ADR 0011), so type/required/enum checks are already done and `args` is
- * the validated `InferArgs` shape here. What remains are value constraints the
- * DSL has no vocabulary for: non-empty strings and a positive, finite timeout.
+ * validates parsed args against the SchemaSpec before `execute` runs (the
+ * arg-validation RFC), so type/required/enum checks are already done and `args`
+ * is the validated `InferArgs` shape here. What remains are value constraints
+ * the DSL has no vocabulary for: non-empty strings and a positive, finite
+ * timeout.
  */
 function validateBashArgs(args: {
   command: string
@@ -54,7 +55,7 @@ function validateBashArgs(args: {
 
 /**
  * Reject an empty `task_id`. Type and presence are guaranteed by the
- * SchemaSpec validation (ADR 0011); only the non-empty constraint, which the
+ * SchemaSpec validation (the arg-validation RFC); only the non-empty constraint, which the
  * DSL can't express, is left to check here.
  */
 function validateTaskId(value: string): string {

packages/tool-bash/tests/tools.spec.ts

@@ -119,7 +119,7 @@ describe('bash tool', () => {
   })
 
   // Type and required-key violations are now rejected by the harness
-  // (defineTool validates against the SchemaSpec — ADR 0011) before execute.
+  // (defineTool validates against the SchemaSpec — the arg-validation RFC) before execute.
   it.each([
     [{}, /missing required property "command"/],
     [{ command: 42, description: 'd' }, /"command" must be a string/],

packages/tools/tests/properties.spec.ts

@@ -1,8 +1,8 @@
 /**
- * Property-based tests for the tool-schema DSL (RFC 001 → ADR 0013), including
- * the RFC 001 ↔ 005 composition: generated args that satisfy a SchemaSpec must
+ * Property-based tests for the tool-schema DSL (the property-testing RFC), including
+ * the the property-testing ↔ runtime-validation composition composition: generated args that satisfy a SchemaSpec must
  * pass validateArgs, and targeted corruptions must be rejected. This closes the
- * validator/InferArgs drift risk noted in ADR 0011.
+ * validator/InferArgs drift risk noted in the arg-validation RFC.
  */
 
 import { describe, expect, it } from 'vitest'
@@ -108,7 +108,7 @@ describe('schema DSL properties', () => {
     }))
   })
 
-  it('RFC 001↔005: args satisfying the spec pass validateArgs', () => {
+  it('the property-testing ↔ runtime-validation composition: args satisfying the spec pass validateArgs', () => {
     fc.assert(fc.property(
       specArb(2).chain(spec => fc.tuple(fc.constant(spec), validArgsForSpec(spec))),
       ([spec, args]) => {
@@ -117,7 +117,7 @@ describe('schema DSL properties', () => {
     ))
   })
 
-  it('RFC 001↔005: dropping a required key is always rejected', () => {
+  it('the property-testing ↔ runtime-validation composition: dropping a required key is always rejected', () => {
     fc.assert(fc.property(
       specArb(1)
         .filter(spec => requiredKeys(spec).length > 0)
@@ -132,7 +132,7 @@ describe('schema DSL properties', () => {
     ))
   })
 
-  it('RFC 001↔005: a non-object top level is always rejected', () => {
+  it('the property-testing ↔ runtime-validation composition: a non-object top level is always rejected', () => {
     fc.assert(fc.property(
       specArb(1),
       fc.oneof(fc.string(), fc.integer(), fc.boolean(), fc.constant(null), fc.array(fc.anything())),

packages/tools/tests/tools.spec.ts

@@ -609,7 +609,7 @@ describe('ToolRegistry.get', () => {
   })
 })
 
-describe('validateArgs (RFC 005 part 1)', () => {
+describe('validateArgs (the runtime-validation RFC, part 1)', () => {
   it('returns [] for valid args and is total over malformed input', () => {
     const spec = {
       path: { type: 'string', required: true },
@@ -709,7 +709,7 @@ describe('validateArgs (RFC 005 part 1)', () => {
   })
 })
 
-describe('defineTool validation (RFC 005 part 1)', () => {
+describe('defineTool validation (the runtime-validation RFC, part 1)', () => {
   it('returns an isError result with the violations when the model sends bad args', async () => {
     const ctx = await setup()
     ctx.tools.register(defineTool({