refactor: brand the command lifecycle pairing id as CommandId

commandId crosses three boundaries (session log, wire admission response,
client flow pairing), so per the branded-id rule it becomes
Branded<'CommandId'>, declared in a new pure @deepseek-ai/dsh-commands/brand
outlet (the dsh-llm/brand shape: type + constructor, no Context merges, so
wire and client programs can name it without loading the host plugin). The
event payloads, CommandExecution, and the executor mint carry the brand; the
wire schema gains commandIdSchema as the domain's single brand-cast point
(the approvals precedent); CommandNode and the fixture's fabrication cast
follow type-only.

packages/client/connection/package.json

@@ -30,6 +30,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^"

packages/client/connection/src/client/fixture.ts

@@ -7,6 +7,9 @@
 
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { SessionEvent, SessionId, TodoItem } from '@deepseek-ai/dsh-session/types'
+// Type-only: the brand constructor is host-side; the fixture casts at its
+// wire-fabrication boundary (the schema layer's one-cast-point posture).
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
   RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
@@ -838,7 +841,7 @@ export function createFixtureApi(options: FixtureOptions = {}): ApiProxy {
         }
         const text = name === undefined ? undefined : outcomes[name]
         if (name === undefined || text === undefined) return ok(request, { matched: false as const })
-        const commandId = `fx-cmd-${logOf(id).length}`
+        const commandId = `fx-cmd-${logOf(id).length}` as CommandId
         append(id, { type: 'command/run', data: { commandId, name, args, source: { kind: 'user' } } })
         append(id, { type: 'command/done', data: { commandId, kind: 'success', ...text === '' ? {} : { text } } })
         return ok(request, { matched: true as const, commandId })

packages/client/connection/tests/fake-api.ts

@@ -1,6 +1,7 @@
 // Test-local programmable IApiClient fake (NOT the fixture: fixture is a demo
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
   CommandDescriptor, HostFrame, IApiClient, MuxFrame,
   RpcRequest, RpcResponse, SessionId, SkillEntry,
@@ -94,7 +95,7 @@ export class FakeApiClient implements IApiClient {
   // wire shapes so cases can program catalogs and skill lists without casts.
   onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
     = () => Promise.resolve(ok({ commands: [] }))
-  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; commandId?: string }>>
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; commandId?: CommandId }>>
     = () => Promise.resolve(ok({ matched: false }))
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))

packages/client/connection/tsconfig.json

@@ -15,6 +15,9 @@
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../ui/commands"
+    },
     {
       "path": "../../util/brand"
     },

packages/client/runtime/package.json

@@ -32,6 +32,7 @@
   "license": "BSD-3-Clause",
   "dependencies": {
     "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",

packages/client/runtime/src/client/sessions/conversation.ts

@@ -3,6 +3,7 @@
 // substructures keep their references (the React.memo premise). callId/approvalId stay plain
 // string here (narrow to real brands when convenient).
 
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm/types'
 import type { TodoItem } from '@deepseek-ai/dsh-session/types'
 import type {
@@ -136,7 +137,7 @@ export interface CommandNode {
   /** Unix epoch ms of the anchoring event. */
   time: number
   /** Pairing id minted by the host executor. */
-  commandId: string
+  commandId: CommandId
   /** Command name (run payload's structured field); null when the run fell outside the window. */
   name: string | null
   /** Verbatim rawInput after the name, separator whitespace included (run payload); null when the run fell outside the window. */

packages/client/runtime/src/client/sessions/fold-adapter.ts

@@ -8,6 +8,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session/types'
 // go through it — the package root points at lib/index.js (needs a build) which the vite
 // browser bundle cannot resolve; surface.ts has no Node dependencies.
 import { SurfaceManager, isSurfaceEligibleType } from '@deepseek-ai/dsh-session/surface'
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { ToolCallView, ToolEventView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
 import type { CommandNode, ConversationNode } from './conversation.ts'
 import { toAssistantBlocks } from './conversation.ts'
@@ -229,7 +230,7 @@ export class FoldAdapter {
     // enter the client program, so this wire consumer narrows structurally
     // (the same posture as tool/code-dispatch in session.ts).
     if ((event.type as string) === 'command/run') {
-      const data = event.data as unknown as { commandId: string; name: string; args: string }
+      const data = event.data as unknown as { commandId: CommandId; name: string; args: string }
       this.commandIdx.set(data.commandId, {
         kind: 'command', seq: event.seq, time: event.time,
         commandId: data.commandId, name: data.name, args: data.args, outcome: null,
@@ -237,7 +238,7 @@ export class FoldAdapter {
       return
     }
     if ((event.type as string) !== 'command/done') return
-    const data = event.data as unknown as { commandId: string; kind: 'success' | 'error'; text?: string }
+    const data = event.data as unknown as { commandId: CommandId; kind: 'success' | 'error'; text?: string }
     const run = this.commandIdx.get(data.commandId)
     const outcome = { kind: data.kind, ...data.text === undefined ? {} : { text: data.text } }
     if (run === undefined) {

packages/client/runtime/tests/fake-api.ts

@@ -1,6 +1,7 @@
 // Test-local programmable IApiClient fake (NOT the fixture: fixture is a demo
 // data source on a real clock; behavior tests need per-case responses and
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
   ClientResponse, CommandDescriptor, HostFrame, IApiClient, MuxFrame,
   RpcError, RpcReceipt, RpcRequest, RpcResponse, SessionId, SkillEntry,
@@ -119,7 +120,7 @@ export class FakeApiClient implements IApiClient {
   // skill lists without casts.
   onCommandList: (payload: unknown) => Promise<RpcResponse<{ commands: CommandDescriptor[] }>>
     = () => Promise.resolve(ok({ commands: [] }))
-  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; commandId?: string }>>
+  onCommandExecute: (payload: unknown) => Promise<RpcResponse<{ matched: boolean; commandId?: CommandId }>>
     = () => Promise.resolve(ok({ matched: false }))
   onSkillList: (payload: unknown) => Promise<RpcResponse<{ skills: SkillEntry[] }>>
     = () => Promise.resolve(ok({ skills: [] }))

packages/client/runtime/tsconfig.json

@@ -23,6 +23,9 @@
     {
       "path": "../../host/apiproxy"
     },
+    {
+      "path": "../../ui/commands"
+    },
     {
       "path": "../../session-projection/session-projection"
     },

packages/client/ui-conversation/tests/chat-view.spec.tsx

@@ -366,7 +366,7 @@ describe('ChatView', () => {
 
   it('renders command nodes as durable rows: settled text, error state, executing spinner, run-less soft-fall', () => {
     const command = (over: Partial<CommandNode>): CommandNode => ({
-      kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1',
+      kind: 'command', seq: 5, time: 5_000, commandId: 'cmd-1' as CommandNode['commandId'],
       name: 'plan', args: '', outcome: { kind: 'success', text: '已进入 plan mode' },
       ...over,
     })
@@ -378,7 +378,7 @@ describe('ChatView', () => {
 
     // Error outcome flips the row state; a text-less error gets the default copy.
     const failed = makeHarness({
-      nodes: [command({ seq: 6, commandId: 'cmd-2', outcome: { kind: 'error' } })],
+      nodes: [command({ seq: 6, commandId: 'cmd-2' as CommandNode['commandId'], outcome: { kind: 'error' } })],
     })
     const fv = render(<failed.ChatView {...failed.props} />)
     expect(fv.container.querySelector('[data-state="error"]')).not.toBeNull()
@@ -386,7 +386,7 @@ describe('ChatView', () => {
 
     // Still executing: running state with the executing copy.
     const executing = makeHarness({
-      nodes: [command({ seq: 7, commandId: 'cmd-3', outcome: null })],
+      nodes: [command({ seq: 7, commandId: 'cmd-3' as CommandNode['commandId'], outcome: null })],
     })
     const xv = render(<executing.ChatView {...executing.props} />)
     expect(xv.container.querySelector('[data-state="running"]')).not.toBeNull()
@@ -394,7 +394,7 @@ describe('ChatView', () => {
 
     // Cross-window soft-fall (run page truncated): generic title, outcome preserved.
     const orphan = makeHarness({
-      nodes: [command({ seq: 8, commandId: 'cmd-4', name: null, args: null, outcome: { kind: 'success' } })],
+      nodes: [command({ seq: 8, commandId: 'cmd-4' as CommandNode['commandId'], name: null, args: null, outcome: { kind: 'success' } })],
     })
     const ov = render(<orphan.ChatView {...orphan.props} />)
     expect(ov.getByText('命令')).toBeTruthy()