Merge branch 'feat/acp-2-bridge' into feat/acp-3-multi-session

# Conflicts:
#	docs/rfc/proposed/2026-06-14-acp-multi-session.md
#	packages/acp/src/index.ts

packages/AGENTS.md

@@ -5,10 +5,12 @@ This directory contains all `@deepseek-ai/dsh-*` harness packages. When editing
 - **Effect-based registrations**: every contribution (tool, section, adapter, agent, event listener) goes through `ctx.effect()` / `ctx.on()`, and `register()` methods return disposers. Never use bare arrays or manual cleanup.
 - **Declaration merging**: services declare their ctx key in `declare module 'cordis' { interface Context { } }` and their events in `interface Events`. Merge-extensible maps (`ContentBlockMap`, `MessageSourceMap`, `FinishReasonMap`, `TurnTriggerMap`, `TurnEndReasonMap`, `SessionEventMap`) are how plugins add new variants.
 - **Waterfall semantics**: `ctx.waterfall` listeners receive `(...args, next)`; call `next()` to delegate, or return without it to short-circuit (veto). Never call `next()` after returning.
-- **Tests**: vitest in `packages/<name>/tests/*.spec.ts`. Every registry needs an HMR-safety test (register a plugin, dispose its fiber, assert cleanup). Err on the side of more tests — edge cases, error paths, event ordering, races.
+- **Plugin export shape — namespace OR default, never both.** A *service* package exports the service class as `export default` (the Loader instantiates it). A *function/namespace* plugin exports `name` / `inject` / `Config` / `apply` as separate named exports and **must NOT add `export default`** — the cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray default export collapses the module to the bare `apply` function and silently discards the `inject`/`name`/`Config` namespace, leaving the plugin with no injected services (it then throws `cannot get property … without inject` at load). See [docs/postmortem/0001](../docs/postmortem/0001-acp-default-export-drops-inject.md).
+- **Read an optional (non-injected) service via `ctx.get(name)`, not `ctx.<name>`.** For a service a plugin reads opportunistically but deliberately leaves out of `static inject` (e.g. `AgentLoop` reading `sessionPersistence`), the `ctx.<name>` property proxy resolves by an ancestor-only fiber walk that throws when the call arrives through a foreign traceable shadow (the service lives on a sibling fiber). `ctx.get(name)` is the topology-independent global-store lookup, strict by default (an inactive/absent backend reads as `undefined` — prefer it over the `ctx.get(name, false)` overload, which also skips the active-state check). Services that ARE in `static inject` resolve fine via `ctx.<name>`. See [docs/postmortem/0001](../docs/postmortem/0001-acp-default-export-drops-inject.md).
+- **Tests**: vitest in `packages/<name>/tests/*.spec.ts`. Every registry needs an HMR-safety test (register a plugin, dispose its fiber, assert cleanup). Err on the side of more tests — edge cases, error paths, event ordering, races. A plugin shipped via `cordis.yml` also needs at least one test that drives it through the REAL Loader/export path (hand-built `ctx.plugin({...})` mounts bypass `unwrapExports` and cannot catch a broken export shape) — see AGENTS.md § Defensive patterns "Line coverage is not behavior coverage". Real-API (with-key) e2e tests are cheap here (we are DeepSeek) and welcome — write many, especially smoke tests; see AGENTS.md § Secrets / .env.
 
 Naming notes:
-- Files `src/index.ts` export the service default + all public types
+- A *service* `src/index.ts` exports the service class as `export default` + all public types; a *function/namespace plugin* `src/index.ts` exports `name`/`inject`/`Config`/`apply` as named exports and NO default (see the plugin-export-shape rule above)
 - `src/types.ts` contain only types — no runtime code
 - Tests live at package level under `tests/`, not `src/__tests__/`
 - A package's README and module/JSDoc comments are part of the change: when you alter behavior (config keys, defaults, error codes, wire fields), update them in the same commit. CI runs `pnpm run doc-sync`, which typechecks fenced `ts` blocks in `packages/*/README.md` and verifies the event-taxonomy table — but it does NOT cover this file or prose drift (config keys, defaults, error codes), so those stay on the author.

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. **N concurrent sessions per connection** (RFC 011): each maps to its own `LoopAgent`, and every event is demuxed strictly by session id so two sessions streaming at once never interleave.
 
-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/acp/src/index.ts

@@ -172,6 +172,17 @@ export function apply(ctx: Context, config: AcpConfig): void {
   const agentName = config.agentName ?? 'deepseek-harness-acp'
   const agentVersion = config.agentVersion ?? '0.0.1'
 
+  // Capture the injected services NOW, during apply(), while we are inside this
+  // plugin's fiber (where `inject` grants access). The ACP method handlers run
+  // LATER, from the AgentSideConnection's JSON-RPC read loop — a context that is
+  // NOT this fiber's injection scope — so reading `ctx.agents` / `ctx.logger` /
+  // `ctx.sessionPersistence` lazily inside a handler throws "cannot get property
+  // … without inject". Resolving the references here and closing over them keeps
+  // the handlers working regardless of which fiber later invokes them.
+  const agents = ctx.agents
+  const sessionPersistence = ctx.sessionPersistence
+  const logger = ctx.logger
+
   // Live sessions keyed by id (RFC 011 multi-session), plus an agent→sessionId
   // reverse map so `agent/*` events (which carry only the Agent) demux in O(1).
   // The two stay in lockstep: a record is added to `sessions` and the agent to
@@ -225,7 +236,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
        failure (closed pipe), which the in-memory test transport never induces;
        the swallow is a defensive best-effort guard like the loop's emit traps */
     void Promise.resolve(conn.sessionUpdate(notification)).catch((error: unknown) => {
-      ctx.logger.warn(`acp: session/update failed: ${String(error)}`)
+      logger.warn(`acp: session/update failed: ${String(error)}`)
     })
   }
 
@@ -377,7 +388,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
         assertOpen()
         validateWorkspaceParams(params)
         const sessionId = randomUUID()
-        const agent = ctx.agents.create({
+        const agent = agents.create({
           agentId: sessionId,
           sessionId,
           meta: { cwd: params.cwd },
@@ -409,13 +420,13 @@ export function apply(ctx: Context, config: AcpConfig): void {
           // launched in workspace B: it would replay A's history while tools run
           // in B. (If the id is unknown to `list()`, fall through to resume,
           // which rejects with the backend's not-found error.)
-          const meta = (await ctx.sessionPersistence.list()).find(m => m.id === params.sessionId)
+          const meta = (await sessionPersistence.list()).find(m => m.id === params.sessionId)
           if (meta?.cwd !== undefined && meta.cwd !== process.cwd()) {
             throw invalidParams(
               `session was created in ${meta.cwd}, but the server's launch directory is ${process.cwd()}; honoring a different cwd is not yet supported — launch the server in the session's workspace`,
             )
           }
-          const agent = await ctx.agents.resume({
+          const agent = await agents.resume({
             agentId: params.sessionId,
             resumeSessionId: params.sessionId,
             agentOptions: agentOptions(config),
@@ -536,13 +547,19 @@ export function apply(ctx: Context, config: AcpConfig): void {
    * loop-level change); the single-in-flight-per-session rule bounds the worst
    * case to one short queued turn per session.
    *
-   * The agents themselves are NOT individually disposed/unregistered here — the
-   * factory (`ctx.agents.create`/`resume`) registers each on the AgentLoop fiber
-   * and returns no per-agent disposer, so registry entries are reclaimed when
-   * the host context disposes. On a bare client disconnect (without a host
-   * dispose) the idled agents linger in `ctx.agents` until shutdown; a reconnect
-   * spins up a fresh context, so this does not strand work. A per-agent disposal
-   * seam is a follow-up (TODO(rfc010-agent-disposal)).
+   * The agents are NOT individually disposed/unregistered here. The factory
+   * (`ctx.agents.create`/`resume`) registers each via `AgentLoop.start`'s
+   * `this.ctx.effect(...)`; because the factory is reached through this bridge's
+   * traceable service proxy, that effect's `this.ctx` is the CALLER context (the
+   * bridge fiber), so every registry entry is bound to the bridge fiber and is
+   * reclaimed when the bridge fiber disposes (whole-context dispose, or an
+   * ACP-only HMR `acpFiber.dispose()` — both unregister all the bridge's
+   * agents). What this teardown path handles is a bare client disconnect, which
+   * resolves `conn.closed` WITHOUT disposing the fiber: each live agent is
+   * idled+aborted here but stays in `ctx.agents` until the fiber is disposed.
+   * Since a reconnect spins up a fresh context, the lingering idle agents strand
+   * no work. A per-agent disposal seam (unregister on disconnect) is a follow-up
+   * (TODO(rfc010-agent-disposal)).
    */
   let quiescing: Promise<void> | undefined
   const quiesce = (): Promise<void> => {
@@ -580,7 +597,7 @@ export function apply(ctx: Context, config: AcpConfig): void {
      mid-run), and there is nothing else to act on once the connection is gone —
      the swallow mirrors notify(). */
   void conn.closed.then(quiesce).catch((error: unknown) => {
-    ctx.logger.warn(`acp: connection-close teardown failed: ${String(error)}`)
+    logger.warn(`acp: connection-close teardown failed: ${String(error)}`)
   })
   /* v8 ignore stop */
 
@@ -736,5 +753,3 @@ function toolResultContent(blocks: ContentBlock[]): { type: 'content'; content:
   }
   return out
 }
-
-export default apply

packages/acp/tests/dispose.spec.ts

@@ -38,7 +38,7 @@ describe('acp bridge — disposal & HMR safety', () => {
     // stay up and the transport is still live. A late session/new must hit the
     // `closed` guard and reject — NOT create an agent the disposed bridge can no
     // longer stream or settle. Verify the world: no agent appeared.
-    const harness = await makeBridgeHarness({ storageDir, script: [], childFiber: true })
+    const harness = await makeBridgeHarness({ storageDir, script: [] })
     await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
     const before = harness.ctx.agents.list().length
     await harness.acpFiber.dispose() // tear down ONLY the bridge
@@ -48,6 +48,25 @@ describe('acp bridge — disposal & HMR safety', () => {
     await harness.dispose()
   })
 
+  it('an agent created through the bridge is unregistered when ONLY the bridge fiber is disposed', async () => {
+    // The factory (`ctx.agents.create`) is reached through the bridge's
+    // traceable service proxy, so `AgentLoop.start`'s `this.ctx.effect(...)`
+    // registration binds to the CALLER context — the bridge fiber — not the
+    // AgentLoop fiber. Disposing JUST the bridge fiber (an ACP-only HMR reload)
+    // must therefore reclaim the agent's registry entry, even though agents/
+    // agent-loop stay up. This pins the fiber-ownership the bridge's teardown
+    // doc comment relies on; if a refactor rebinds the registration to the
+    // AgentLoop fiber, the agent would survive bridge dispose and this fails.
+    const harness = await makeBridgeHarness({ storageDir, script: [] })
+    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    expect(harness.ctx.agents.get(sessionId)).toBeDefined()
+
+    await harness.acpFiber.dispose() // tear down ONLY the bridge
+    expect(harness.ctx.agents.get(sessionId)).toBeUndefined()
+    await harness.dispose()
+  })
+
   it('no agent is created by a session/new after the bridge has closed (closed guard)', async () => {
     // After teardown (here a client disconnect sets `closed`), a late
     // `session/new` must NOT create an orphan agent the bridge can no longer

packages/acp/tests/harness.ts

@@ -148,8 +148,6 @@ export async function makeBridgeHarness(options: {
   script?: (StreamChunk[] | 'hang')[]
   config?: Partial<AcpConfig>
   storageDir: string
-  /** Mount the bridge in a disposable child fiber (for the ACP-only-HMR test). */
-  childFiber?: boolean
 } = { storageDir: '' }): Promise<BridgeHarness> {
   const adapter = new MockAdapter(options.script ?? [])
 
@@ -225,21 +223,20 @@ export async function makeBridgeHarness(options: {
   // override means "no model at all".
   const cfg: AcpConfig = { stream: agentStream, ...options.config }
   if (!(options.config && 'model' in options.config)) cfg.model = 'mock'
-  // By default apply the bridge directly on the root ctx (services ungated). For
-  // the ACP-only-HMR test, `childFiber: true` mounts it in a CHILD fiber instead
-  // so the test can dispose JUST the bridge while the rest of the harness stays
-  // up — its disposer (`harness.acpFiber.dispose()`) tears down only the
-  // bridge's listeners/effect. (Child-fiber service tracing gates the async
-  // persistence path, so the load-replay tests use the default direct mount.)
-  if (options.childFiber) {
-    harness.acpFiber = await ctx.plugin({
-      name: 'acp-test',
-      inject: ['agents', 'sessions', 'sessionPersistence'],
-      apply: (inner: Context) => { AcpPlugin.apply(inner, cfg) },
-    })
-  } else {
-    AcpPlugin.apply(ctx, cfg)
-  }
+  // Mount the bridge the way production does: as a cordis PLUGIN (via
+  // `ctx.plugin` with the real `inject`), NOT `AcpPlugin.apply(ctx, cfg)`
+  // directly on the root ctx. The plugin fiber is the faithful reproduction —
+  // the bridge's `apply` runs inside the fiber's injection scope, and its ACP
+  // handlers later run from the JSON-RPC read loop OUTSIDE that scope, exactly
+  // as under the example's cordis.yml. (Mounting directly on root made every
+  // service an ungated property and hid the "cannot get property … without
+  // inject" failure that bit a real Zed session.) `harness.acpFiber.dispose()`
+  // tears down JUST the bridge (its listeners + effect) for the HMR test.
+  harness.acpFiber = await ctx.plugin({
+    name: 'acp-test',
+    inject: ['agents', 'sessions', 'sessionPersistence'],
+    apply: (inner: Context) => { AcpPlugin.apply(inner, cfg) },
+  })
   harness.client = new ClientSideConnection(makeClient, clientStream)
 
   return harness

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/index.ts

@@ -152,12 +152,22 @@ export class AgentLoop extends Service implements AgentFactory {
    * by the time this runs the service exists.
    */
   async resume(options: ResumeAgentOptions): Promise<Agent> {
-    const persistence = this.ctx.sessionPersistence
-    // `sessionPersistence` is declaration-merged onto Context as non-optional,
-    // but the service is only present when a backend plugin is loaded — and
-    // AgentLoop deliberately does NOT inject it (that would pend non-persistent
-    // demos forever). So the runtime value can be undefined; the type cannot.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // Read the service through `ctx.get('sessionPersistence')` — a direct
+    // global-store lookup keyed by the isolate symbol — NOT
+    // `this.ctx.sessionPersistence`. AgentLoop deliberately does NOT inject
+    // `sessionPersistence` (injecting it would pend non-persistent demos
+    // forever). The `ctx.<name>` property proxy resolves a service by an
+    // ancestor-only walk of the current fiber's parent chain; from AgentLoop's
+    // own fiber (which lacks the inject) that walk never reaches the sibling
+    // backend fiber and throws "cannot get property … without inject". Worse,
+    // when the call arrives via a traceable shadow (e.g. the ACP bridge child
+    // fiber → `ctx.agents.resume()` → `this.factory.resume()`), the walk starts
+    // at the shadow's origin fiber and fails the same way. `ctx.get(name)`
+    // sidesteps the fiber walk entirely (a store lookup by the global isolate
+    // key), so resume works from any caller fiber. It is strict by default: a
+    // backend that is not ACTIVE (absent, or mid-teardown) reads as undefined
+    // and we reject below, rather than handing back an unusable handle.
+    const persistence = this.ctx.get('sessionPersistence')
     if (persistence === undefined) {
       throw new Error('cannot resume: session persistence is not configured (load a dsh-session-persistence backend)')
     }

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

@@ -46,10 +46,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
@@ -71,7 +72,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({