Merge remote-tracking branch 'origin/master' into codex/pr48-repo-hardening-rfcs

# Conflicts:
#	docs/adr/README.md
#	docs/rfc/009-session-persistence-and-resumability.md
#	docs/rfc/README.md
#	docs/rfc/implemented/2026-06-11-doc-sync-enforcement.md
#	docs/rfc/proposed/2026-06-14-acp-agent-client-protocol.md
#	examples/acp-agent/tests/acp.e2e.ts
#	packages/acp/README.md
#	packages/acp/src/index.ts
#	packages/acp/tests/stream-update.spec.ts
#	packages/agent-loop/src/loop.ts
#	packages/tools/src/index.ts

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 = (): boolean => {
     if (!stepOpen) return false
     stepOpen = false
@@ -226,8 +226,11 @@ async function runTurn(ctx: Context, agent: LoopAgent, handle: LoopHandle, turn:
     // a throwing listener from producing a silent "completed" turn when the step
     // itself succeeded, AND keeps finalization going when closeStep runs from
     // the outer catch.
-    if (failure !== undefined) failTurn(toError(failure))
-    return failure !== undefined
+    if (failure !== undefined) {
+      failTurn(toError(failure))
+      return true
+    }
+    return false
   }
 
   // Record a step/turn failure exactly once: append the single `error` event
@@ -242,7 +245,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
@@ -347,7 +350,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
@@ -394,7 +397,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
@@ -429,7 +432,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)
@@ -498,32 +501,28 @@ async function runStep(
   const stepError = finishError(assembler.finish)
   if (stepError) throw stepError
 
+  if (assembler.finish.kind === 'max-tokens') {
+    if (assembler.usage) {
+      session.append('usage', { turn, step, usage: assembler.usage })
+    }
+    return { hadToolCalls: false, finish: assembler.finish }
+  }
+
   // The step-result waterfall runs BEFORE the session append so the log (the
   // source of truth for derived history and replay) records the message that
   // tool dispatch actually uses.
   let message: Message = assembler.message()
   message = await ctx.waterfall('agent/step-result', agent, turn, step, message, () => Promise.resolve(message))
-  const finish = assembler.finish
-  const messageForLog: Message = finish.kind === 'max-tokens'
-    ? { ...message, content: message.content.filter(block => block.type !== 'tool-call') }
-    : message
 
-  if (finish.kind !== 'max-tokens' || messageForLog.content.length > 0) {
-    session.append('assistant/message', { turn, step, content: messageForLog.content })
-  }
+  session.append('assistant/message', { turn, step, content: message.content })
   if (assembler.usage) {
     session.append('usage', { turn, step, usage: assembler.usage })
   }
 
   // --- Tool execution (sequential; parallel execution is a TODO) ---
   // ToolRegistry.execute converts tool failures (including aborts) into
-  // isError results, so abort is re-checked around every call here. A
-  // max-tokens step is cut off: any tool-call block in it may be partial, so it
-  // is neither dispatched nor recorded in the derived-history assistant message
-  // above. Raw assistant/chunk events still preserve the exact stream.
-  const toolCalls = finish.kind === 'max-tokens'
-    ? []
-    : message.content.filter(block => block.type === 'tool-call')
+  // isError results, so abort is re-checked around every call here.
+  const toolCalls = message.content.filter(block => block.type === 'tool-call')
   for (const call of toolCalls) {
     /* v8 ignore next -- signal.reason always set by agent.abort() which provides a default */
     if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
@@ -564,7 +563,7 @@ async function runStep(
     /* v8 ignore stop */
   }
 
-  return { hadToolCalls: toolCalls.length > 0, finish }
+  return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish }
 }
 
 /** The last turn number in a (possibly seeded) session log, or 0. */
@@ -580,7 +579,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)