Merge remote-tracking branch 'origin/master' into codex/project-instruction-files

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.md # docs/event-producer-consumer.md # docs/persistence-catalog.md # docs/rfc/implemented/feature/2026-06-15-code-mode.md # docs/rfc/implemented/feature/2026-06-30-interception-seams.md # docs/rfc/proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md # docs/tool-execution-pipeline.md # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-core/tests/agent-core.spec.ts # packages/core/agent-loop/src/agent.ts # packages/core/agent/README.md # packages/core/session/src/index.ts # packages/core/tools/README.md # packages/core/tools/src/index.ts # pnpm-lock.yaml # scripts/gen-doc-graphs.ts # scripts/type-equiv.manifest.json
2026-07-13 14:37:32 +08:00
parent 4e47a7c1bf b3e1a4154b
commit adf6b8a1ab
243 changed files with 14538 additions and 4798 deletions
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -7,6 +7,7 @@ import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { bindReactLoopAgentContext, prepareReactLoopAgent } from '../src/agent.ts'
 import { MockAdapter, textResponse } from './mock-adapter.ts'

 async function harness(adapter: MockAdapter) {
@@ -48,6 +49,33 @@ function send(agent: ReactLoopAgent, text: string) {
 }

 describe('ReactLoopAgent', () => {
+  it('rejects access before context binding and a second driver for one session', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('exclusive-driver'))
+    const prepared = prepareReactLoopAgent(ctx, AgentId('first-driver'), { model: 'mock' }, session)
+
+    expect(() => prepared.agent.ctx).toThrow('context is not bound')
+    expect(() => prepareReactLoopAgent(ctx, AgentId('second-driver'), { model: 'mock' }, session))
+      .toThrow('already has a concrete agent driver')
+
+    await prepared.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('borrows caller options and binds its scoped context exactly once', async () => {
+    const ctx = await harness(new MockAdapter([textResponse('unused')]))
+    const options = { model: 'mock' }
+    const agent = ctx.agentLoop.create(AgentId('owned-bindings'), options)
+
+    expect(agent.options).toBe(options)
+    expect(agent.id).toBe('owned-bindings')
+    expect(agent.session.id).toMatch(/^owned-bindings-session-/)
+    expect(() => { bindReactLoopAgentContext(agent, new Context()) }).toThrow(/context is already bound/)
+
+    await ctx.fiber.dispose()
+  })
+
  it('send() throws after disposal', async () => {
    const adapter = new MockAdapter(['hang'])
    const ctx = await harness(adapter)
@@ -158,10 +186,8 @@ describe('ReactLoopAgent', () => {
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
    let flushes = 0
    ctx.on('session/flush', () => { flushes += 1 })
-    // A session/event listener that throws on the synthetic turn/end. Append
-    // pushes before notifying, so turn/end is in the log (turn balanced) but the
-    // throw must NOT skip the durability checkpoint — the flush decision is made
-    // from the log, not a flag set after the (throwing) append.
+    // Session contains a throwing post-commit turn/end observer. The accepted
+    // boundary still triggers the idle injection's durability checkpoint.
    let threw = false
    ctx.on('session/event', (_s, event) => {
      if (!threw && event.type === 'turn/end') { threw = true; throw new Error('boom turn/end') }
@@ -226,26 +252,45 @@ describe('ReactLoopAgent', () => {
  })

  it('disposer is idempotent (double-stop)', async () => {
-    // Create a bare ReactLoopAgent and call start() directly to get the disposer.
-    // Then call it twice — the second call hits the early-return branch.
+    // Create a bare ReactLoopAgent and start it through the package-internal
+    // test seam. Then call its disposer twice — the second call hits the
+    // early-return branch.
    const ctx = new Context()
    await ctx.plugin(SessionStore)
    const session = ctx.sessions.create(SessionId('test'))
-    const agent = new ReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
+    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
+    const { agent } = prepared

    // Start the loop to get the disposer; the agent waits for messages
    // (idle, never-resolving cancel), so it will stay idle.
-    const dispose = agent.start()
+    prepared.markPublished()
+    const dispose = prepared.startDriver()

    // First dispose
-    dispose()
+    const firstDisposal = dispose()
    expect(agent.status).toBe('disposed')
+    await firstDisposal

    // Second dispose — idempotent, no throw
-    expect(() => { dispose() }).not.toThrow()
+    await expect(dispose()).resolves.toBeUndefined()
    expect(agent.status).toBe('disposed')
  })

+  it('a pre-start disposal makes a later driver-start attempt inert', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const session = ctx.sessions.create(SessionId('pre-start-dispose'))
+    const prepared = prepareReactLoopAgent(ctx, AgentId('pre-start-dispose'), { model: 'mock' }, session)
+
+    await prepared.dispose()
+    expect(prepared.agent.status).toBe('disposed')
+    const dispose = prepared.startDriver()
+    await dispose()
+    await expect(prepared.agent.done).resolves.toBeUndefined()
+    expect(prepared.agent.session.events).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
  it('setting the same status does not emit agent/status again', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
@@ -324,7 +369,7 @@ describe('ReactLoopAgent', () => {
    // Covers the waiter's disposed arm: whenIdle() queues an internal waiter
    // while running (not the fast path), then the disposer settles it and chains
    // `done` (loop exit), not an eager resolve. A bare ReactLoopAgent + direct
-    // start() disposer keeps the emit synchronous.
+    // internal driver disposer keeps the emit synchronous.
    const ctx = new Context()
    await ctx.plugin(LlmService)
    await ctx.plugin(SessionStore)
@@ -334,17 +379,19 @@ describe('ReactLoopAgent', () => {
    const adapter = new MockAdapter(['hang'])
    ctx.llm.registerAdapter(['mock'], adapter)
    const session = ctx.sessions.create(SessionId('bare'))
-    const agent = new ReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
-    const dispose = agent.start()
+    const prepared = prepareReactLoopAgent(ctx, AgentId('bare'), { model: 'mock' }, session)
+    const { agent } = prepared
+    prepared.markPublished()
+    const dispose = prepared.startDriver()
    agent.send([{ type: 'text', text: 'go' }])
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')

    const idle = agent.whenIdle() // queues an internal waiter (running)
-    dispose() // settles the waiter synchronously; whenIdle chains done
+    const disposal = dispose() // settles the waiter synchronously; whenIdle chains done
    await idle
    expect(agent.status).toBe('disposed')
-    await agent.done
+    await disposal
  })

  it('whenIdle() subscribed while running survives a FIBER dispose (no hung promise)', async () => {
@@ -409,7 +456,7 @@ describe('ReactLoopAgent', () => {

    expect(adapter.requests).toHaveLength(1)
    expect(agent.status).toBe('idle')
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('agent/status listener threw on running'))
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('agent event "agent/status" listener threw'))
    warn.mockRestore()
  })

@@ -427,7 +474,7 @@ describe('ReactLoopAgent', () => {

    expect(adapter.requests).toHaveLength(1)
    expect(agent.status).toBe('idle')
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('agent/status listener threw on idle'))
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('agent event "agent/status" listener threw'))
    warn.mockRestore()
  })
 })
--- a/packages/core/agent-loop/tests/cancel.spec.ts
+++ b/packages/core/agent-loop/tests/cancel.spec.ts
@@ -202,7 +202,7 @@ describe('Agent.cancel()', () => {
    await ctx.plugin(AgentLoop, { agents: [] })
    ctx.llm.registerAdapter(['mock'], adapter)

-    const handle = ctx.agents.create({
+    const handle = await ctx.agents.create({
      agentId: AgentId('a-dispose-prefix'),
      sessionId: SessionId('dispose-prefix-session'),
      agentOptions: { model: 'mock' },
@@ -333,7 +333,7 @@ describe('Agent.cancel()', () => {
    await ctx.plugin(AgentLoop, { agents: [] })
    ctx.llm.registerAdapter(['mock'], adapter)

-    const handle = ctx.agents.create({
+    const handle = await ctx.agents.create({
      agentId: AgentId('a-dispose-step-start'),
      sessionId: SessionId('dispose-step-start-session'),
      agentOptions: { model: 'mock' },
--- a/packages/core/agent-loop/tests/config-session-id.spec.ts
+++ b/packages/core/agent-loop/tests/config-session-id.spec.ts
@@ -24,6 +24,24 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
 }

 describe('config-driven session id', () => {
+  it('identity-nests the deferred resume fiber under its labeled owner effect', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    const loopFiber = await ctx.plugin(AgentLoop, {
+      agents: [{ id: AgentId('main'), model: 'mock', resumeSessionId: SessionId('deferred') }],
+    })
+
+    const resumeEffect = loopFiber.getEffects().find(effect => effect.label === 'agentLoop.resume(main)')
+    expect(resumeEffect?.children.map(child => child.label)).toEqual(['ctx.plugin()'])
+    expect(loopFiber.getEffects().filter(effect => effect.label === 'ctx.plugin()')).toEqual([])
+
+    await loopFiber.dispose()
+  })
+
  it('config-driven create uses a fresh ${id}-session-<uuid> per run (restart-safe)', async () => {
    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-session-'))
    dirs.push(root)
@@ -78,7 +96,7 @@ describe('config-driven session id', () => {
    await ctx1.plugin(AgentLoop, { agents: [] })
    await ctx1.plugin(SessionPersistenceJsonl, { root })
    ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('first')]))
-    const a1 = ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sticky-1') }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sticky-1') })).agent as ReactLoopAgent
    a1.send([{ type: 'text', text: 'remember me' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
    await ctx1.fiber.dispose()
--- a/packages/core/agent-loop/tests/coverage-edges.spec.ts
+++ b/packages/core/agent-loop/tests/coverage-edges.spec.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, LlmError, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
@@ -35,31 +36,24 @@ function send(agent: ReactLoopAgent, text: string) {
  agent.send([{ type: 'text', text }])
 }

-describe('turn boundary listener throws (handled in-turn, loop survives)', () => {
-  it('a pre-push turn/start failure (non-serializable source) is rethrown to the runLoop backstop', async () => {
-    // A non-serializable message source makes the turn/start append throw BEFORE
-    // the event is pushed (Session.append validates before push), so turn/start
-    // never enters the log. runTurn sees no logged turn/start and rethrows; the
-    // runLoop backstop reports via agent/error (step 0) + the logger and the
-    // driver survives. This is the ONLY path that reaches the backstop.
-    const adapter = new MockAdapter([textResponse('turn 2')])
+describe('inbox acceptance', () => {
+  it('rejects non-serializable content or source synchronously before notification or enqueue', async () => {
+    const adapter = new MockAdapter([textResponse('turn 1')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
+    let queued = 0
+    ctx.on('agent/queued', () => { queued += 1 })

-    const errors: { turn: number; step: number; message: string }[] = []
-    ctx.on('agent/error', (_a, turn, step, error) => void errors.push({ turn, step, message: error.message }))
+    expect(() => {
+      agent.send([{ type: 'text', text: 'first', bad: 1n } as never])
+    }).toThrow(/losslessly JSON-serializable/)
+    expect(() => {
+      agent.send([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
+    }).toThrow(/losslessly JSON-serializable/)
+    expect(queued).toBe(0)
+    expect(agent.session.events).toHaveLength(0)

-    // A non-serializable source (BigInt) on the queued message.
-    agent.send([{ type: 'text', text: 'first' }], { source: { kind: 'plugin', plugin: 'p', bad: 1n } as never })
-    await waitForIdle(ctx, agent)
-
-    expect(errors).toHaveLength(1)
-    expect(errors[0]!.step).toBe(0)
-    expect(errors[0]!.message).toMatch(/non-JSON-serializable/)
-    // No turn boundary was written (the turn/start append threw before push).
-    expect(agent.session.events.some(e => e.type === 'turn/start')).toBe(false)
-
-    // loop survives: a well-formed second turn runs normally.
+    // The rejected value never woke or poisoned the loop; a valid message runs.
    send(agent, 'second')
    await waitForIdle(ctx, agent)
    expect(adapter.requests).toHaveLength(1)
@@ -129,13 +123,15 @@ describe('tool JSON parse', () => {
 })

 describe('toError normalization', () => {
-  it('normalizes non-Error throws from a turn/start session-event listener via toError', async () => {
+  it('normalizes non-Error throws from pre-commit dispatch validation via the runLoop backstop', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })

    let threwOnce = false
-    ctx.on('session/event', (_session, event) => {
+    ctx.on('internal/dispatch', (_mode, name, args) => {
+      if (name !== 'session/event') return
+      const event = args[1] as SessionEvent
      if (event.type === 'turn/start' && !threwOnce) {
        threwOnce = true
        throw 'naked string error' // non-Error throw, normalized via toError
@@ -148,11 +144,9 @@ describe('toError normalization', () => {
    send(agent, 'go')
    await waitForIdle(ctx, agent)
    expect(errors).toHaveLength(1)
-    expect(errors[0]!.message).toBe('naked string error')
-    // A non-Error throw is wrapped in a HarnessError with code UNKNOWN, so the
-    // turn-end error reason carries a routable code instead of degrading.
-    const turnEnd = agent.session.events.find(e => e.type === 'turn/end')
-    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind === 'error' && turnEnd.data.reason.code).toBe('UNKNOWN')
+    expect(errors[0]).toMatchObject({ message: 'naked string error', code: 'UNKNOWN' })
+    expect(adapter.requests).toEqual([])
+    expect(agent.session.events.some(event => event.type === 'turn/start' || event.type === 'turn/end')).toBe(false)
  })

  it('normalizes non-Error throws from agent/request waterfall via inline toError in runStep catch', async () => {
--- a/packages/core/agent-loop/tests/inbox.spec.ts
+++ b/packages/core/agent-loop/tests/inbox.spec.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { Inbox } from '@deepseek-ai/dsh-agent-loop'
+import { Inbox } from '../src/inbox.ts'

 function resolverPair() {
  let r!: () => void
--- a/packages/core/agent-loop/tests/interception.spec.ts
+++ b/packages/core/agent-loop/tests/interception.spec.ts
@@ -319,6 +319,36 @@ describe('agent/session-start', () => {
 })

 describe('agent/session-prefix', () => {
+  it('dispatches to global and matching agent-scope listeners only', async () => {
+    const adapter = new MockAdapter([textResponse('a done'), textResponse('b done')])
+    const ctx = await harness(adapter)
+    const agentA = ctx.agentLoop.create(AgentId('prefix-a'), { model: 'mock' })
+    const agentB = ctx.agentLoop.create(AgentId('prefix-b'), { model: 'mock' })
+    const seen: string[] = []
+    ctx.on('agent/session-prefix', async (agent, _prefix, _signal, next) => {
+      seen.push(`global:${agent.id}`)
+      return next()
+    })
+    agentA.ctx.on('agent/session-prefix', async (agent, _prefix, _signal, next) => {
+      seen.push(`a:${agent.id}`)
+      return next()
+    })
+    agentB.ctx.on('agent/session-prefix', async (agent, _prefix, _signal, next) => {
+      seen.push(`b:${agent.id}`)
+      return next()
+    })
+
+    send(agentA, 'run a')
+    await waitForIdle(ctx, agentA)
+    send(agentB, 'run b')
+    await waitForIdle(ctx, agentB)
+
+    expect(seen).toEqual([
+      'global:prefix-a', 'a:prefix-a',
+      'global:prefix-b', 'b:prefix-b',
+    ])
+  })
+
  it('composes once per loop instance and fronts every request; the header records it; history stays untouched', async () => {
    const adapter = new MockAdapter([
      toolCallResponse('c1', 'echo', { text: 'ping' }),
--- a/packages/core/agent-loop/tests/loop.spec.ts
+++ b/packages/core/agent-loop/tests/loop.spec.ts
@@ -168,7 +168,7 @@ describe('agent loop', () => {
  it('resolves {{cwd}} from the agent session workspace (factory create with meta.cwd)', async () => {
    const adapter = new MockAdapter([textResponse('ok')])
    const ctx = await harness(adapter, 'Working in {{cwd}}.')
-    const handle = ctx.agents.create({
+    const handle = await ctx.agents.create({
      agentId: AgentId('a-cwd'),
      sessionId: SessionId('s-cwd'),
      meta: { cwd: '/work/space' },
@@ -243,6 +243,44 @@ describe('agent loop', () => {
    expect(adapter.requests[0]!.system).toBe('You are an AI agent powered by the DeepSeek Harness SDK.\n\nYou run on mock.')
  })

+  it.each([
+    ['BigInt', { n: 1n }],
+    ['Map', new Map([['key', 'value']])],
+    ['class instance', new (class ResultMeta { x = 1 })()],
+  ])('normalizes non-JSON tool meta (%s) before the durable result commit', async (_kind, meta) => {
+    const adapter = new MockAdapter([
+      toolCallResponse('bad-meta-call', 'bad-meta', {}, 'calling'),
+      textResponse('recovered'),
+    ])
+    const ctx = await harness(adapter)
+    ctx.tools.register(defineTool({
+      name: 'bad-meta',
+      description: 'returns invalid durable metadata',
+      parameters: {},
+      execute: () => Promise.resolve({ content: [{ type: 'text' as const, text: 'apparent success' }], meta }),
+    }))
+    const agent = ctx.agentLoop.create(AgentId('bad-meta-agent'), { model: 'mock' })
+
+    send(agent, 'use the tool')
+    await waitForIdle(ctx, agent)
+
+    const result = agent.session.events.find(event => event.type === 'tool/result')
+    expect(result?.type).toBe('tool/result')
+    if (result?.type === 'tool/result') {
+      expect(result.data.callId).toBe('bad-meta-call')
+      expect(result.data.isError).toBe(true)
+      expect(result.data.meta).toBeUndefined()
+      expect(result.data.content).toEqual([{
+        type: 'text',
+        text: 'Error: tool result must be losslessly JSON-serializable',
+      }])
+    }
+    // The normalized failure was durably logged and fed back to the model; the
+    // turn continued normally instead of failing after an apparent success.
+    expect(adapter.requests).toHaveLength(2)
+    expect(JSON.stringify(adapter.requests[1]!.messages)).toContain('losslessly JSON-serializable')
+  })
+
  it('omits the system field when a system-prompt/assemble veto empties the assembly', async () => {
    // The documented escape valve: a deployment that must drop the harness
    // openers short-circuits the assemble waterfall; the request then carries
@@ -798,10 +836,10 @@ describe('agent loop', () => {
    ])
  })

-  it('stops the turn when a step/end session-event listener failure has recorded an error', async () => {
+  it('contains a step/end observer failure without changing continuation', async () => {
    const adapter = new MockAdapter([
      toolCallResponse('c1', 'echo', { text: 'x' }),
-      textResponse('should not run'),
+      textResponse('continued after tool call'),
    ])
    const ctx = await harness(adapter)
    ctx.tools.register(defineTool({
@@ -814,9 +852,8 @@ describe('agent loop', () => {
    }))
    const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
    let threw = false
-    // A throwing step/end session-event listener is the surviving boundary-listener
-    // failure path (step boundaries have no agent/* mirror): closeStep contains it
-    // and surfaces it as a turn error rather than stranding the turn open.
+    // Post-commit session observers cannot control the loop. The tool call still
+    // drives the second model request, and the turn completes normally.
    ctx.on('session/event', (_session, event) => {
      if (event.type === 'step/end' && !threw) { threw = true; throw new Error('bad step/end listener') }
    })
@@ -824,9 +861,9 @@ describe('agent loop', () => {
    send(agent, 'go')
    await waitForIdle(ctx, agent)

-    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests).toHaveLength(2)
    const turnEnd = agent.session.events.findLast(e => e.type === 'turn/end')
-    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('error')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason.kind).toBe('completed')
  })

  it('chains queued messages into consecutive turns', async () => {
--- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts
+++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts
@@ -222,7 +222,7 @@ describe('request stability across the loop', () => {
    // one's full log (the resume/fork path).
    const adapter2 = new MockAdapter([textResponse('two')])
    const ctx2 = await harness(adapter2)
-    const handle = ctx2.agents.create({
+    const handle = await ctx2.agents.create({
      agentId: AgentId('gen2'),
      sessionId: SessionId('gen2-session'),
      seed: [...agent.session.events],
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -19,6 +19,10 @@ afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive:
 async function persistentHarness(adapter: MockAdapter): Promise<{ ctx: Context; root: string }> {
  const root = await mkdtemp(join(tmpdir(), 'dsh-resume-'))
  dirs.push(root)
+  return { ctx: await mountPersistentHarness(root, adapter), root }
+}
+
+async function mountPersistentHarness(root: string, adapter: MockAdapter): Promise<Context> {
  const ctx = new Context()
  await ctx.plugin(LlmService)
  await ctx.plugin(SessionStore)
@@ -28,7 +32,22 @@ async function persistentHarness(adapter: MockAdapter): Promise<{ ctx: Context;
  await ctx.plugin(AgentLoop, { agents: [] })
  await ctx.plugin(SessionPersistenceJsonl, { root })
  ctx.llm.registerAdapter(['mock'], adapter)
-  return { ctx, root }
+  return ctx
+}
+
+async function persistSession(sessionId: SessionId): Promise<string> {
+  const { ctx, root } = await persistentHarness(new MockAdapter([textResponse('seed')]))
+  // Persistence deliberately has no artifact for a truly empty session. A
+  // balanced completed turn is the smallest resumable log and avoids running
+  // the model merely to construct this lifecycle fixture.
+  const seed: SessionEvent[] = [
+    { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } },
+    { type: 'turn/end', seq: 1, time: 2, data: { turn: 1, reason: { kind: 'completed' } } },
+  ]
+  const session = ctx.sessions.create(sessionId, { seed })
+  await ctx.sessions.flush(session)
+  await ctx.fiber.dispose()
+  return root
 }

 function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
@@ -39,11 +58,44 @@ function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise<void> {
  })
 }

+/** Fail a lifecycle regression promptly instead of waiting for Vitest's suite timeout. */
+async function promptly<T>(task: Promise<T>): Promise<T> {
+  const timeout = Promise.withResolvers<never>()
+  const timer = setTimeout(() => { timeout.reject(new Error('lifecycle task did not settle promptly')) }, 1000)
+  try {
+    return await Promise.race([task, timeout.promise])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Throw an arbitrary callback value to exercise the public unknown-error boundary. */
+function throwUnknown(value: unknown): never {
+  throw value
+}
+
 describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
+  it('normalizes a non-Error resume publication failure for rollback and rethrows it', async () => {
+    const sessionId = SessionId('unknown-resume-failure-s')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const failure = { source: 'resume' }
+    ctx.on('session/created', () => throwUnknown(failure))
+
+    await expect(ctx.agents.resume({
+      agentId: AgentId('unknown-resume-failure'),
+      resumeSessionId: sessionId,
+    })).rejects.toBe(failure)
+
+    expect(ctx.agents.get(AgentId('unknown-resume-failure'))).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
  it('createAgent uses the caller-supplied sessionId (not ${id}-session)', async () => {
    const adapter = new MockAdapter([textResponse('hi')])
    const { ctx } = await persistentHarness(adapter)
-    const { agent } = ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('custom-session'), meta: { cwd: '/w' } })
+    const { agent } = await ctx.agents.create({ agentId: AgentId('a1'), sessionId: SessionId('custom-session'), meta: { cwd: '/w' } })
    expect(agent.session.id).toBe('custom-session')
    expect(agent.session.header.cwd).toBe('/w')
    await ctx.fiber.dispose()
@@ -52,10 +104,10 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
  it('createAgent rejects a duplicate agent id BEFORE creating the session (no orphan)', async () => {
    const adapter = new MockAdapter([textResponse('hi')])
    const { ctx } = await persistentHarness(adapter)
-    ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-a') })
+    await ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-a') })
    // A second create with the SAME agent id but a fresh session id must reject
    // up front — and must NOT leave an orphaned 'sess-b' session behind.
-    expect(() => ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-b') })).toThrow(/already registered/)
+    await expect(ctx.agents.create({ agentId: AgentId('dup'), sessionId: SessionId('sess-b') })).rejects.toThrow(/already registered/)
    expect(ctx.sessions.get(SessionId('sess-b'))).toBeUndefined()
    await ctx.fiber.dispose()
  })
@@ -63,7 +115,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
  it('createAgent works without meta (no cwd)', async () => {
    const adapter = new MockAdapter([textResponse('hi')])
    const { ctx } = await persistentHarness(adapter)
-    const { agent } = ctx.agents.create({ agentId: AgentId('a-nometa'), sessionId: SessionId('nometa-session') })
+    const { agent } = await ctx.agents.create({ agentId: AgentId('a-nometa'), sessionId: SessionId('nometa-session') })
    expect(agent.session.id).toBe('nometa-session')
    expect(agent.session.header.cwd).toBeUndefined()
    await ctx.fiber.dispose()
@@ -73,7 +125,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    // Lifecycle 1: create a no-cwd session and run a turn.
    const adapter1 = new MockAdapter([textResponse('a')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('nocwd-sess') }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('nocwd-sess') })).agent as ReactLoopAgent
    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
    await ctx1.fiber.dispose()
@@ -100,7 +152,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
    const sources1: string[] = []
    ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
-    const a1 = ctx1.agents.create({ agentId: AgentId('s'), sessionId: SessionId('start-sess') }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('s'), sessionId: SessionId('start-sess') })).agent as ReactLoopAgent
    expect(sources1).toEqual(['startup'])
    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
@@ -124,6 +176,250 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    await ctx2.fiber.dispose()
  })

+  it('resume awaits setup while unpublished, then publishes a fully composed world in order', async () => {
+    const sessionId = SessionId('resume-setup-success')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const gate = Promise.withResolvers<undefined>()
+    const setupStarted = Promise.withResolvers<undefined>()
+    const order: string[] = []
+
+    ctx.on('session/created', (session) => {
+      expect(ctx.sessions.get(session.id)).toBe(session)
+      expect(ctx.agents.get(AgentId('resumed-atomic'))?.session).toBe(session)
+      order.push('session/created')
+    })
+    ctx.on('agent/created', (agent) => {
+      expect(agent.status).toBe('idle')
+      order.push('agent/created')
+    })
+    ctx.on('agent/session-start', (agent) => {
+      expect(() => { agent.cancel('now live') }).not.toThrow()
+      order.push('agent/session-start')
+    })
+
+    const resuming = ctx.agents.resume({
+      agentId: AgentId('resumed-atomic'),
+      resumeSessionId: sessionId,
+      agentOptions: { model: 'mock' },
+      setup: async (agentCtx) => {
+        expect(agentCtx.agent?.id).toBe(AgentId('resumed-atomic'))
+        expect(agentCtx.agent?.session.events).toHaveLength(2)
+        agentCtx.on('session/created', () => void order.push('setup-listener:session/created'))
+        agentCtx.on('agent/created', () => void order.push('setup-listener:agent/created'))
+        order.push('setup:start')
+        setupStarted.resolve(undefined)
+        await gate.promise
+        order.push('setup:end')
+      },
+    })
+
+    await setupStarted.promise
+    expect(ctx.agents.get(AgentId('resumed-atomic'))).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    expect(order).toEqual(['setup:start'])
+
+    gate.resolve(undefined)
+    const handle = await resuming
+    expect(order).toEqual([
+      'setup:start',
+      'setup:end',
+      'session/created',
+      'setup-listener:session/created',
+      'agent/created',
+      'setup-listener:agent/created',
+      'agent/session-start',
+    ])
+    await handle.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('successful resume disposal retires its caller-owned transaction effects', async () => {
+    const sessionId = SessionId('resume-retired-effects-s')
+    const agentId = AgentId('resume-retired-effects')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const handle = await ctx.agents.resume({
+      agentId,
+      resumeSessionId: sessionId,
+      agentOptions: { model: 'mock' },
+    })
+    const transactionLabels = [
+      `agentLoop.owner(${agentId})`,
+      `agentLoop.lifecycle(${agentId})`,
+    ]
+
+    expect(ctx.fiber.getEffects().map(effect => effect.label)).toEqual(expect.arrayContaining(transactionLabels))
+    await handle.dispose()
+    expect(ctx.fiber.getEffects().filter(effect => transactionLabels.includes(effect.label))).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
+  it('resume setup rejection publishes nothing, unwinds, and releases both identities', async () => {
+    const sessionId = SessionId('resume-setup-reject')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const published: string[] = []
+    ctx.on('session/created', () => void published.push('session/created'))
+    ctx.on('agent/created', () => void published.push('agent/created'))
+    ctx.on('agent/session-start', () => void published.push('agent/session-start'))
+
+    await expect(ctx.agents.resume({
+      agentId: AgentId('resume-reject'),
+      resumeSessionId: sessionId,
+      agentOptions: { model: 'mock' },
+      setup: async () => {
+        await Promise.resolve()
+        throw new Error('resume setup failed')
+      },
+    })).rejects.toThrow('resume setup failed')
+
+    expect(published).toEqual([])
+    expect(ctx.agents.get(AgentId('resume-reject'))).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    const retry = await ctx.agents.resume({
+      agentId: AgentId('resume-reject'),
+      resumeSessionId: sessionId,
+      agentOptions: { model: 'mock' },
+    })
+    await retry.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('owner unload aborts resume setup and cannot publish after the callback settles', async () => {
+    const sessionId = SessionId('resume-setup-owner-unload')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const gate = Promise.withResolvers<undefined>()
+    const setupStarted = Promise.withResolvers<undefined>()
+    const published: string[] = []
+    ctx.on('session/created', () => void published.push('session/created'))
+    ctx.on('agent/created', () => void published.push('agent/created'))
+
+    let resuming!: ReturnType<typeof ctx.agents.resume>
+    const owner = await ctx.plugin(Object.assign((inner: Context) => {
+      resuming = inner.agents.resume({
+        agentId: AgentId('resume-owner-race'),
+        resumeSessionId: sessionId,
+        agentOptions: { model: 'mock' },
+        setup: async () => {
+          setupStarted.resolve(undefined)
+          await gate.promise
+        },
+      })
+    }, { inject: ['agents'] }))
+    await setupStarted.promise
+
+    await owner.dispose()
+    await expect(resuming).rejects.toThrow(/owner disposed during setup/)
+    expect(published).toEqual([])
+    expect(ctx.agents.get(AgentId('resume-owner-race'))).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    gate.resolve(undefined)
+    await Promise.resolve()
+    expect(published).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
+  it('owner unload aborts a never-settling persistence load, releases identities, and blocks late publication', async () => {
+    const sessionId = SessionId('resume-load-owner-unload')
+    const agentId = AgentId('resume-load-race')
+    const root = await persistSession(sessionId)
+    const ctx = await mountPersistentHarness(root, new MockAdapter([textResponse('next')]))
+    const snapshot = await ctx.sessionPersistence.load(sessionId)
+    const lateLoad = Promise.withResolvers<typeof snapshot>()
+    const loadStarted = Promise.withResolvers<undefined>()
+    let loads = 0
+    ctx.sessionPersistence.load = (id) => {
+      expect(id).toBe(sessionId)
+      loads += 1
+      if (loads === 1) {
+        loadStarted.resolve(undefined)
+        return lateLoad.promise
+      }
+      return Promise.resolve(structuredClone(snapshot))
+    }
+
+    const published: string[] = []
+    ctx.on('session/created', () => void published.push('session/created'))
+    ctx.on('agent/created', () => void published.push('agent/created'))
+    ctx.on('agent/session-start', () => void published.push('agent/session-start'))
+
+    let resuming!: ReturnType<typeof ctx.agents.resume>
+    const owner = await ctx.plugin(Object.assign((inner: Context) => {
+      resuming = inner.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } })
+    }, { inject: ['agents'] }))
+    await loadStarted.promise
+
+    const rejection = expect(promptly(resuming)).rejects.toThrow(/owner disposed during setup/)
+    await promptly(owner.dispose())
+    expect(published).toEqual([])
+    expect(ctx.agents.get(agentId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+
+    // owner.dispose() awaited transaction settlement, so the same identities
+    // can be reused before awaiting the public rejection.
+    const retry = await promptly(ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } }))
+    await rejection
+    expect(loads).toBe(2)
+    expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
+
+    // Settlement of the abandoned backend promise cannot resume the old
+    // transaction or emit a second publication after the retry owns the ids.
+    lateLoad.resolve(structuredClone(snapshot))
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(ctx.agents.get(agentId)).toBe(retry.agent)
+    expect(ctx.sessions.get(sessionId)).toBe(retry.agent.session)
+    expect(published).toEqual(['session/created', 'agent/created', 'agent/session-start'])
+
+    await retry.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('AgentLoop unload aborts persistence load and awaits wrapper settlement', async () => {
+    const sessionId = SessionId('resume-load-factory-unload')
+    const agentId = AgentId('resume-load-factory-race')
+    const root = await persistSession(sessionId)
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    const loopFiber = await ctx.plugin(AgentLoop, { agents: [] })
+    await ctx.plugin(SessionPersistenceJsonl, { root })
+    ctx.llm.registerAdapter(['mock'], new MockAdapter([textResponse('next')]))
+
+    const snapshot = await ctx.sessionPersistence.load(sessionId)
+    const lateLoad = Promise.withResolvers<typeof snapshot>()
+    const loadStarted = Promise.withResolvers<undefined>()
+    ctx.sessionPersistence.load = (id) => {
+      expect(id).toBe(sessionId)
+      loadStarted.resolve(undefined)
+      return lateLoad.promise
+    }
+    const published: string[] = []
+    ctx.on('session/created', () => void published.push('session/created'))
+    ctx.on('agent/created', () => void published.push('agent/created'))
+
+    const resuming = ctx.agents.resume({ agentId, resumeSessionId: sessionId, agentOptions: { model: 'mock' } })
+    await loadStarted.promise
+    const rejection = expect(promptly(resuming)).rejects.toThrow(/agent loop is not active/)
+    await promptly(loopFiber.dispose())
+    await rejection
+
+    expect(published).toEqual([])
+    expect(ctx.agents.get(agentId)).toBeUndefined()
+    expect(ctx.sessions.get(sessionId)).toBeUndefined()
+    lateLoad.resolve(structuredClone(snapshot))
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(published).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
  it('resume of a forked session preserves the parentSession lineage and seed boundary in the header', async () => {
    // Lifecycle 1: persist a FORKED session (carries parentSession + seedLength
    // in its header) by creating it with a complete-turn seed — the write path
@@ -170,7 +466,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    // disk, since a crash before the next turn would otherwise lose it.
    const adapter1 = new MockAdapter([textResponse('answer')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
    a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
@@ -195,7 +491,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    // drop it on reload (the bug this guards).
    const adapter1 = new MockAdapter([textResponse('answer')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('m'), sessionId: SessionId('inject-sess'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
    a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
@@ -223,7 +519,7 @@ describe('the session-persistence RFC: AgentLoop factory create/resume', () => {
    // Lifecycle 1: run one full turn, persisting it.
    const adapter1 = new MockAdapter([textResponse('first answer')])
    const { ctx: ctx1, root } = await persistentHarness(adapter1)
-    const a1 = ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } }).agent as ReactLoopAgent
+    const a1 = (await ctx1.agents.create({ agentId: AgentId('main'), sessionId: SessionId('sess-resume'), meta: { cwd: '/w' } })).agent as ReactLoopAgent
    a1.send([{ type: 'text', text: 'first question' }], { source: { kind: 'user' } })
    await waitForIdle(ctx1, a1)
    const events1 = [...a1.session.events]
--- a/packages/core/agent-loop/tests/review-fixes.spec.ts
+++ b/packages/core/agent-loop/tests/review-fixes.spec.ts
@@ -1,18 +1,16 @@
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import LlmService, { CallId, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
+import LlmService, { CallId, ContentBlock, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
 import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
 import AgentRegistry, { AgentId, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { prepareReactLoopAgent } from '../src/agent.ts'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'

-/**
- * Regression tests for the findings of the first architecture review
- * (Codex + sub-agent, post phase-1). Each describe block names the finding.
- */
+/** Regression tests for agent-loop boundary, identity, and lifecycle contracts. */

 async function harness(adapter: MockAdapter) {
  const ctx = new Context()
@@ -436,6 +434,94 @@ describe('MEDIUM: misc registry and config fixes', () => {
    const steeringSources = agent.session.events.flatMap(e => e.type === 'steering/message' ? [e.data.source] : [])
    expect(steeringSources).toEqual([{ kind: 'plugin', plugin: 'goal' }])
  })
+
+  it('send() owns content and source before notification and delivery', async () => {
+    const adapter = new MockAdapter([textResponse('done')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('owned-send'), { model: 'mock' })
+    const content = [{ type: 'text' as const, text: 'accepted-send' }]
+    const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
+    let notifiedContent: ContentBlock[] | undefined
+    let notifiedSource: MessageSource | undefined
+    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+      if (subject !== agent || info.steering) return
+      // Retain the exact notification references: cloning here would test the
+      // listener's copy rather than the event/inbox ownership boundary.
+      notifiedContent = acceptedContent
+      notifiedSource = info.source
+    })
+
+    agent.send(content, { source })
+    content[0]!.text = 'caller-mutated-send'
+    source.plugin = 'caller-mutated-source'
+    await waitForIdle(ctx, agent)
+
+    expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-send' }])
+    expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
+    expect(Object.isFrozen(notifiedContent)).toBe(true)
+    expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
+    expect(Object.isFrozen(notifiedSource)).toBe(true)
+    const recorded = agent.session.events.flatMap(event => event.type === 'user/message' ? [event.data] : [])
+    expect(recorded).toContainEqual({
+      content: [{ type: 'text', text: 'accepted-send' }],
+      source: { kind: 'plugin', plugin: 'accepted-source' },
+    })
+    const request = JSON.stringify(adapter.requests[0]!.messages)
+    expect(request).toContain('accepted-send')
+    expect(request).not.toContain('caller-mutated-send')
+  })
+
+  it('running steer() owns content and source before notification and delivery', async () => {
+    const adapter = new MockAdapter([toolCallResponse('c1', 'gate', {}), textResponse('done')])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('owned-steer'), { model: 'mock' })
+    const entered = Promise.withResolvers<undefined>()
+    const release = Promise.withResolvers<undefined>()
+    ctx.tools.register(defineTool({
+      name: 'gate',
+      description: '',
+      parameters: {},
+      async execute() {
+        entered.resolve(undefined)
+        await release.promise
+        return [{ type: 'text', text: 'tool done' }]
+      },
+    }))
+    let notifiedContent: ContentBlock[] | undefined
+    let notifiedSource: MessageSource | undefined
+    ctx.on('agent/queued', (subject, acceptedContent, info) => {
+      if (subject !== agent || !info.steering) return
+      notifiedContent = acceptedContent
+      notifiedSource = info.source
+    })
+
+    agent.send([{ type: 'text', text: 'start' }])
+    await entered.promise
+    expect(agent.status).toBe('running')
+    const content = [{ type: 'text' as const, text: 'accepted-steer' }]
+    const source = { kind: 'plugin' as const, plugin: 'accepted-source' }
+    agent.steer(content, { source })
+    content[0]!.text = 'caller-mutated-steer'
+    source.plugin = 'caller-mutated-source'
+    const idle = waitForIdle(ctx, agent)
+    release.resolve(undefined)
+    await idle
+
+    expect(notifiedContent).toEqual([{ type: 'text', text: 'accepted-steer' }])
+    expect(notifiedSource).toEqual({ kind: 'plugin', plugin: 'accepted-source' })
+    expect(Object.isFrozen(notifiedContent)).toBe(true)
+    expect(Object.isFrozen(notifiedContent?.[0])).toBe(true)
+    expect(Object.isFrozen(notifiedSource)).toBe(true)
+    const recorded = agent.session.events.flatMap(event => event.type === 'steering/message' ? [event.data] : [])
+    expect(recorded).toContainEqual({
+      turn: 1,
+      content: [{ type: 'text', text: 'accepted-steer' }],
+      source: { kind: 'plugin', plugin: 'accepted-source' },
+    })
+    const request = JSON.stringify(adapter.requests[1]!.messages)
+    expect(request).toContain('accepted-steer')
+    expect(request).not.toContain('caller-mutated-steer')
+  })
 })

 describe('MEDIUM: turn numbering continues across seeded (forked) sessions', () => {
@@ -458,8 +544,10 @@ describe('MEDIUM: turn numbering continues across seeded (forked) sessions', ()
    ctx2.llm.registerAdapter(['mock'], second)

    const seeded = ctx2.sessions.create(SessionId('forked'), { seed: [...agent.session.events] })
-    const forked = new ReactLoopAgent(ctx2, AgentId('forked-agent'), { model: 'mock' }, seeded)
-    ctx2.effect(() => forked.start())
+    const prepared = prepareReactLoopAgent(ctx2, AgentId('forked-agent'), { model: 'mock' }, seeded)
+    const forked = prepared.agent
+    prepared.markPublished()
+    ctx2.effect(() => prepared.startDriver())

    const turns: number[] = []
    ctx2.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
@@ -558,7 +646,7 @@ describe('HIGH: a finish-error stream chunk ends the turn as error, not complete
  })
 })

-describe('P1-6: a step/start session-event listener sees the event already in the log', () => {
+describe('step boundary publication order', () => {
  it('the step/start event is in session.events when its session/event listener fires', async () => {
    const adapter = new MockAdapter([textResponse('done')])
    const ctx = await harness(adapter)
@@ -589,7 +677,7 @@ describe('P1-6: a step/start session-event listener sees the event already in th
  })
 })

-describe('P1-5: a started turn (and any open step) is always closed on a boundary throw', () => {
+describe('turn and step boundary recovery', () => {
  // Harness with the invariants plugin loaded as an oracle: it throws on
  // append if the log goes unbalanced (turn/end while a step is open,
  // turn/start while a turn is open, etc.), so a regression surfaces as an
@@ -602,7 +690,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)
    return ctx
  }
@@ -620,19 +708,13 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    }
  }

-  it('a throwing step/start session-event listener closes the open step then the turn (step/end before turn/end)', async () => {
-    const adapter = new MockAdapter([textResponse('never reached')])
+  it('a throwing step/start observer cannot change a successful turn', async () => {
+    const adapter = new MockAdapter([textResponse('request completed')])
    const ctx = await balancedHarness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a-stepstart'), { model: 'mock' })

-    // Step boundaries have no agent/* mirror; a throwing step/start session-event
-    // listener is the surviving step-boundary-listener failure. The loop marks
-    // the step open BEFORE appending step/start (Session.append pushes before
-    // notifying, so a post-push listener throw still leaves stepOpen=true), so
-    // the outer catch's closeStep() appends the balancing step/end — the turn
-    // stays enclosed. The invariants oracle (balancedHarness) rejects any
-    // imbalance, so a green run proves turn/start → step/start → step/end →
-    // turn/end nesting holds.
+    // Session owns post-commit containment. The loop sees a successful append,
+    // runs the request, and balances the ordinary step and turn boundaries.
    let threw = false
    ctx.on('session/event', (_s, event) => {
      if (event.type === 'step/start' && !threw) { threw = true; throw new Error('boom step-start') }
@@ -645,8 +727,8 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar

    const e = [...agent.session.events]
    const c = boundaryCounts(agent)
-    expect(c).toMatchObject({ turnStart: 1, turnEnd: 1, stepStart: 1, stepEnd: 1, errors: 1 })
-    expect(errors.map(x => x.message)).toEqual(['boom step-start'])
+    expect(c).toMatchObject({ turnStart: 1, turnEnd: 1, stepStart: 1, stepEnd: 1, errors: 0 })
+    expect(errors).toEqual([])
    // step/end precedes turn/end (the invariants oracle would reject
    // turn/end-while-step-open, but assert the order explicitly too).
    const stepEndIdx = e.findIndex(x => x.type === 'step/end')
@@ -655,6 +737,101 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    expect(stepEndIdx).toBeLessThan(turnEndIdx)
  })

+  it('a pre-commit step/start validation failure does not invent a step boundary', async () => {
+    const adapter = new MockAdapter([textResponse('never reached')])
+    const ctx = await balancedHarness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-stepstart-veto'), { model: 'mock' })
+    let rejected = false
+    ctx.on('internal/dispatch', (_mode, name, args) => {
+      if (name !== 'session/event') return
+      const event = args[1] as SessionEvent
+      if (event.type === 'step/start' && !rejected) {
+        rejected = true
+        throw new Error('reject step-start before commit')
+      }
+    })
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => { errors.push(error) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toEqual([])
+    expect(boundaryCounts(agent)).toMatchObject({
+      turnStart: 1,
+      turnEnd: 1,
+      stepStart: 0,
+      stepEnd: 0,
+      errors: 1,
+    })
+    expect(errors.map(error => error.message)).toEqual(['reject step-start before commit'])
+  })
+
+  it('a one-shot turn/end validation failure preserves the earlier turn error on retry', async () => {
+    const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider failed' } }]
+    const adapter = new MockAdapter([errorStream])
+    const ctx = await balancedHarness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-turnend-veto'), { model: 'mock' })
+    let rejected = false
+    ctx.on('internal/dispatch', (_mode, name, args) => {
+      if (name !== 'session/event') return
+      const event = args[1] as SessionEvent
+      if (event.type === 'turn/end' && !rejected) {
+        rejected = true
+        throw new Error('reject first turn-end')
+      }
+    })
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => { errors.push(error) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(errors.map(error => error.message)).toEqual(['provider failed'])
+    expect(boundaryCounts(agent)).toMatchObject({
+      turnStart: 1,
+      turnEnd: 1,
+      stepStart: 1,
+      stepEnd: 1,
+      errors: 1,
+    })
+    const turnEnd = agent.session.events.findLast(event => event.type === 'turn/end')
+    expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toMatchObject({
+      kind: 'error',
+      message: 'provider failed',
+    })
+  })
+
+  it('a one-shot step/end validation failure keeps the step open until retry succeeds', async () => {
+    const adapter = new MockAdapter([textResponse('completed before close validation')])
+    const ctx = await balancedHarness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('a-stepend-veto'), { model: 'mock' })
+    let rejected = false
+    ctx.on('internal/dispatch', (_mode, name, args) => {
+      if (name !== 'session/event') return
+      const event = args[1] as SessionEvent
+      if (event.type === 'step/end' && !rejected) {
+        rejected = true
+        throw new Error('reject first step-end')
+      }
+    })
+    const errors: Error[] = []
+    ctx.on('agent/error', (_agent, _turn, _step, error) => { errors.push(error) })
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(errors.map(error => error.message)).toEqual(['reject first step-end'])
+    expect(boundaryCounts(agent)).toMatchObject({
+      turnStart: 1,
+      turnEnd: 1,
+      stepStart: 1,
+      stepEnd: 1,
+      errors: 1,
+    })
+  })
+
  it('a throwing agent/error listener during a step-error path still balances the turn, loop survives', async () => {
    // First turn: model stream ends with a finish-error → step error path →
    // failTurn emits agent/error, whose listener throws. The turn must still
@@ -717,13 +894,9 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
  })

  it('preserves reason disposed when a pre-step listener disposes then throws (outer-catch disposed branch)', async () => {
-    // Reach the OUTER catch while disposed: an `agent/pre-step` listener requests
-    // disposal AND throws. The throw escapes the pre-step `await` (line ~419) to
-    // the loop's outer catch — BEFORE the post-pre-step disposal check at ~422
-    // gets to run — so the catch sees `isDisposed() && !errorReported` and must
-    // PRESERVE reason=disposed rather than overwrite it with the listener's throw
-    // (disposal is not a failure). This is the surviving path to that sub-branch
-    // now that there is no turn-boundary emit to throw from.
+    // A pre-step listener requests disposal and then throws before the ordinary
+    // post-listener disposal check. The outer catch sees disposal already won
+    // and must preserve reason=disposed rather than rewrite it as a plugin error.
    const adapter = new MockAdapter([textResponse('never reached')])
    const ctx = await balancedHarness(adapter)
    let agent!: ReactLoopAgent
@@ -759,16 +932,8 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    expect(errorEmits).toHaveLength(0)
  })

-  it('a throwing session/event listener on the turn/start append still balances the turn', async () => {
-    // Session.append pushes the event BEFORE notifying session/event listeners,
-    // so a listener throwing on turn/start leaves turn/start IN THE LOG. The
-    // 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 (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')])
+  it('a throwing turn/start observer cannot starve the loop or later turns', async () => {
+    const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a-preturn'), { model: 'mock' })

@@ -782,12 +947,9 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    send(agent, 'go')
    await waitForIdle(ctx, agent)

-    // The error was surfaced exactly once via agent/error.
-    expect(errors.map(e => e.message)).toEqual(['boom turn/start append'])
-    // The turn is BALANCED: turn/start is in the log (it was pushed before the
-    // listener threw), so a turn/end was owed and appended — no open turn. The
-    // last turn-boundary event being turn/end is exactly the loop's isTurnOpen
-    // check (no open turn remains).
+    expect(errors).toEqual([])
+    // Session contains the observer failure per listener, so the committed turn
+    // remains visible to later observers and executes normally.
    const types = [...agent.session.events].map(e => e.type)
    expect(types.filter(t => t === 'turn/start')).toHaveLength(1)
    expect(types.filter(t => t === 'turn/end')).toHaveLength(1)
@@ -798,15 +960,10 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    // loop survives: a second turn runs normally.
    send(agent, 'second')
    await waitForIdle(ctx, agent)
-    expect(adapter.requests).toHaveLength(1)
+    expect(adapter.requests).toHaveLength(2)
  })

-  it('a throwing step/end session-event listener during a successful step ends the turn as error, not completed', async () => {
-    // closeStep() must surface a throwing step/end listener via failTurn so the
-    // turn ends with reason error, not a silent "completed" with the throw
-    // swallowed. Regression test for the closeStep() catch that previously
-    // swallowed the throw in the normal (no-tool, no-steering) path. (Step
-    // boundaries have no agent/* mirror; the session-event listener is the path.)
+  it('a throwing step/end observer cannot rewrite the turn outcome', async () => {
    const adapter = new MockAdapter([textResponse('all good'), textResponse('turn 2 ok')])
    const ctx = await balancedHarness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a-stepend-throw'), { model: 'mock' })
@@ -822,11 +979,10 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    await waitForIdle(ctx, agent)

    const c = boundaryCounts(agent)
-    // step opened and closed; exactly one error turn-end; turn balanced.
-    expect(c).toMatchObject({ turnStart: 1, turnEnd: 1, stepStart: 1, stepEnd: 1, errors: 1 })
-    expect(errors.map(e => e.message)).toEqual(['boom step-end'])
+    expect(c).toMatchObject({ turnStart: 1, turnEnd: 1, stepStart: 1, stepEnd: 1, errors: 0 })
+    expect(errors).toEqual([])
    expect(c.lastTurnEnd?.type === 'turn/end' && c.lastTurnEnd.data.reason)
-      .toEqual({ kind: 'error', step: 1, message: 'boom step-end' })
+      .toEqual({ kind: 'completed' })

    // step/end precedes turn/end (ordering contract)
    const e = [...agent.session.events]
@@ -844,14 +1000,11 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    expect(c2.stepStart).toBe(c2.stepEnd)
  })

-  it('a throwing session/event listener on step/end during finalization still appends turn/end', async () => {
+  it('a throwing step/end observer cannot interrupt error finalization', async () => {
    // A finish-error stream opens a step then fails it, driving finalization
-    // through closeStep() with the step open. closeStep appends step/end; a
-    // session/event listener throwing on THAT must not abort the catch before
-    // closeTurn — step/end is already logged (balance holds) and the throw is
-    // contained + surfaced via failTurn, so turn/end is still appended. (The
-    // failed step itself also routes through failTurn; the step/end-listener
-    // throw is the second, contained, failure.)
+    // through closeStep() with the step open. Session contains the observer
+    // failure after committing step/end, so closeTurn still records the model
+    // failure and balances the turn.
    const errorStream: StreamChunk[] = [{ type: 'finish', reason: { kind: 'error', message: 'provider 500' } }]
    const adapter = new MockAdapter([errorStream, textResponse('turn 2 ok')])
    const ctx = await harness(adapter)
@@ -872,7 +1025,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
    expect(e.some(x => x.type === 'step/end')).toBe(true)
    expect(e.some(x => x.type === 'turn/end')).toBe(true)
    expect(e.at(-1)?.type).toBe('turn/end')
-    expect(errors.length).toBeGreaterThanOrEqual(1) // surfaced via agent/error
+    expect(errors.map(error => error.message)).toEqual(['provider 500'])

    // loop survives.
    send(agent, 'again')
@@ -881,12 +1034,8 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
  })

  it('a throwing session/event listener on turn/end is contained (turn still balanced, loop survives)', async () => {
-    // closeTurn appends turn/end; Session.append pushes it BEFORE notifying
-    // session/event listeners, so a throwing listener leaves turn/end in the log
-    // (the turn is balanced) but must not escape — from the normal-path closeTurn
-    // it would otherwise propagate; the append is contained so the loop continues.
-    // Turn boundaries are durable session events only (no agent/* mirror), so this
-    // session/event append-notify throw is the sole turn-end-listener failure path.
+    // Session contains the observer failure after committing turn/end, so the
+    // boundary stays authoritative and the loop continues normally.
    const adapter = new MockAdapter([textResponse('turn 1'), textResponse('turn 2')])
    const ctx = await harness(adapter)
    const agent = ctx.agentLoop.create(AgentId('a-turnendappend'), { model: 'mock' })
@@ -912,7 +1061,7 @@ describe('P1-5: a started turn (and any open step) is always closed on a boundar
  })
 })

-describe('P1-7: tool/result is logged under the originating call.id, not result.callId', () => {
+describe('tool result call identity', () => {
  it('the loop records tool/result under the model call.id even when a post-execute listener replaces content', async () => {
    // Model emits a tool-call with id "c1", then a final text turn.
    const adapter = new MockAdapter([
@@ -992,7 +1141,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream



-describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
+describe('disposal and cancellation during pre-step assembly', () => {
  it('disposal during system-prompt assembly drops the about-to-start step as disposed', { timeout: 30000 }, async () => {
    // Block `system-prompt/assemble` on a promise. Start disposal (which
    // calls stop() synchronously, setting status=disposed), then release the
@@ -1011,7 +1160,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

    // Blocking listener on the parent context (survives fiber disposal).
@@ -1068,7 +1217,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

    const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
@@ -1124,7 +1273,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('agent/pre-step', async () => {
@@ -1176,7 +1325,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('agent/pre-step', async () => {
@@ -1225,7 +1374,7 @@ describe('disposal/cancel honored during pre-step assembly (P1-1)', () => {
    await ctx.plugin(ToolRegistry)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(AgentLoop, { agents: [] })
-    await ctx.plugin(Invariants, { freeze: false })
+    await ctx.plugin(Invariants)
    ctx.llm.registerAdapter(['mock'], adapter)

    ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
--- a/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
+++ b/packages/core/agent-loop/tests/scope-lifecycle.spec.ts
--- a/packages/core/agent-loop/tests/tool-order.spec.ts
+++ b/packages/core/agent-loop/tests/tool-order.spec.ts
@@ -107,7 +107,7 @@ describe('loop-level canonical tool order', () => {
    agent.send([{ type: 'text', text: 'go' }])
    await waitForIdle(ctx, agent)
    expect(adapter.requests).toHaveLength(0)
-    expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; registered tools: alpha'])
+    expect(errors.map(e => e.message)).toEqual(['toolOrder lists unregistered tool "ghost"; known tools: alpha'])
    expect(foldRequestHeader(agent.session.events)).toBeUndefined()
    const end = agent.session.events.find(e => e.type === 'turn/end')
    expect(end?.type === 'turn/end' && end.data.reason).toMatchObject({ kind: 'error', step: 1 })
--- a/packages/core/agent-loop/tests/turn-stop.spec.ts
+++ b/packages/core/agent-loop/tests/turn-stop.spec.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore, { type TurnEndReason } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import AgentRegistry, { AgentId, type ContinuationStop } from '@deepseek-ai/dsh-agent'
+import AgentLoop, { type ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import * as Invariants from '@deepseek-ai/dsh-invariants'
+import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+async function harness(adapter: MockAdapter): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(Invariants)
+  await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return ctx
+}
+
+function send(agent: ReactLoopAgent, text = 'go'): Promise<void> {
+  agent.send([{ type: 'text', text }])
+  return agent.whenIdle()
+}
+
+function registerEcho(ctx: Context): void {
+  ctx.tools.register(defineTool({
+    name: 'echo',
+    description: 'echo',
+    parameters: { text: { type: 'string' } },
+    async execute(args) {
+      return [{ type: 'text', text: String(args.text) }]
+    },
+  }))
+}
+
+describe('agent/turn-stop', () => {
+  it('runs after steering folding and discards terminal steering instead of creating another step or turn', async () => {
+    const adapter = new MockAdapter([
+      textResponse('the ordinary decision is stop'),
+      textResponse('must not be requested'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('terminal-steering'), { model: 'mock' })
+    agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
+
+    let steered = false
+    ctx.on('agent/turn-continuation', async (subject, _turn, _default, next) => {
+      const downstream = await next()
+      if (subject === agent && !steered) {
+        steered = true
+        subject.steer([{ type: 'text', text: 'late continuation steering' }])
+      }
+      return downstream
+    }, { prepend: true })
+
+    await send(agent)
+
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'step/start')).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'steering/message')).toHaveLength(0)
+  })
+
+  it('discards steering that arrives from session/flush after the terminal checkpoint', async () => {
+    const adapter = new MockAdapter([
+      textResponse('terminal answer'),
+      textResponse('must not become a late-steering turn'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('terminal-flush-steering'), { model: 'mock' })
+    agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
+
+    let injected = false
+    ctx.on('session/flush', (session) => {
+      if (session !== agent.session || injected) return
+      injected = true
+      agent.steer([{ type: 'text', text: 'steering from flush' }])
+    })
+
+    await send(agent)
+
+    expect(injected).toBe(true)
+    expect(agent.status).toBe('idle')
+    expect(adapter.requests).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'step/start')).toHaveLength(1)
+    expect(agent.session.events.filter(event => event.type === 'steering/message')).toHaveLength(0)
+  })
+
+  it('preserves an ordinary queued send that arrives during terminal flush', async () => {
+    const adapter = new MockAdapter([
+      textResponse('first terminal answer'),
+      textResponse('queued follow-up answer'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('terminal-flush-send'), { model: 'mock' })
+    agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
+
+    let queued = false
+    ctx.on('session/flush', (session) => {
+      if (session !== agent.session || queued) return
+      queued = true
+      agent.send([{ type: 'text', text: 'ordinary queued follow-up' }])
+    })
+
+    await send(agent)
+
+    expect(agent.status).toBe('idle')
+    expect(adapter.requests).toHaveLength(2)
+    expect(agent.session.events.filter(event => event.type === 'turn/start')).toHaveLength(2)
+    expect(agent.session.events.filter(event => event.type === 'step/start')).toHaveLength(2)
+  })
+
+  it('filters a scoped terminal listener to its own agent', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('a1', 'echo', { text: 'a' }),
+      toolCallResponse('b1', 'echo', { text: 'b' }),
+      textResponse('b continues normally'),
+    ])
+    const ctx = await harness(adapter)
+    registerEcho(ctx)
+    const stopped = ctx.agentLoop.create(AgentId('stopped'), { model: 'mock' })
+    const ordinary = ctx.agentLoop.create(AgentId('ordinary'), { model: 'mock' })
+    stopped.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
+
+    await send(stopped)
+    expect(adapter.requests).toHaveLength(1)
+    await send(ordinary)
+
+    expect(adapter.requests).toHaveLength(3)
+    expect(stopped.session.events.filter(event => event.type === 'step/start')).toHaveLength(1)
+    expect(ordinary.session.events.filter(event => event.type === 'step/start')).toHaveLength(2)
+  })
+
+  it('unregisters with its scoped owner disposer', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('first', 'echo', { text: 'first' }),
+      toolCallResponse('second', 'echo', { text: 'second' }),
+      textResponse('continued after listener disposal'),
+    ])
+    const ctx = await harness(adapter)
+    registerEcho(ctx)
+    const agent = ctx.agentLoop.create(AgentId('owned-listener'), { model: 'mock' })
+    const disposeStop = agent.ctx.on('agent/turn-stop', (): ContinuationStop => ({ action: 'stop' }))
+
+    await send(agent, 'first turn')
+    expect(adapter.requests).toHaveLength(1)
+
+    disposeStop()
+    await send(agent, 'second turn')
+    expect(adapter.requests).toHaveLength(3)
+  })
+
+  it('fails a throwing terminal policy closed while the driver survives', async () => {
+    const adapter = new MockAdapter([
+      textResponse('throwing policy'),
+      textResponse('healthy later turn'),
+    ])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create(AgentId('bad-policy'), { model: 'mock' })
+    const reasons: TurnEndReason[] = []
+    const errors: string[] = []
+    ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'turn/end') reasons.push(event.data.reason)
+    })
+    agent.ctx.on('agent/error', (_subject, _turn, _step, error) => { errors.push(error.message) })
+
+    const disposeThrowing = agent.ctx.on('agent/turn-stop', () => {
+      throw new Error('terminal policy exploded')
+    })
+    await send(agent, 'first')
+    disposeThrowing()
+
+    await send(agent, 'healthy')
+
+    expect(reasons.map(reason => reason.kind)).toEqual(['error', 'completed'])
+    expect(errors).toContain('terminal policy exploded')
+    expect(adapter.requests).toHaveLength(2)
+  })
+})