refactor(client): command decorations replace the hostBacked contribution mode

A popup on a host command is not a second command — it is what that
command's BARE invocation does on this client. CommandContribution loses
hostBacked (contributions are pure client commands again; a host-name
collision fails loud, unchanged for /model), and the contract gains
CommandDecoration + command.decorate(): key = the HOST command name, no
catalog row, no claim participation. Dispatch consults decorations only on
the bare paths (menu pick / bare enter) after the host row resolves; space
and argued enter never see them — the two edges hostBacked had to guard
explicitly hold by construction in the decoration model. A decorated name
with no host row in the session's directory never fires (a decoration
cannot manufacture a command).

ui-permission switches register→decorate with zero behavior change
(options still read the permissions projection; a pick still submits
'/permission <preset>'). Specs rewrite to the decoration semantics: no
catalog row, bare-enter popup vs argued-enter host claim, space host
claim, no-host-row miss, unavailable fall-through, duplicate fail-loud.

packages/client/ui-command/README.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-README.md: 17bc4edd7d002d6bba4470c9418a9179b2cb131b
-README.zh.md: 1291556409b993aa893e102386f75c45bb195adf
+#   pnpm run verify-translation-pairing --write packages/client/ui-command/README.md
+README.md: 64d06f1d9baae98ef31c7e2a62242eda6a8174da
+README.zh.md: 0cec3b8c8f7baf2fb1c408bccfe8937aa78e4bf9

packages/client/ui-command/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Client command surface (`ctx.command`): the session-keyed command-directory cache, the `/` command source with matchSpace/matchEnter adjudication hooks, three-kind dispatch (execute / popupSelect / leadingInput), and the popupSelect registration face for business packages. Contract: the [web command surfaces Agent Note](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md).
 
-`src/client/contract.ts` is the frozen business face: `CommandServiceContract.register(name, spec)` is everything a business package consumes; `CommandUiSpec{options, onSelect}` keeps popup data self-served — the shell component is this package's and business never sees it. Command kinds derive per dispatch, never per registration: a host descriptor with `input` is leadingInput, a registered `CommandUiSpec` is popupSelect, everything else is execute.
+`src/client/contract.ts` is the frozen business face: `CommandServiceContract.register(name, spec)` and `decorate(name, spec)` are everything a business package consumes; `CommandUiSpec{options, onSelect}` keeps popup data self-served — the shell component is this package's and business never sees it. A contribution is a client-owned command (a host-name collision fails loud); a decoration hangs a bare-invocation popup on an EXISTING host command — the host keeps its catalog row, argument claim (space / argued enter), and lifecycle logging, and a decorated name with no host row in the session's directory simply never fires. Command kinds derive per dispatch, never per registration: a host descriptor with `input` is leadingInput, a registered `CommandUiSpec` is popupSelect, everything else is execute.
 
 `CommandDirectory` (`src/client/directory.ts`) is the one wire-derived cache, keyed by session: every session is agent-backed, so `command.list({sessionId})` is the only address shape and the source's scope-birth `warm` hook prewarms the session's entry. Entries are soft-invalidated by the `commands/changed` typed event (old snapshot serves while the repull flies), hard-invalidated by `connection/reset`, epoch-guarded so a superseded pull can never overwrite a newer one. `matchSpace` answers synchronously from this cache only; `matchEnter` strong-waits it on the SubmitAttempt signal and rejects on warmup failure — a `/` line is never silently downgraded to a plain prompt.
 

packages/client/ui-command/README.zh.md

@@ -4,7 +4,7 @@
 
 客户端命令业务面（`ctx.command`）：以会话为 key 的命令目录缓存、带 matchSpace／matchEnter 裁决钩子的 `/` 命令 source、三型派发（execute／popupSelect／leadingInput），以及面向业务包的 popupSelect 注册面。契约：[Web 命令业务面 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-25-web-command-surfaces-and-assembly.zh.md)。
 
-`src/client/contract.ts` 是冻结的业务表层：`CommandServiceContract.register(name, spec)` 是业务包消费的全部内容；`CommandUiSpec{options, onSelect}` 让 popup 数据自给自足——壳组件归本包所有，业务永远见不到它。命令三型按每次派发派生，绝不在注册时定型：带 `input` 的 host descriptor 是 leadingInput，注册了 `CommandUiSpec` 的是 popupSelect，其余全部是 execute。
+`src/client/contract.ts` 是冻结的业务表层：`CommandServiceContract.register(name, spec)` 与 `decorate(name, spec)` 是业务包消费的全部内容；`CommandUiSpec{options, onSelect}` 让 popup 数据自给自足——壳组件归本包所有，业务永远见不到它。contribution 是 client 自有命令（与 host 同名碰撞即 fail-loud）；decoration（装饰）则把裸调用 popup 挂在**已存在的** host 命令上——host 保留目录行、带参 claim（space / 带参 enter）与生命周期记账，被装饰的名字若在会话目录中无 host 行则装饰永不触发。命令三型按每次派发派生，绝不在注册时定型：带 `input` 的 host descriptor 是 leadingInput，注册了 `CommandUiSpec` 的是 popupSelect，其余全部是 execute。
 
 `CommandDirectory`（`src/client/directory.ts`）是唯一的 wire 派生缓存，以会话为 key：每个会话恒为 agent-backed，因此 `command.list({sessionId})` 是唯一的寻址形状，source 的 scope 出生 `warm` 钩子会预热该会话的缓存项。缓存项由 `commands/changed` 类型化事件软失效（重拉在途期间旧快照继续服务），由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝——`/` 开头的一行绝不会被静默降级为普通提示词。
 

packages/client/ui-command/src/client/contract.ts

@@ -30,29 +30,37 @@ export type CommandUiSpec = {
  * One client-owned command contribution: a slash-menu entry whose behavior
  * lives entirely on the client (no host descriptor). Merged with the host
  * catalog by name — a collision with a host command fails loud at candidate
- * synthesis, never shadows — UNLESS the contribution declares `hostBacked`:
- * then the same-named host command owns execution and the contribution only
- * supplies the bare-invocation picker (menu row stays the host's; a bare
- * pick/enter opens the popup; a line with arguments falls through to the
- * host command's own path).
+ * synthesis, never shadows.
  */
 export interface CommandContribution {
   /** Command name without the leading slash (unique across contributions). */
   readonly name: string
   /** Menu row description. */
   readonly description: string
-  /**
-   * Cooperate with the same-named host command instead of colliding: the
-   * popup is the bare-invocation UI, the host command is the executor (its
-   * catalog row, argument claim, and lifecycle logging stand unchanged).
-   */
-  readonly hostBacked?: true
   /** Capability filter, called with a fresh projection per candidate pass. */
   available(session: ClientSessionContext): boolean
   /** The command's UI behavior (this phase: popupSelect only). */
   readonly ui: CommandUiSpec
 }
 
+/**
+ * A UI decoration hung on one HOST command: what its BARE invocation does on
+ * this client. Not a second command — the host command keeps its catalog
+ * row, its argument claim (space / argued enter), and its lifecycle logging;
+ * the decoration replaces only the bare menu-pick/enter with a popup whose
+ * onSelect typically submits a completed line back through command.execute.
+ * A decoration never manufactures a row: a name with no host catalog entry
+ * in the session's directory simply never reaches the decoration.
+ */
+export interface CommandDecoration {
+  /** The HOST command name this decorates (without the leading slash). */
+  readonly name: string
+  /** Capability filter, called with a fresh projection per bare invocation. */
+  available(session: ClientSessionContext): boolean
+  /** The bare-invocation UI (this phase: popupSelect only). */
+  readonly ui: CommandUiSpec
+}
+
 /** The `ctx.command` service face visible to business packages. */
 export interface CommandServiceContract {
   /**
@@ -60,6 +68,11 @@ export interface CommandServiceContract {
    * names throw at registration.
    */
   register(contribution: CommandContribution): () => void
+  /**
+   * Hang a bare-invocation decoration on one host command; effect disposer.
+   * Duplicate names throw at registration.
+   */
+  decorate(decoration: CommandDecoration): () => void
   /** Resolve the per-session popup controller for one session scope (wiring/overlay layer). */
   popupFor(actx: ClientContext): unknown
 }

packages/client/ui-command/src/client/index.ts

@@ -21,7 +21,7 @@ export { filterOptions, PopupSelectController } from './popup.ts'
 export type { PopupSelectDeps, PopupSpec, PopupState, TokenSegment } from './popup.ts'
 export type { PopupSelectInjected } from './PopupSelectView.tsx'
 export type {
-  CommandContribution, CommandServiceContract, CommandUiSpec, SelectOption,
+  CommandContribution, CommandDecoration, CommandServiceContract, CommandUiSpec, SelectOption,
 } from './contract.ts'
 
 declare module 'cordis' {

packages/client/ui-command/src/client/service.ts

@@ -14,7 +14,7 @@ import type {
   CandidateRequest, ClientSessionContext, CommandClaim, PickOutcome, SlashCandidate, SlashPick,
   SubmitOutcome,
 } from '@deepseek-ai/dsh-client-ui-slash/client'
-import type { CommandContribution, CommandServiceContract } from './contract.ts'
+import type { CommandContribution, CommandDecoration, CommandServiceContract } from './contract.ts'
 import type { CommandDescriptor } from './directory.ts'
 import { CommandDirectory } from './directory.ts'
 import { PopupSelectController } from './popup.ts'
@@ -23,6 +23,7 @@ import type { TokenSegment } from './popup.ts'
 /** Live mutable state in one holder (service methods run behind the caller-ctx tracker). */
 interface LiveState {
   readonly contributions: Map<string, CommandContribution>
+  readonly decorations: Map<string, CommandDecoration>
   readonly popups: Map<SessionId, PopupSelectController<ClientSessionContext>>
 }
 
@@ -31,7 +32,7 @@ export class CommandService extends Service implements CommandServiceContract {
   static inject = ['slash', 'sessions', 'connection']
 
   private readonly directory: CommandDirectory
-  private readonly live: LiveState = { contributions: new Map(), popups: new Map() }
+  private readonly live: LiveState = { contributions: new Map(), decorations: new Map(), popups: new Map() }
 
   /**
    * @param ctx - owning root context (plugin fiber; the service registers
@@ -79,6 +80,24 @@ export class CommandService extends Service implements CommandServiceContract {
     return () => { void dispose() }
   }
 
+  /**
+   * Hang a bare-invocation decoration on one host command; effect disposer
+   * (rides the caller's fiber). Duplicate names throw.
+   * @param decoration - host command name + availability + popup spec.
+   * @returns the disposer removing the registration.
+   */
+  decorate(decoration: CommandDecoration): () => void {
+    const dispose = this.ctx.effect(() => {
+      const { decorations } = this.live
+      if (decorations.has(decoration.name)) {
+        throw new Error(`ui-command: duplicate decoration for /${decoration.name}`)
+      }
+      decorations.set(decoration.name, decoration)
+      return () => { decorations.delete(decoration.name) }
+    }, 'command.decorate()')
+    return () => { void dispose() }
+  }
+
   /**
    * Resolve the per-session popup controller (lazy; dies with the session
    * scope). The controller's consume callback dispatches the scoped
@@ -139,9 +158,6 @@ export class CommandService extends Service implements CommandServiceContract {
     for (const contribution of this.live.contributions.values()) {
       if (!contribution.available(session)) continue
       if (seen.has(contribution.name)) {
-        // hostBacked cooperates: the host's catalog row stands, the
-        // contribution only supplies the bare-invocation popup.
-        if (contribution.hostBacked === true) continue
         throw new Error(`ui-command: contribution /${contribution.name} collides with a host command`)
       }
       rows.push({ name: contribution.name, description: contribution.description })
@@ -151,16 +167,24 @@ export class CommandService extends Service implements CommandServiceContract {
       .filter(c => req.position === 'leading' || c.hint === undefined)
   }
 
-  /** Decision table, menu column: contribution → popup; host input → claim; host bare → detached execute. */
+  /** Decision table, menu column: contribution/decorated-host → popup; host input → claim; host bare → detached execute. */
   private dispatch(pick: SlashPick): PickOutcome {
     const name = pick.candidate.name
     const contribution = this.live.contributions.get(name)
     if (contribution !== undefined && contribution.available(pick.session)) {
-      this.openPopup(contribution, pick.session, { via: 'menu', span: pick.span })
+      this.openPopup(name, contribution.ui, pick.session, { via: 'menu', span: pick.span })
       return 'handled'
     }
     const desc = this.directory.resolve(pick.session.sessionId, name)
     if (desc === undefined) return undefined // snapshot swapped between menu and pick → miss
+    // A decoration replaces the HOST row's bare invocation with its popup;
+    // it decorates only a resolvable host command (checked above), never
+    // manufactures one, and never touches the argument claim below.
+    const decoration = this.live.decorations.get(name)
+    if (decoration !== undefined && decoration.available(pick.session)) {
+      this.openPopup(name, decoration.ui, pick.session, { via: 'menu', span: pick.span })
+      return 'handled'
+    }
     if (desc.input !== undefined) return { claim: this.leadingClaim(desc, pick.session) }
     // Menu-pick execute consumes the trigger span before the detached run
     // (scoped event; the input owns the CAS guard).
@@ -173,10 +197,7 @@ export class CommandService extends Service implements CommandServiceContract {
   private matchSpace(session: ClientSessionContext, token: string): PickOutcome {
     if (!token.startsWith('/')) return undefined
     const name = token.slice(1)
-    // Popup kinds never claim on space; a hostBacked popup defers to the
-    // host command's own claim (the popup serves only the bare invocation).
-    const spaceContribution = this.live.contributions.get(name)
-    if (spaceContribution !== undefined && spaceContribution.hostBacked !== true) return undefined
+    if (this.live.contributions.has(name)) return undefined // popup kinds never claim on space
     const desc = this.directory.resolve(session.sessionId, name)
     if (desc === undefined || desc.input === undefined) return undefined
     return { claim: this.leadingClaim(desc, session) }
@@ -198,17 +219,22 @@ export class CommandService extends Service implements CommandServiceContract {
     if (name === '') return undefined
     const contribution = this.live.contributions.get(name)
     if (contribution !== undefined && contribution.available(session)) {
-      if (bare) {
-        this.openPopup(contribution, session, { via: 'enter', token })
-        return 'handled'
-      }
-      // hostBacked + arguments: the host command owns the argued path
-      // (claim or detached run below); a pure contribution stays bare-only.
-      if (contribution.hostBacked !== true) return undefined
+      if (!bare) return undefined
+      this.openPopup(name, contribution.ui, session, { via: 'enter', token })
+      return 'handled'
     }
     await this.directory.ensureReady(session.sessionId, signal)
     const desc = this.directory.resolve(session.sessionId, name)
     if (desc === undefined) return undefined
+    // Bare enter on a decorated host command opens its popup; an argued line
+    // never consults the decoration (the claim/detached paths below own it).
+    if (bare) {
+      const decoration = this.live.decorations.get(name)
+      if (decoration !== undefined && decoration.available(session)) {
+        this.openPopup(name, decoration.ui, session, { via: 'enter', token })
+        return 'handled'
+      }
+    }
     if (desc.input !== undefined) return { claim: this.leadingClaim(desc, session) }
     if (!bare) return undefined
     this.consumeVia(session.sessionId, { via: 'enter', token })
@@ -216,15 +242,16 @@ export class CommandService extends Service implements CommandServiceContract {
     return 'handled'
   }
 
-  /** Open the session's popup for one contribution (menu pick / bare enter). */
+  /** Open the session's popup for one contribution or decoration (menu pick / bare enter). */
   private openPopup(
-    contribution: CommandContribution,
+    name: string,
+    ui: CommandContribution['ui'],
     session: ClientSessionContext,
     segment: TokenSegment,
   ): void {
     const actx = this.scopeFor(session.sessionId)
     if (actx === undefined) return
-    this.popupFor(actx).open(contribution.name, contribution.ui, session, segment)
+    this.popupFor(actx).open(name, ui, session, segment)
   }
 
   /** Build the leadingInput claim: token `/name ` + the command.execute submit transaction. */

packages/client/ui-command/tests/service.spec.ts

@@ -12,7 +12,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { createScope, scopeOf } from '@deepseek-ai/dsh-client-runtime/client'
 import type { SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ClientSessionContext, ConsumeTokenRequest, SlashPick, SlashSource } from '@deepseek-ai/dsh-client-ui-slash/client'
-import type { CommandContribution, CommandUiSpec, SelectOption } from '../src/client/contract.ts'
+import type { CommandContribution, CommandDecoration, CommandUiSpec, SelectOption } from '../src/client/contract.ts'
 import type { CommandDescriptor } from '../src/client/directory.ts'
 import { CommandService } from '../src/client/service.ts'
 
@@ -198,18 +198,26 @@ describe('candidates', () => {
     await expect(source.candidates(proj('s1'), req(''))).rejects.toThrow('collides with a host command')
   })
 
-  it('a hostBacked contribution cooperates: the host row stands, no duplicate, no throw', async () => {
+})
+
+describe('decorations (bare-invocation UI on host commands)', () => {
+  const goalDecoration = (over: Partial<CommandDecoration> = {}): CommandDecoration => ({
+    name: 'goal',
+    available: () => true,
+    ui: themeUi(),
+    ...over,
+  })
+
+  it('adds no catalog row: the host row stands alone', async () => {
     const { command, source } = await bench()
-    command.register(themeContribution({ name: 'goal', hostBacked: true }))
+    command.decorate(goalDecoration())
     const names = (await source.candidates(proj('s1'), req(''))).map(c => c.name)
     expect(names).toEqual(['plan', 'goal'])
   })
-})
 
-describe('hostBacked enter/space columns', () => {
-  it('bare enter opens the popup; an argued line falls through to the host claim', async () => {
+  it('bare enter opens the popup; an argued line never consults the decoration (host claim)', async () => {
     const { command, source, mint, warm } = await bench()
-    command.register(themeContribution({ name: 'goal', hostBacked: true }))
+    command.decorate(goalDecoration())
     const scope = mint('s1')
     await warm(proj('s1'))
     expect(await source.matchEnter!(proj('s1'), '/goal', new AbortController().signal)).toBe('handled')
@@ -219,14 +227,38 @@ describe('hostBacked enter/space columns', () => {
     expect(argued.claim.token).toBe('/goal ')
   })
 
-  it('space defers to the host claim instead of the popup', async () => {
+  it('space never consults the decoration (host claim)', async () => {
     const { command, source, warm } = await bench()
-    command.register(themeContribution({ name: 'goal', hostBacked: true }))
+    command.decorate(goalDecoration())
     await warm(proj('s1'))
     const outcome = source.matchSpace!(proj('s1'), '/goal')
     if (outcome === undefined || outcome === 'handled' || !('claim' in outcome)) throw new Error('expected the host claim')
     expect(outcome.claim.token).toBe('/goal ')
   })
+
+  it('a decoration with no host row never fires (bare enter misses; menu pick misses)', async () => {
+    const { command, source, mint, warm } = await bench()
+    command.decorate(goalDecoration({ name: 'phantom' }))
+    const scope = mint('s1')
+    await warm(proj('s1'))
+    expect(await source.matchEnter!(proj('s1'), '/phantom', new AbortController().signal)).toBeUndefined()
+    expect(menuPick(source, 'phantom', proj('s1'))).toBeUndefined()
+    expect(command.popupFor(scope.ctx).state.getSnapshot().open).toBe(false)
+  })
+
+  it('an unavailable decoration falls through to the host bare path (detached execute)', async () => {
+    const { command, source, warm, executeCalls } = await bench()
+    command.decorate(goalDecoration({ name: 'plan', available: () => false }))
+    await warm(proj('s1'))
+    expect(await source.matchEnter!(proj('s1'), '/plan', new AbortController().signal)).toBe('handled')
+    expect(executeCalls).toEqual([{ sessionId: sid('s1'), line: '/plan' }])
+  })
+
+  it('duplicate decoration names fail loud', async () => {
+    const { command } = await bench()
+    command.decorate(goalDecoration())
+    expect(() => { command.decorate(goalDecoration()) }).toThrow('duplicate decoration for /goal')
+  })
 })
 
 describe('dispatch (menu column)', () => {