feat(types): brand bash ids + stop brand erosion; extract Branded to dsh-brand

Type-only change (brands are zero-cost casts; no runtime/wire impact). Closes
the two gaps in the "brand ids that cross package boundaries" policy and fixes
the dependency direction so a capability package never pulls in an unrelated one.

- Extract the `Branded<B>` primitive into a new standalone type-only package
  `@deepseek-ai/dsh-brand` (packages/util/brand) with no harness-package deps.
  dsh-llm keeps its owned CallId but imports Branded from dsh-brand; dsh-session,
  dsh-agent, and dsh-bash all import Branded from there. dsh-bash depends on
  dsh-brand ALONE — never on dsh-llm or dsh-session (the architectural fix: a
  generic execution backend must not couple to the LLM or session vocabulary).
- Mint BashTaskId + OwnerToken in dsh-bash and thread them through BashTask.id,
  the get/ownerOf/list/readOutput/kill seam, the bash-local generation site, and
  the dsh-tool-bash validate/access surface. OwnerToken is a DISTINCT brand from
  SessionId so the seam stays decoupled; dsh-tool-bash is the single boundary
  that casts SessionId -> OwnerToken.
- Brand at the SOURCE, not via mid-pipeline casts: agent-loop's Config types
  agents[].id as AgentId and resumeSessionId as SessionId, so the brand enters
  at the config boundary and the inner create()/resume casts disappear (only the
  genuinely-new per-run session-id string is cast).
- Stop brand erosion: propagate CallId/SessionId/AgentId to the registry/store
  Map keys and public params/exports (SessionStore, AgentRegistry + factory
  options, the ACP session-id surface + ToolPresenter CallId map, the
  persistence coordinator, invariants pendingCalls, the pi-ai tool-call maps).
- Docs: document BashTaskId/OwnerToken in bash.md (type-equiv re-pasted), point
  the Branded type-equiv at dsh-brand, fix stale param types in the session/
  agent/bash READMEs, regenerate the cordis catalog + module graph.

Implements docs/rfc/proposed/architecture/2026-06-20-branded-ids.md

packages/core/agent/README.md

@@ -9,7 +9,7 @@ Tracks live agents so UI, hook, and orchestrator plugins can find them without i
 ### Public API
 
 - `ctx.agents.register(agent: Agent): () => void` — record an **already-constructed** agent. Disposed with the calling fiber.
-- `ctx.agents.get(id: string): Agent | undefined`
+- `ctx.agents.get(id: AgentId): Agent | undefined`
 - `ctx.agents.list(): Agent[]`
 
 #### Factory seam (creation)

packages/core/agent/package.json

@@ -20,11 +20,13 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.6"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.6"

packages/core/agent/src/index.ts

@@ -7,7 +7,7 @@
 
 import { Context, Service } from 'cordis'
 import type { SessionId } from '@deepseek-ai/dsh-session'
-import type { Agent, AgentOptions } from './types.ts'
+import type { Agent, AgentId, AgentOptions } from './types.ts'
 
 export * from './types.ts'
 
@@ -26,9 +26,9 @@ declare module 'cordis' {
  */
 export interface CreateAgentOptions {
   /** The agent's id (the registry handle). */
-  agentId: string
+  agentId: AgentId
   /** The live session's id (NOT derived from agentId). */
-  sessionId: string
+  sessionId: SessionId
   /**
    * Session creation metadata: validated absolute `cwd` and `parentSession`
    * fork lineage. Mirrors the `cwd`/`parentSession` fields of
@@ -47,9 +47,9 @@ export interface CreateAgentOptions {
  */
 export interface ResumeAgentOptions {
   /** The agent's id (the registry handle). */
-  agentId: string
+  agentId: AgentId
   /** The persisted session id to load and resume on. */
-  resumeSessionId: string
+  resumeSessionId: SessionId
   /** Per-agent options (model, system prompt). */
   agentOptions?: AgentOptions
 }
@@ -103,7 +103,7 @@ const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plug
  * {@link setFactory}.
  */
 export class AgentRegistry extends Service {
-  private store = new Map<string, Agent>()
+  private store = new Map<AgentId, Agent>()
   private factory: AgentFactory | undefined
 
   constructor(ctx: Context) {
@@ -188,7 +188,7 @@ export class AgentRegistry extends Service {
     return () => void dispose()
   }
 
-  get(id: string): Agent | undefined {
+  get(id: AgentId): Agent | undefined {
     return this.store.get(id)
   }
 

packages/core/agent/src/types.ts

@@ -9,7 +9,8 @@
  * @module @deepseek-ai/dsh-agent/types
  */
 
-import type { Branded, ContentBlock, GenerateOptions, Message, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import type { ContentBlock, GenerateOptions, Message, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm'
 
 /** Identifies one live agent in the registry. */
 export type AgentId = Branded<'AgentId'>

packages/core/agent/tests/agent.spec.ts

@@ -32,12 +32,12 @@ describe('AgentRegistry', () => {
     const agent = stubAgent('a1')
     const dispose = ctx.agents.register(agent)
     expect(created).toEqual(['a1'])
-    expect(ctx.agents.get('a1')).toBe(agent)
+    expect(ctx.agents.get(AgentId('a1'))).toBe(agent)
     expect(ctx.agents.list()).toEqual([agent])
 
     dispose()
     expect(disposed).toEqual(['a1'])
-    expect(ctx.agents.get('a1')).toBeUndefined()
+    expect(ctx.agents.get(AgentId('a1'))).toBeUndefined()
   })
 
   it('rejects duplicate ids and unregisters on fiber dispose (HMR safety)', async () => {
@@ -66,14 +66,14 @@ describe('AgentRegistry', () => {
 
     // The throwing emit must roll the entry back, not leak it.
     expect(() => ctx.agents.register(stubAgent('main'))).toThrow('boom created listener')
-    expect(ctx.agents.get('main')).toBeUndefined() // rolled back, not leaked
+    expect(ctx.agents.get(AgentId('main'))).toBeUndefined() // rolled back, not leaked
 
     // A subsequent listener-free register of the SAME id succeeds and is
     // tracked exactly once (the duplicate-id check is not wedged).
     const dispose = ctx.agents.register(stubAgent('main'))
     expect(ctx.agents.list().map(a => a.id)).toEqual(['main'])
     dispose()
-    expect(ctx.agents.get('main')).toBeUndefined()
+    expect(ctx.agents.get(AgentId('main'))).toBeUndefined()
   })
 })
 
@@ -97,8 +97,8 @@ describe('AgentRegistry factory seam', () => {
   it('create()/resume() throw when no factory is registered', async () => {
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
-    expect(() => ctx.agents.create({ agentId: 'a', sessionId: 's' })).toThrow(/no agent factory/)
-    await expect(ctx.agents.resume({ agentId: 'a', resumeSessionId: 's' })).rejects.toThrow(/no agent factory/)
+    expect(() => ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).toThrow(/no agent factory/)
+    await expect(ctx.agents.resume({ agentId: AgentId('a'), resumeSessionId: SessionId('s') })).rejects.toThrow(/no agent factory/)
   })
 
   it('setFactory registers a factory; create/resume delegate to it', async () => {
@@ -107,13 +107,13 @@ describe('AgentRegistry factory seam', () => {
     const { factory, calls } = stubFactory()
     ctx.agents.setFactory(factory)
 
-    const created = ctx.agents.create({ agentId: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } })
+    const created = ctx.agents.create({ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } })
     expect(created.agent.id).toBe('c1')
-    expect(calls.create).toEqual([{ agentId: 'c1', sessionId: 'sess-1', meta: { cwd: '/w' } }])
+    expect(calls.create).toEqual([{ agentId: AgentId('c1'), sessionId: SessionId('sess-1'), meta: { cwd: '/w' } }])
 
-    const resumed = await ctx.agents.resume({ agentId: 'r1', resumeSessionId: 'old-sess' })
+    const resumed = await ctx.agents.resume({ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') })
     expect(resumed.agent.id).toBe('r1')
-    expect(calls.resume).toEqual([{ agentId: 'r1', resumeSessionId: 'old-sess' }])
+    expect(calls.resume).toEqual([{ agentId: AgentId('r1'), resumeSessionId: SessionId('old-sess') }])
   })
 
   it('setFactory rejects a second factory', async () => {
@@ -130,10 +130,10 @@ describe('AgentRegistry factory seam', () => {
     const fiber = await ctx.plugin(Object.assign((inner: Context) => {
       dispose = inner.agents.setFactory(stubFactory().factory)
     }, { inject: ['agents'] }))
-    expect(() => ctx.agents.create({ agentId: 'a', sessionId: 's' })).not.toThrow()
+    expect(() => ctx.agents.create({ agentId: AgentId('a'), sessionId: SessionId('s') })).not.toThrow()
     void dispose
     await fiber.dispose()
     // factory slot cleared → create throws again
-    expect(() => ctx.agents.create({ agentId: 'a2', sessionId: 's2' })).toThrow(/no agent factory/)
+    expect(() => ctx.agents.create({ agentId: AgentId('a2'), sessionId: SessionId('s2') })).toThrow(/no agent factory/)
   })
 })

packages/core/agent/tsconfig.json

@@ -14,6 +14,9 @@
     {
       "path": "../../../vendor/cordis"
     },
+    {
+      "path": "../../util/brand"
+    },
     {
       "path": "../../llm/llm"
     },