refactor: unify agent and session identity

2026-07-14 01:59:21 +08:00
parent 7a33ee94be
commit 709cc7200e
105 changed files with 899 additions and 948 deletions
--- a/packages/ui/acp/src/index.ts
+++ b/packages/ui/acp/src/index.ts
@@ -72,7 +72,6 @@ import {
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import { assertNever, CallId } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { SANDBOX_MODES, effectiveSandboxMode, setSandboxMode } from '@deepseek-ai/dsh-bash'
 import { APPROVAL_POLICIES, effectiveApprovalPolicy, setApprovalPolicy } from '@deepseek-ai/dsh-user-approval'
@@ -686,7 +685,6 @@ export function apply(ctx: Context, config: AcpConfig): void {
        validateMcpServers(params)
        const sessionId = SessionId(randomUUID())
        const handle = await agents.create({
-          agentId: AgentId(sessionId),
          sessionId,
          meta: { cwd: params.cwd },
          agentOptions: agentOptions(config),
@@ -757,7 +755,6 @@ export function apply(ctx: Context, config: AcpConfig): void {
            }
          }
          const handle = await agents.resume({
-            agentId: AgentId(sessionId),
            resumeSessionId: sessionId,
            agentOptions: agentOptions(config),
          })
--- a/packages/ui/acp/tests/approval.spec.ts
+++ b/packages/ui/acp/tests/approval.spec.ts
@@ -4,9 +4,11 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { CallId } from '@deepseek-ai/dsh-llm'
-import { AgentId, type Agent } from '@deepseek-ai/dsh-agent'
+import { type Agent } from '@deepseek-ai/dsh-agent'
+
 import ApprovalService, { type ApprovalRequest } from '@deepseek-ai/dsh-user-approval'
 import { makeBridgeHarness, type BridgeHarness } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * The bridge's `approval/request` answerer: an ask for an agent the bridge
@@ -31,7 +33,7 @@ describe('acp bridge — approval answerer', () => {
  ): Promise<{ agent: Agent; request: ApprovalRequest }> {
    await h.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await h.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = h.ctx.agents.get(AgentId(sessionId))
+    const agent = h.ctx.agents.get(SessionId(sessionId))
    if (agent === undefined) throw new Error('newSession created no agent')
    // In production an ask always fires mid-turn (tool execution); open one so
    // request()'s turn-enclosure precondition holds for the direct drive below.
--- a/packages/ui/acp/tests/bridge.spec.ts
+++ b/packages/ui/acp/tests/bridge.spec.ts
@@ -3,8 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /**
 * End-to-end bridge specs over an in-memory transport: a real
@@ -98,7 +98,7 @@ describe('acp bridge', () => {
        required: [],
      },
    })
-    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
+    const toolResult = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'tool/result')
    const toolResultBlock = toolResult?.type === 'tool/result' ? toolResult.data.content[0] : undefined
    const toolResultText = toolResultBlock?.type === 'text' ? toolResultBlock.text : undefined
    expect(toolResultText).toBe('{"answers":[{"id":"language","selected":["Python"]}]}')
@@ -127,7 +127,7 @@ describe('acp bridge', () => {
        required: ['custom'],
      },
    })
-    const toolResult = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'tool/result')
+    const toolResult = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'tool/result')
    expect(JSON.stringify(toolResult)).toContain('apollo')
  })

@@ -136,7 +136,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    const result = await harness.ctx.userInteraction.ask({
      agent,
@@ -167,7 +167,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { choice: 'TypeScript', custom: 'Use Zig' } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({
      agent,
@@ -184,7 +184,7 @@ describe('acp bridge', () => {
    harness.onElicitation = () => ({ action: 'accept', content: { choice: ['Tests', 'Docs'] } })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({
      agent,
@@ -201,7 +201,7 @@ describe('acp bridge', () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    await expect(harness.ctx.userInteraction.ask({ questions: [{ id: 'x', question: 'No agent?' }] }))
      .rejects.toMatchObject({ name: 'UserInteractionError', code: 'NO_AGENT' })
@@ -225,7 +225,7 @@ describe('acp bridge', () => {
    harness = await makeBridgeHarness({ storageDir, withAskUser: true })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    const alreadyAborted = new AbortController()
    alreadyAborted.abort()
@@ -265,8 +265,8 @@ describe('acp bridge', () => {
    expect(b.sessionId).toBeTruthy()
    expect(a.sessionId).not.toBe(b.sessionId)
    // Both agents are live and independently registered.
-    expect(harness.ctx.agents.get(AgentId(a.sessionId))).toBeDefined()
-    expect(harness.ctx.agents.get(AgentId(b.sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(a.sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(b.sessionId))).toBeDefined()
  })

  it('rejects a non-absolute cwd but accepts any absolute cwd (per-session workspace)', async () => {
@@ -281,7 +281,7 @@ describe('acp bridge', () => {
    const res = await harness.client.newSession({ cwd: '/tmp', mcpServers: [] })
    expect(res.sessionId).toBeTruthy()
    // The session header records that cwd, so its bash tools run there.
-    expect(harness.ctx.agents.get(AgentId(res.sessionId))!.session.header.cwd).toBe('/tmp')
+    expect(harness.ctx.agents.get(SessionId(res.sessionId))!.session.header.cwd).toBe('/tmp')
  })

  it('rejects non-empty additionalDirectories', async () => {
@@ -321,7 +321,7 @@ describe('acp bridge', () => {
      ],
    })
    expect(result.stopReason).toBe('end_turn')
-    const user = harness.ctx.agents.get(AgentId(sessionId))!.session.events.find(event => event.type === 'user/message')
+    const user = harness.ctx.agents.get(SessionId(sessionId))!.session.events.find(event => event.type === 'user/message')
    expect(JSON.stringify(user)).toContain('resource_link')
  })

--- a/packages/ui/acp/tests/dispose.spec.ts
+++ b/packages/ui/acp/tests/dispose.spec.ts
@@ -4,7 +4,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse } from './harness.ts'

 describe('acp bridge — disposal & HMR safety', () => {
@@ -17,7 +16,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!

    // Start a prompt that hangs in the model stream.
    const promptDone = harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
@@ -62,10 +61,10 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeDefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeDefined()

    await harness.acpFiber.dispose() // tear down ONLY the bridge
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
    await harness.dispose()
  })

@@ -92,7 +91,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    // Start a prompt that hangs in the model stream. The prompt RPC will never
    // return (its transport is severed), so do not await it.
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
@@ -115,7 +114,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    // and its session removed from the store, not merely idled (the old
    // behavior). The services live on the root ctx, so they survive this.
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId(sessionId))).toBeUndefined()
    await harness.dispose()
  })
@@ -128,7 +127,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')
@@ -145,7 +144,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const session = harness.ctx.agents.get(AgentId(sessionId))!.session
+    const session = harness.ctx.agents.get(SessionId(sessionId))!.session

    await harness.ctx.fiber.dispose()
    const before = harness.updates.length
@@ -169,12 +168,12 @@ describe('acp bridge — disposal & HMR safety', () => {
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    await harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] })
-    const liveEvents = harness.ctx.agents.get(AgentId(sessionId))!.session.events.length
+    const liveEvents = harness.ctx.agents.get(SessionId(sessionId))!.session.events.length
    expect(liveEvents).toBeGreaterThan(0)

    // Tear down JUST the bridge (the AgentHandle dispose runs to quiescence).
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()

    // Re-load the session from disk: every live event (incl. the closing
    // turn/end) was flushed before the session was detached.
@@ -201,7 +200,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const { sessionId } = await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    void harness.client.prompt({ sessionId, prompt: [{ type: 'text', text: 'go' }] }).catch(() => {})
    await new Promise(r => setTimeout(r, 30))
    expect(agent.status).toBe('running')
@@ -211,7 +210,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    // Dispose JUST the bridge: a fiber unload that must STILL honor the ordered
    // teardown (the composite effect runs its disposer chain as a unit).
    await harness.acpFiber.dispose()
-    expect(harness.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId(sessionId))).toBeUndefined()

    // The loop's own `turn/end {disposed}` is on disk (re-load: the world, not
    // self-report) — NOT a crash-recovery `interrupted` substitute.
@@ -230,21 +229,21 @@ describe('acp bridge — disposal & HMR safety', () => {
    // queryable, with its session still in the store.
    const harness = await makeBridgeHarness({ storageDir, script: [] })
    const handleA = await harness.ctx.agents.create({
-      agentId: AgentId('sib-a'), sessionId: SessionId('sib-a'), agentOptions: { model: 'mock' },
+      sessionId: SessionId('sib-a'), agentOptions: { model: 'mock' },
    })
    const handleB = await harness.ctx.agents.create({
-      agentId: AgentId('sib-b'), sessionId: SessionId('sib-b'), agentOptions: { model: 'mock' },
+      sessionId: SessionId('sib-b'), agentOptions: { model: 'mock' },
    })
-    expect(harness.ctx.agents.get(AgentId('sib-a'))).toBe(handleA.agent)
-    expect(harness.ctx.agents.get(AgentId('sib-b'))).toBe(handleB.agent)
+    expect(harness.ctx.agents.get(SessionId('sib-a'))).toBe(handleA.agent)
+    expect(harness.ctx.agents.get(SessionId('sib-b'))).toBe(handleB.agent)

    await handleA.dispose()
    // A is gone — unregistered AND its session removed from the store.
-    expect(harness.ctx.agents.get(AgentId('sib-a'))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId('sib-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('sib-a'))).toBeUndefined()
    expect(handleA.agent.status).toBe('disposed')
    // B is wholly unaffected.
-    expect(harness.ctx.agents.get(AgentId('sib-b'))).toBe(handleB.agent)
+    expect(harness.ctx.agents.get(SessionId('sib-b'))).toBe(handleB.agent)
    expect(harness.ctx.sessions.get(SessionId('sib-b'))).toBeDefined()
    expect(handleB.agent.status).not.toBe('disposed')
    await harness.dispose()
@@ -262,7 +261,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    const harness = await makeBridgeHarness({ storageDir, script: [textResponse('ok')] })
    harness.ctx.on('agent/disposed', () => { throw new Error('boom disposed listener') })
    const handle = await harness.ctx.agents.create({
-      agentId: AgentId('guard-a'), sessionId: SessionId('guard-a'), agentOptions: { model: 'mock' },
+      sessionId: SessionId('guard-a'), agentOptions: { model: 'mock' },
    })
    handle.agent.send([{ type: 'text', text: 'go' }])
    await handle.agent.whenIdle()
@@ -270,7 +269,7 @@ describe('acp bridge — disposal & HMR safety', () => {

    // Dispose: the throwing listener must NOT break the chain before detach.
    await handle.dispose()
-    expect(harness.ctx.agents.get(AgentId('guard-a'))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId('guard-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('guard-a'))).toBeUndefined() // detach still ran
    await harness.dispose()
  })
@@ -283,7 +282,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    // observe the same quiescence boundary.
    const harness = await makeBridgeHarness({ storageDir, script: ['hang'] })
    const handle = await harness.ctx.agents.create({
-      agentId: AgentId('conc-a'), sessionId: SessionId('conc-a'), agentOptions: { model: 'mock' },
+      sessionId: SessionId('conc-a'), agentOptions: { model: 'mock' },
    })
    // Drive a turn that hangs in the model stream, so the loop is mid-turn when
    // disposed — its exit runs a final session/flush we can gate to hold the
@@ -313,7 +312,7 @@ describe('acp bridge — disposal & HMR safety', () => {
    // Release the flush; both resolve together and the session is gone.
    releaseFlush()
    await Promise.all([first, second])
-    expect(harness.ctx.agents.get(AgentId('conc-a'))).toBeUndefined()
+    expect(harness.ctx.agents.get(SessionId('conc-a'))).toBeUndefined()
    expect(harness.ctx.sessions.get(SessionId('conc-a'))).toBeUndefined()
    await harness.dispose()
  })
--- a/packages/ui/acp/tests/edges.spec.ts
+++ b/packages/ui/acp/tests/edges.spec.ts
@@ -3,7 +3,6 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { makeBridgeHarness, textResponse, type BridgeHarness } from './harness.ts'

@@ -27,7 +26,7 @@ describe('acp bridge — demux & config edges', () => {
    await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })
    const before = harness.updates.length

-    const { agent: foreign } = await harness.ctx.agents.create({ agentId: AgentId('foreign'), sessionId: SessionId('foreign-session'), agentOptions: { model: 'mock' } })
+    const { agent: foreign } = await harness.ctx.agents.create({ sessionId: SessionId('foreign-session'), agentOptions: { model: 'mock' } })
    foreign.send([{ type: 'text', text: 'hi' }])
    await foreign.whenIdle()
    await new Promise(r => setTimeout(r, 10))
--- a/packages/ui/acp/tests/load.spec.ts
+++ b/packages/ui/acp/tests/load.spec.ts
@@ -4,7 +4,6 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'

 /** Concatenate the text of all agent_message_chunk updates. */
@@ -194,7 +193,7 @@ describe('acp bridge — session/load replay', () => {
    release()                            // resume() finishes AFTER teardown
    expect(await loadResult).toBe('rejected')
    // No live agent was installed for the closed connection.
-    expect(loader.ctx.agents.get(AgentId(sessionId))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId(sessionId))).toBeUndefined()
  })

  it('rejects load when the requested cwd does not match the persisted session cwd', async () => {
@@ -215,11 +214,11 @@ describe('acp bridge — session/load replay', () => {
    await loader.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    await expect(loader.client.loadSession({ sessionId: 'elsewhere', cwd: process.cwd(), mcpServers: [] }))
      .rejects.toThrow(/cwd mismatch/)
-    expect(loader.ctx.agents.get(AgentId('elsewhere'))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId('elsewhere'))).toBeUndefined()

    const res = await loader.client.loadSession({ sessionId: 'elsewhere', cwd: `${otherCwd}/.`, mcpServers: [] })
    expect(res).toBeDefined()
-    expect(loader.ctx.agents.get(AgentId('elsewhere'))!.session.header.cwd).toBe(otherCwd)
+    expect(loader.ctx.agents.get(SessionId('elsewhere'))!.session.header.cwd).toBe(otherCwd)
  })

  it('rejects load for a non-absolute cwd (still required to be absolute)', async () => {
@@ -254,7 +253,7 @@ describe('acp bridge — session/load replay', () => {
    // Rejected BEFORE resume (metadata-only check) — no agent was registered, so
    // the id is not wedged: a later attempt hits the same clean rejection, not a
    // duplicate-registration error.
-    expect(loader.ctx.agents.get(AgentId('legacy'))).toBeUndefined()
+    expect(loader.ctx.agents.get(SessionId('legacy'))).toBeUndefined()
    await expect(loader.client.loadSession({ sessionId: 'legacy', cwd: process.cwd(), mcpServers: [] }))
      .rejects.toThrow(/no absolute persisted cwd/)
  })
--- a/packages/ui/acp/tests/multi-session.spec.ts
+++ b/packages/ui/acp/tests/multi-session.spec.ts
@@ -3,8 +3,8 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { makeBridgeHarness, textResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /** Text of the agent_message_chunk updates scoped to one session id. */
 function messageTextFor(updates: { sessionId?: string; update: CapturedUpdate }[], sessionId: string): string {
@@ -102,8 +102,8 @@ describe('acp bridge — RFC 011 multi-session isolation', () => {
    await harness.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
    const a = (await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })).sessionId
    const b = (await harness.client.newSession({ cwd: process.cwd(), mcpServers: [] })).sessionId
-    const agentA = harness.ctx.agents.get(AgentId(a))!
-    const agentB = harness.ctx.agents.get(AgentId(b))!
+    const agentA = harness.ctx.agents.get(SessionId(a))!
+    const agentB = harness.ctx.agents.get(SessionId(b))!

    // Wait deterministically for BOTH agents to enter `running` (not a fixed
    // sleep — agent startup latency is unbounded on a loaded worker).
--- a/packages/ui/acp/tests/turns.spec.ts
+++ b/packages/ui/acp/tests/turns.spec.ts
@@ -3,7 +3,6 @@ import { mkdtemp, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import {
  errorResponse,
@@ -13,6 +12,7 @@ import {
  toolCallResponse,
  type BridgeHarness,
 } from './harness.ts'
+import { SessionId } from '@deepseek-ai/dsh-session'

 /** Boilerplate: initialize + create one session, returning its id. */
 async function newSession(h: BridgeHarness, clientCapabilities: Record<string, unknown> = {}): Promise<string> {
@@ -279,7 +279,7 @@ describe('acp bridge — turn outcomes', () => {
    // OWN turn with the real model answer.
    harness = await makeBridgeHarness({ storageDir, script: [textResponse('real answer')] })
    const sessionId = await newSession(harness)
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    // On the queued prompt, synchronously inject a one-shot context turn (idle
    // inject writes turn/start{injection} → context/message → turn/end). Fire
    // once so it lands between install and the prompt turn.
@@ -335,7 +335,7 @@ describe('acp bridge — turn outcomes', () => {
    await harness.client.cancel({ sessionId })
    const res = await promptDone
    expect(res.stopReason).toBe('cancelled')
-    const agent = harness.ctx.agents.get(AgentId(sessionId))!
+    const agent = harness.ctx.agents.get(SessionId(sessionId))!
    await agent.whenIdle()
    // At most ONE turn ran (the cancelled one) — the cancel cleared the queue, so
    // no second turn was batched or leaked. (A best-effort abort that left queued
--- a/packages/ui/jsonrpc/src/server.ts
+++ b/packages/ui/jsonrpc/src/server.ts
@@ -16,7 +16,6 @@ import type { Context } from 'cordis'
 import { resolve } from 'node:path'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { AgentHandle } from '@deepseek-ai/dsh-agent'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId, type TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
@@ -255,7 +254,6 @@ export class HarnessSdkServer {

  private async createSession(sessionId: string): Promise<SessionRecord> {
    const handle = await this.ctx.agents.create({
-      agentId: AgentId(sessionId),
      sessionId: SessionId(sessionId),
      meta: { cwd: this.cwd },
      agentOptions: { model: this.model },
--- a/packages/ui/jsonrpc/tests/server.spec.ts
+++ b/packages/ui/jsonrpc/tests/server.spec.ts
@@ -5,7 +5,8 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { AgentId, type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
+import { type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
+
 import { SessionId } from '@deepseek-ai/dsh-session'
 import * as agentCore from '@deepseek-ai/dsh-agent-core'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
@@ -135,7 +136,6 @@ describe('HarnessSdkServer', () => {
      expect(llmServer.requests).toHaveLength(2)

      const orphanHandle = await ctx.agents.create({
-        agentId: AgentId('orphan-agent'),
        sessionId: SessionId('orphan-session'),
        meta: { cwd: storageDir },
        agentOptions: { model: 'dsagent-model' },
@@ -170,8 +170,8 @@ describe('HarnessSdkServer', () => {
    } as unknown as Agent
    const mainHandle = { agent: mainAgent, dispose: vi.fn(() => Promise.resolve()) }
    const otherHandle = { agent: otherAgent, dispose: vi.fn(() => Promise.resolve()) }
-    const create = vi.fn(async (options: { agentId: AgentId }) =>
-      String(options.agentId) === 'main' ? mainHandle : otherHandle)
+    const create = vi.fn(async (options: { sessionId: SessionId }) =>
+      String(options.sessionId) === 'main' ? mainHandle : otherHandle)
    const ctx = {
      on: vi.fn(() => () => undefined),
      agents: { create, get: () => undefined },
@@ -263,20 +263,18 @@ describe('HarnessSdkServer', () => {
      const server = new HarnessSdkServer(ctx, transport)

      const parentHandle = await ctx.agents.create({
-        agentId: AgentId('parent-agent'),
        sessionId: SessionId('main'),
        meta: { cwd: storageDir },
        agentOptions: { model: 'deepseek' },
      })
      const handle = await ctx.agents.create({
-        agentId: AgentId('child-agent'),
        sessionId: SessionId('child-session'),
        meta: { cwd: storageDir, parentSession: SessionId('main') },
        agentOptions: { model: 'deepseek' },
      })
      await settleSubagent(ctx, parentHandle.agent, {
        provider: 'spawn',
-        id: AgentId('child-agent'),
+        id: SessionId('child-session'),
        stopReason: 'completed',
        lastAssistantMessage: [{ type: 'text', text: 'child done' }],
      })
@@ -285,7 +283,7 @@ describe('HarnessSdkServer', () => {
        method: 'subagent.finished',
        params: {
          provider: 'spawn',
-          agentId: 'child-agent',
+          agentId: 'child-session',
          parentSessionId: 'main',
          childSessionId: 'child-session',
          status: 'ok',
@@ -311,19 +309,16 @@ describe('HarnessSdkServer', () => {
    let failedHandle: AgentHandle | undefined
    try {
      parentHandle = await ctx.agents.create({
-        agentId: AgentId('fallback-parent-agent'),
        sessionId: SessionId('fallback-parent'),
        meta: { cwd: storageDir },
        agentOptions: { model: 'deepseek' },
      })
      handle = await ctx.agents.create({
-        agentId: AgentId('fallback-child-agent'),
        sessionId: SessionId('fallback-child-session'),
        meta: { cwd: storageDir, parentSession: SessionId('fallback-parent') },
        agentOptions: { model: 'deepseek' },
      })
      failedHandle = await ctx.agents.create({
-        agentId: AgentId('failed-child-agent'),
        sessionId: SessionId('failed-child-session'),
        meta: { cwd: storageDir },
        agentOptions: { model: 'deepseek' },
@@ -333,18 +328,18 @@ describe('HarnessSdkServer', () => {

      await settleSubagent(ctx, parentHandle.agent, {
        provider: 'fork',
-        id: AgentId('fallback-child-agent'),
+        id: SessionId('fallback-child-session'),
        stopReason: 'max-tokens',
        lastAssistantMessage: [],
      })
      await settleSubagent(ctx, parentHandle.agent, {
        provider: 'fork',
-        id: AgentId('failed-child-agent'),
+        id: SessionId('failed-child-session'),
        stopReason: 'error',
      })
      await settleSubagent(ctx, parentHandle.agent, {
        provider: 'fork',
-        id: AgentId('missing-child-agent'),
+        id: SessionId('missing-child-agent'),
        stopReason: 'error',
      })

@@ -352,7 +347,7 @@ describe('HarnessSdkServer', () => {
        method: 'subagent.finished',
        params: {
          provider: 'fork',
-          agentId: 'fallback-child-agent',
+          agentId: 'fallback-child-session',
          parentSessionId: 'fallback-parent',
          childSessionId: 'fallback-child-session',
          status: 'error',
@@ -364,7 +359,7 @@ describe('HarnessSdkServer', () => {
        method: 'subagent.finished',
        params: {
          provider: 'fork',
-          agentId: 'failed-child-agent',
+          agentId: 'failed-child-session',
          childSessionId: 'failed-child-session',
          status: 'error',
          stopReason: 'error',
--- a/packages/ui/stdio-agent/README.md
+++ b/packages/ui/stdio-agent/README.md
@@ -11,11 +11,11 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating one agent under the `main` config label from this app's `model`, with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
-| `stdio-chat` (in-package module) | the readline UI, bound to the `main` agent |
+| `stdio-chat` (in-package module) | the readline UI, holding the app-owned agent object directly and rendering it as `main` |

 `@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:repl` leaves load it and pass `--expose-internals`.

@@ -25,14 +25,14 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte

 | Key | Default | Routed to |
 |---|---|---|
-| `model` | (required) | the pre-created `main` agent's model |
+| `model` | (required) | the pre-created agent's model |
 | `persona` | — | the deployment persona template (may reference `{{model}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |

-Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header.
+Fresh stdio sessions use the process launch directory as `session.header.cwd` and mint one combined `main-session-<uuid>` agent/session id, so durable restarts cannot collide. The UI's `main` text is a display label, not a second routing id. Resumed sessions register under the exact `resumeSessionId` and keep the cwd stored in the persisted session header.

 ## The bin

--- a/packages/ui/stdio-agent/src/index.ts
+++ b/packages/ui/stdio-agent/src/index.ts
@@ -3,11 +3,11 @@
 * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
 * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
 * module), JSONL session
- * persistence, and a pre-created `main` agent the UI drives.
+ * persistence, and one pre-created agent the UI drives under its `main` label.
 *
 * The cluster is BAKED IN, not left to the leaf: a stdio app always logs to the
- * console (stdout is just the terminal) and always pre-creates the `main` agent
- * the readline UI sends to. The leaf supplies the swappable backends (the LLM
+ * console (stdout is just the terminal) and always pre-creates one agent the
+ * readline UI labels `main`. The leaf supplies the swappable backends (the LLM
 * adapter, the bash executor), optional product tools, the optional `hmr`
 * dev-reload plugin, and this app's {@link Config} (model, prompt, persistence
 * root, welcome banner).
@@ -41,7 +41,6 @@
 import type { Context } from 'cordis'
 import ConsoleExporter from '@cordisjs/plugin-logger-console'
 import z from 'schemastery'
-import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import * as agentCore from '@deepseek-ai/dsh-agent-core'
@@ -54,7 +53,7 @@ export const name = 'stdio-agent'

 /**
 * App config: the swappable per-demo values, each routed to where the app wires
- * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
+ * it. `model`/`resumeSessionId` configure the pre-created agent (through
 * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
@@ -63,7 +62,7 @@ export const name = 'stdio-agent'
 * `welcome` is the UI banner.
 */
 export interface Config {
-  /** Model name for the `main` agent (must have a registered adapter). */
+  /** Model name for the pre-created agent (must have a registered adapter). */
  model: string
  /** Deployment persona (the system-prompt plugin's `persona` config). */
  persona?: string
@@ -78,7 +77,7 @@ export interface Config {
  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
  skills?: agentCore.SkillConfig
  /**
-   * If set, the `main` agent RESUMES this persisted session id instead of
+   * If set, the pre-created agent RESUMES this persisted session id instead of
   * starting fresh. Sourced from an env var in the leaf `cordis.yml`
   * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`).
   */
@@ -103,9 +102,9 @@ export const Config: z<Config> = z.object({

 /**
 * Compose the spine with the stdio front door. The console logger comes first
- * (infra), then the agent-core bundle pre-creating the `main` agent from this
- * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
- * backend, then the readline UI bound to `main`. The `hmr` dev-reload plugin is
+ * (infra), then the agent-core bundle pre-creating one agent from this app's
+ * `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
+ * backend, then the readline UI rendering that object as `main`. The `hmr` dev-reload plugin is
 * a leaf concern (see the module doc), so it is not mounted here.
 */
 export function apply(ctx: Context, config: Config): void {
@@ -115,7 +114,7 @@ export function apply(ctx: Context, config: Config): void {
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
    ...config.tools !== undefined ? { tools: config.tools } : {},
    agents: [{
-      id: AgentId('main'),
+      id: 'main',
      model: config.model,
      cwd: process.cwd(),
      ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
@@ -125,5 +124,5 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
  ctx.plugin(UserInteractionService)
  ctx.plugin(toolAskUser)
-  ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' })
+  ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.' })
 }
--- a/packages/ui/stdio-agent/src/stdio-chat.ts
+++ b/packages/ui/stdio-agent/src/stdio-chat.ts
@@ -19,7 +19,7 @@ import { createInterface } from 'node:readline'
 import type { Readable, Writable } from 'node:stream'
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
 import {
  UserInteractionError,
  type AskUserQuestionAnswer,
@@ -36,15 +36,10 @@ export const inject = ['agents', 'userInteraction']
 export interface Config {
  /** Banner printed once on start, before the first `> ` prompt. */
  welcome?: string
-  // TODO(fixed-stdio-agent): this app-internal plugin is mounted only for the
-  // precreated `main` agent; remove configurability and its config-only test.
-  /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
-  agent?: string
 }

 export const Config: z<Config> = z.object({
  welcome: z.string().default('ready.'),
-  agent: z.string().default('main'),
 })

 /**
@@ -98,23 +93,16 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
  // Loader validation, so it must be self-contained rather than trusting the
  // cast — `config.welcome as string` would otherwise be `undefined` on `{}`.
  const welcome = config.welcome ?? 'ready.'
-  const agentId = AgentId(config.agent ?? 'main')
  const { input, output, exit } = runtime

-  // Render label lookup: the `turn/start` session event carries only the turn
-  // number, so to print the short agent id (`[main turn 1]`) we map the
-  // session's id to its agent's id. The session id is not reliably the agent id
-  // (a session can be created with an explicit/client-supplied id), so build the
-  // map from `agent/created` rather than parsing the id string. Seed from the
-  // registry's current agents first: an agent registered before this plugin
-  // installed (e.g. the pre-created `main` agent, or any agent surviving an HMR
-  // reload of just this fiber) already fired its `agent/created`, so the live
-  // listener alone would miss it and its turns would fall back to the raw
-  // session id.
-  const labelBySession = new Map<string, string>()
-  for (const agent of ctx.agents.list()) labelBySession.set(agent.session.header.id, agent.id)
-  ctx.on('agent/created', (agent) => { labelBySession.set(agent.session.header.id, agent.id) })
-  ctx.on('agent/disposed', (agent) => { labelBySession.delete(agent.session.header.id) })
+  // This app owns exactly one pre-created agent. Hold the live object directly:
+  // its per-run id is intentionally fresh, while `main` remains only the
+  // terminal's fixed display label.
+  let target: Agent | undefined = ctx.agents.list()[0]
+  ctx.on('agent/created', (agent) => { target ??= agent })
+  ctx.on('agent/disposed', (agent) => {
+    if (target === agent) target = undefined
+  })

  // Transcript rendering off the durable `session/event` feed — the assistant
  // token stream, turn/step boundaries, tool activity, and todos all come from
@@ -136,7 +124,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
        output.write(chunk.text)
      }
    } else if (event.type === 'turn/start') {
-      const label = labelBySession.get(session.header.id) ?? session.header.id
+      const label = target?.session === session ? 'main' : session.id
      output.write(`\n[${label} turn ${event.data.turn}] `)
    } else if (event.type === 'turn/end') {
      if (inReasoning) output.write('\x1B[0m')
@@ -187,7 +175,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
      // Work submitted: wait until a turn has run and the agent is idle.
      if (submittedWork) {
        if (!sawRunning) return
-        const agent = ctx.agents.get(agentId)
+        const agent = target
        if (agent && agent.status !== 'idle') return // a turn is still running
      }
      // Let any final output flush, then exit. The handle is tracked so the
@@ -201,7 +189,7 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
    }

    const disposeStatusListener = ctx.on('agent/status', (subject, status) => {
-      if (subject.id !== agentId) return
+      if (subject !== target) return
      if (status === 'running') sawRunning = true
      if (status === 'idle') maybeExit()
    })
@@ -354,9 +342,9 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
      }
      const text = line.trim()
      if (!text) return
-      const agent = ctx.agents.get(agentId)
+      const agent = target
      if (!agent) {
-        ctx.logger.error('ui-stdio: agent "%s" is not running', agentId)
+        ctx.logger.error('ui-stdio: main agent is not running')
        return
      }
      submittedWork = true
--- a/packages/ui/stdio-agent/tests/readline.spec.ts
+++ b/packages/ui/stdio-agent/tests/readline.spec.ts
@@ -16,7 +16,7 @@ function fakeContext(): Context {
  return {
    on: vi.fn(() => vi.fn()),
    effect: vi.fn((callback: () => () => void) => callback()),
-    // The UI seeds its label map from the registry at install; this suite only
+    // The UI seeds its target object from the registry at install; this suite only
    // exercises readline terminal-mode selection, so an empty roster suffices.
    agents: { list: vi.fn(() => []) },
    userInteraction: { registerProvider: vi.fn(() => vi.fn()) },
--- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
@@ -4,7 +4,8 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+
 import type { Message } from '@deepseek-ai/dsh-llm'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'
@@ -82,9 +83,12 @@ describe('dsh-stdio-agent app', () => {
    expect(ctx.get('sessionPersistence')).toBeDefined()
    expect(ctx.get('userInteraction')).toBeDefined()
    expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined()
-    // The pre-created `main` agent the UI drives.
-    const agent = ctx.get('agents')?.get(AgentId('main'))
+    // The sole pre-created agent the UI drives. `main` is its stable config
+    // label; each fresh process mints a durable combined agent/session id.
+    const agent = ctx.get('agents')?.list()[0]
    expect(agent).toBeDefined()
+    expect(agent?.id).toBe(agent?.session.id)
+    expect(agent?.id).toMatch(/^main-session-/)
    expect(agent?.session.header.cwd).toBe(process.cwd())
    await ctx.fiber.dispose()
  })
@@ -99,7 +103,7 @@ describe('dsh-stdio-agent app', () => {
    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
    await new Promise(resolve => setTimeout(resolve, 80))
    expect(ctx.get('sessionPersistence')).toBeDefined()
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    expect(ctx.get('agents')?.list()).toHaveLength(1)
    await ctx.fiber.dispose()
  })

@@ -116,7 +120,7 @@ describe('dsh-stdio-agent app', () => {

  it('forwards resumeSessionId onto the pre-created agent when set', async () => {
    // A resume id defers agent creation until persistence loads; with no backing
-    // session the resume is contained + logged, so no `main` agent registers —
+    // session the resume is contained + logged, so no agent registers —
    // the branch that maps resumeSessionId through is what this covers.
    const ctx = await mount({
      model: 'mock',
@@ -125,7 +129,7 @@ describe('dsh-stdio-agent app', () => {
      resumeSessionId: 'no-such-session',
      skills: await isolatedSkillsConfig(),
    })
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    expect(ctx.get('agents')?.list()).toEqual([])
    await ctx.fiber.dispose()
  })

--- a/packages/ui/stdio-agent/tests/stdio-chat.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-chat.spec.ts
@@ -57,17 +57,16 @@ function makeAgent(id: string, status: AgentStatus = 'idle'): Agent & {
    status,
    sent,
    steered,
-    // A minimal session stub: the UI reads only `session.header.id` (to map the
-    // session back to its agent id for the turn-boundary label).
-    session: { header: { id: `${id}-session` } },
+    // A minimal session stub with the agent's shared durable identity.
+    session: { id, header: { id } },
    send: (content: ContentBlock[]) => void sent.push(content),
    steer: (content: ContentBlock[]) => void steered.push(content),
  } as never
 }

 /** A session stub whose `header.id` matches an agent's, for `session/event` emits. */
-function makeSession(agentId: string): Session {
-  return { header: { id: `${agentId}-session` } } as Session
+function makeSession(id: string): Session {
+  return { id, header: { id } } as Session
 }

 /** An `assistant/chunk` session event carrying one raw stream chunk. */
@@ -75,7 +74,7 @@ function chunkEvent(chunk: StreamChunk): SessionEvent {
  return { type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 0, chunk } }
 }

-const CONFIG: Config = { welcome: 'hi there', agent: 'main' }
+const CONFIG: Config = { welcome: 'hi there' }

 async function setup(config: Config = CONFIG, runtimeOver: Partial<StdioRuntime> = {}) {
  const ctx = new Context()
@@ -99,12 +98,11 @@ describe('createStdioChat rendering', () => {
    expect(out.text()).toBe('hi there\n> ')
  })

-  it('falls back to default welcome/agent when called with empty config', async () => {
+  it('falls back to the default welcome when called with empty config', async () => {
    // createStdioChat is exported and may be driven directly (bypassing the
-    // Loader's schemastery validation), so it must default welcome/agent itself.
+    // Loader's schemastery validation), so it must default the welcome itself.
    const { out } = await setup({})
    expect(out.text()).toBe('ready.\n> ')
-    // And it drives the default agent id 'main'.
  })

  it('detects readline terminal mode from both stream TTY flags', async () => {
@@ -156,9 +154,9 @@ describe('createStdioChat rendering', () => {
  it('renders turn/start and turn/end markers from the session feed', async () => {
    const { ctx, out } = await setup()
    const agent = makeAgent('main')
-    // agent/created populates the session-id → agent-id label map.
+    // agent/created supplies the app-owned target object.
    ctx.emit('agent/created', agent)
-    const session = makeSession('main')
+    const session = agent.session
    ctx.emit('session/event', session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 3, trigger: { kind: 'message' } },
    } as SessionEvent)
@@ -169,21 +167,20 @@ describe('createStdioChat rendering', () => {
    expect(out.text()).toContain('\n> ')
  })

-  it('falls back to the session id as the label when no agent is mapped', async () => {
+  it('uses the session id as the label for a non-target session', async () => {
    const { ctx, out } = await setup()
-    // No agent/created emitted, so the label map is empty — the header id shows.
+    // No target exists, so the event's durable identity is the label.
    ctx.emit('session/event', makeSession('orphan'), {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
    } as SessionEvent)
-    expect(out.text()).toContain('[orphan-session turn 1] ')
+    expect(out.text()).toContain('[orphan turn 1] ')
  })

-  it('seeds labels for agents already registered before the UI installs', async () => {
+  it('uses an agent already registered before the UI installs as its target', async () => {
    // The pre-created `main` agent (and any agent surviving an HMR reload of just
    // this fiber) fired its `agent/created` before the UI's listener existed, so
    // the live listener alone would miss it. Seeding from `ctx.agents.list()` at
-    // install time is what keeps its turn header showing `[main turn N]` instead
-    // of the raw session id.
+    // install time preserves the terminal's fixed `[main turn N]` label.
    const ctx = new Context()
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(UserInteractionService)
@@ -193,7 +190,7 @@ describe('createStdioChat rendering', () => {
    await ctx.plugin(Object.assign((inner: Context) => {
      createStdioChat(inner, CONFIG, runtime)
    }, { inject: ['agents', 'userInteraction'] }))
-    ctx.emit('session/event', makeSession('main'), {
+    ctx.emit('session/event', agent.session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } },
    } as SessionEvent)
    expect(out.text()).toContain('[main turn 5] ')
@@ -209,17 +206,28 @@ describe('createStdioChat rendering', () => {
    expect(out.text()).toContain('\x1B[2mmid\x1B[0m')
  })

-  it('drops the label mapping on agent/disposed', async () => {
+  it('drops the target object on agent/disposed', async () => {
    const { ctx, out } = await setup()
    const agent = makeAgent('main')
    ctx.emit('agent/created', agent)
    ctx.emit('agent/disposed', agent)
-    // After disposal the map no longer resolves the agent id — fall back to the
-    // session header id.
-    ctx.emit('session/event', makeSession('main'), {
+    // After disposal the event belongs to a non-target session, so its durable
+    // identity is rendered directly.
+    ctx.emit('session/event', agent.session, {
      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
    } as SessionEvent)
-    expect(out.text()).toContain('[main-session turn 1] ')
+    expect(out.text()).toContain('[main turn 1] ')
+  })
+
+  it('keeps the target when a different agent is disposed', async () => {
+    const { ctx, out } = await setup()
+    const target = makeAgent('target')
+    ctx.emit('agent/created', target)
+    ctx.emit('agent/disposed', makeAgent('other'))
+    ctx.emit('session/event', target.session, {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main turn 1] ')
  })

  it('renders tool/call and tool/result session events', async () => {
@@ -666,11 +674,11 @@ describe('createStdioChat input', () => {
    const spy = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {})
    input.feed('nobody home')
    await new Promise(r => setImmediate(r))
-    expect(spy).toHaveBeenCalledWith('ui-stdio: agent "%s" is not running', 'main')
+    expect(spy).toHaveBeenCalledWith('ui-stdio: main agent is not running')
  })

-  it('drives the agent named in config, not a hardcoded id', async () => {
-    const { ctx, input } = await setup({ welcome: 'w', agent: 'worker' })
+  it('drives the app-owned agent without a duplicate id config', async () => {
+    const { ctx, input } = await setup({ welcome: 'w' })
    const agent = makeAgent('worker')
    ctx.agents.register(agent)
    input.feed('hi')