Merge remote-tracking branch 'origin/master' into worktree/web-skill-tool-row

# Conflicts:
#	packages/host/apiproxy/README.i18n.yaml

packages/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/README.md
-README.md: 4832fffbc8963b8a7b1f8332e691083195bf94bc
-README.zh.md: 076b4f877070fcf0ee6b98d2310d1121cbbe63d6
+README.md: dec4d71ca2d323fe05f918dd3bf4709cfa01878e
+README.zh.md: 9596dfe8bf8d2d6144ffe7820886342707dd3009

packages/README.md

@@ -31,9 +31,10 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`spill/`](spill/README.md) | Spill capability family: storage seam, local impl, tool-result spill policy | Product — stable surface |
 | [`todo/`](todo/README.md) | The model-facing `todo_write` tool | Product — stable surface |
 | [`plan/`](plan/README.md) | Plan collaboration state with a direct entry command and reviewed exit | Product — stable surface |
-| [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface |
-| [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface |
-| [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection/model-written temporary Plugins and restricted repository Plugin loading | Product — stable surface |
+| [`timeout/`](timeout/README.md) | Tool-call `tools/execute` deadline enforcement | Product — stable surface |
+| [`guard/`](guard/README.md) | Loop-hygiene advisory repeat-call reminders | Product — stable surface |
+| [`bundle/`](bundle/README.md) | Installable `dsh --profile` patch layers | Product — stable surface |
+| [`cordis/`](cordis/README.md) | Cordis runtime integration: self-inspection, temporary Plugins, restricted repository Plugin loading | Product — stable surface |
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-projection/`](session-projection/README.md) | Projection seam: domain fold units serve whole values | Product — stable surface |

packages/README.zh.md

@@ -31,9 +31,10 @@
 | [`spill/`](spill/README.md) | 溢出能力系列：存储 seam、本地实现、工具结果溢出策略 | 产品：稳定表面 |
 | [`todo/`](todo/README.md) | 面向模型的 `todo_write` 工具 | 产品：稳定表面 |
 | [`plan/`](plan/README.md) | Plan 协作状态，提供直接进入命令与经评审的退出 | 产品：稳定表面 |
-| [`timeout/`](timeout/README.md) | 工具调用超时策略：`tools/execute` 截止时间强制执行器 | 产品：稳定表面 |
-| [`guard/`](guard/README.md) | 循环卫生守卫：建议性重复调用提醒 | 产品：稳定表面 |
-| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检／模型编写的临时 Plugin，以及受限 repository Plugin 加载 | 产品：稳定表面 |
+| [`timeout/`](timeout/README.md) | 工具调用 `tools/execute` 截止时间强制执行 | 产品：稳定表面 |
+| [`guard/`](guard/README.md) | 循环卫生建议性重复调用提醒 | 产品：稳定表面 |
+| [`bundle/`](bundle/README.md) | 可安装的 `dsh --profile` 补丁层 | 产品：稳定表面 |
+| [`cordis/`](cordis/README.md) | Cordis 运行时集成：自检、临时 Plugin、受限 repository Plugin 加载 | 产品：稳定表面 |
 | [`hooks/`](hooks/README.md) | 钩子桥接 + 共享 Claude Code／Codex 协议格式库 | 产品：稳定表面 |
 | [`session-persistence/`](session-persistence/README.md) | 持久化 seam + JSONL/SQLite 后端 | 产品：稳定表面 |
 | [`session-projection/`](session-projection/README.md) | 投影 seam：领域折叠单元供给全量值 | 产品：稳定表面 |

packages/acp/acp/src/index.ts

@@ -184,13 +184,13 @@ export function apply(ctx: Context, config: AcpConfig): void {
     }
   })
 
-  ctx.on('agent/inbox/claimed', (agent, { message, turn }) => {
+  ctx.on('agent/inbox/claimed', ({ agent, message, turn }) => {
     const record = ownedRecord(agent)
     const inflight = record?.inflight
     if (inflight !== undefined && inflight.messageId === message.id) inflight.turn = turn
   })
 
-  ctx.on('agent/error', (agent, turn, _step, error) => {
+  ctx.on('agent/error', ({ agent, turn, error }) => {
     const record = ownedRecord(agent)
     const inflight = record?.inflight
     if (record === undefined || inflight === undefined || inflight.turn === turn) return

packages/acp/acp/tests/turns.spec.ts

@@ -87,7 +87,7 @@ describe('ACP prompt lifecycle', () => {
     const sessionId = await newSession(harness)
     const agent = harness.ctx.agents.get(SessionId(sessionId))!
     let injected = false
-    harness.ctx.on('agent/inbox/inserted', (subject, { message }) => {
+    harness.ctx.on('agent/inbox/inserted', ({ agent: subject, message }) => {
       if (subject === agent && message.source.kind === 'user' && !injected) {
         injected = true
         agent.inject(createUserMessage({ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } }))
@@ -235,7 +235,7 @@ describe('ACP prompt lifecycle', () => {
     harness = await makeBridgeHarness({ script: [errorResponse('transient boom'), textResponse('recovered')] })
     // A recovery policy: schedule one retry for the failed request.
     let retried = false
-    harness.ctx.on('agent/request-error', async (_subject) => {
+    harness.ctx.on('agent/request-error', async () => {
       if (!retried) {
         retried = true
         return { kind: 'retry' }
@@ -272,7 +272,7 @@ describe('ACP prompt lifecycle', () => {
   it('cancels a prompt removed before its turn claims it', async () => {
     harness = await makeBridgeHarness({ script: [] })
     const sessionId = await newSession(harness)
-    const dispose = harness.ctx.on('agent/inbox/inserted', (agent, { message }) => {
+    const dispose = harness.ctx.on('agent/inbox/inserted', ({ agent, message }) => {
       if (message.source.kind === 'user') agent.inbox.remove(message.id)
     })
 

packages/bash/tool-bash/tests/integration.spec.ts

@@ -48,7 +48,7 @@ afterEach(() => {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()

packages/bundle/README.i18n.yaml

@@ -0,0 +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 packages/bundle/README.md
+README.md: 4759170435a80e85731446cef21d24fff2abed66
+README.zh.md: 1ef610a1b7b3c591c9a900e04f2d8096b0b086b9

packages/bundle/README.md

@@ -0,0 +1,13 @@
+# bundle/ — profile plugin bundles
+
+English | [中文](README.zh.md)
+
+Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, making them installable patch layers for `dsh --profile` compositions ([profile contract](../ui/app-boot/README.md#profiles)). A bundle's substance is its patch list; some also ship runtime glue plugins their patch mounts.
+
+| Package | Role | ctx key |
+|---|---|---|
+| [`base/`](base/README.md) | The shared dsh core every profile applies first | — (patch only) |
+| [`web-app/`](web-app/README.md) | Browser surface: web patch layer + runtime glue plugin | mounts rows |
+| [`headless/`](headless/README.md) | One-shot task mode over base + web-app | mounts `headless-runner` |
+
+In-box bundles resolve from the dsh installation; out-of-tree bundles install into a profile through `dsh plugin --profile <name> add <package>`.

packages/bundle/README.zh.md

@@ -0,0 +1,13 @@
+# bundle/ — profile 插件组合包
+
+[English](README.md) | 中文
+
+Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包，因此可作为 patch 层安装进 `dsh --profile` 组合（[profile 契约](../ui/app-boot/README.md#profiles)）。组合包的实体是它的 patch 列表；有些组合包还附带由其 patch 挂载的运行时粘合插件。
+
+| 包 | 职责 | ctx key |
+|---|---|---|
+| [`base/`](base/README.md) | 每个 profile 最先应用的共享 dsh 核心 | —（仅 patch） |
+| [`web-app/`](web-app/README.md) | 浏览器表层：web patch 层 + 运行时粘合插件 | 挂载多条配置行 |
+| [`headless/`](headless/README.md) | 叠加在 base + web-app 之上的一次性任务模式 | 挂载 `headless-runner` |
+
+内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile <name> add <package>` 安装进 profile。

packages/bundle/base/README.i18n.yaml

@@ -0,0 +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 packages/bundle/base/README.md
+README.md: 301d397d4c87687b382665cf63af47ab5e3f85be
+README.zh.md: f007bc817b6cbad84725fe8abe72549cf67d8cd7

packages/bundle/base/README.md

@@ -0,0 +1,19 @@
+# `@deepseek-ai/dsh-base`
+
+English | [中文](README.zh.md)
+
+The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
+
+The row set and its rationale are documented inline in the patch file; the [generated composition graph](../../../apps/cli/composition.md) renders it.
+
+## Model Experience
+
+Indirectly, through the inserted rows: this bundle selects the shipped persona-less prompt base, tool set, and DeepSeek adapter that mode bundles specialize, and contributes no model-visible text of its own.
+
+#### KV Cache effect
+
+None directly; each inserted row's package owns its effect.
+
+## Known Limitations and Deferred Work
+
+- **A patch replaces whole row configs** — profile overrides must restate every field a row keeps; there is no deep-merge layer.

packages/bundle/base/README.zh.md

@@ -0,0 +1,19 @@
+# `@deepseek-ai/dsh-base`
+
+[English](README.md) | 中文
+
+以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
+
+行集合及其设计依据以行内注释写在 patch 文件里；[生成的组合图](../../../apps/cli/composition.md)负责渲染它。
+
+## 模型体验
+
+通过插入的行间接产生影响：该组合包选定了随发行版交付的无 persona 提示词基座、工具集合与 DeepSeek 适配器，供各模式组合包进一步特化；它自身不贡献任何模型可见文本。
+
+#### KV Cache 影响
+
+无直接影响；每条插入行的影响归其所属的包负责。
+
+## 已知限制与延期工作
+
+- **patch 会替换整行 `config`**：profile 覆盖必须重述该行需要保留的每个字段；不存在深度合并层。

packages/bundle/base/cordis.patch.yml

@@ -0,0 +1,404 @@
+# The dsh-base bundle patch: the shared core of every dsh profile, applied as
+# ONE insert over the empty profile root. Later bundle patches and the user's
+# profile cordis.patch.yml address these rows by id, with the last write
+# winning per row.
+#
+# A patch replaces the targeted row's whole `config` rather than merging into
+# it, so a row whose value differs by mode does NOT live here: it belongs to
+# each mode bundle, keeping any single row down to one bundle layer plus the
+# user's. Mode-specific rows appear below only with shared plugin identity and
+# neutral defaults; each mode bundle restates its complete configuration.
+#
+# Row order carries no load semantics (activation is service-availability
+# driven); the grouping is for readers.
+
+- insert:
+    - id: timer
+      name: '@cordisjs/plugin-timer'
+
+    - id: hmr
+      name: '@cordisjs/plugin-hmr'
+      config:
+        root: ['.']
+
+    # The profile's cordis.patch.yml replaces this row's config to select exact GitHub
+    # repository Plugin generations. The app registers the DSH-owned runtime even
+    # when the list is empty so a later personal-config edit can load
+    # transactionally; one-shot headless runs consume the startup value only.
+    - id: repository-plugins
+      name: '@deepseek-ai/dsh-repository-plugin'
+
+    - id: llm
+      name: '@deepseek-ai/dsh-llm'
+
+    - id: session
+      name: '@deepseek-ai/dsh-session'
+
+    - id: session-title
+      name: '@deepseek-ai/dsh-session-title'
+      config:
+        fallbackMaxWords: 5
+        fallbackMaxBytes: 40
+        maxTitleBytes: 80
+
+    - id: session-title-llm
+      name: '@deepseek-ai/dsh-session-title-first-message-llm'
+      config:
+        targetWords: 5
+        targetCjkCharacters: 10
+        maxInputBytes: 4096
+        maxOutputTokens: 64
+        timeoutMs: 60000
+
+    - id: user-interaction
+      name: '@deepseek-ai/dsh-user-interaction'
+
+    - id: agent
+      name: '@deepseek-ai/dsh-agent'
+
+    - id: tasks
+      name: '@deepseek-ai/dsh-tasks-local'
+
+    - id: llm-retry
+      name: '@deepseek-ai/dsh-llm-retry'
+
+    # User-settings document (`$DSH_HOME/settings.yaml`, hot-reloaded): a
+    # `llm-deepseek:` or `llm-pi-ai:` section there overrides the adapter entries
+    # below without a restart, and is what the web Models page writes.
+    - id: settings
+      name: '@deepseek-ai/dsh-settings-local'
+
+    # Credential store: the live process environment over `$DSH_HOME/.env`
+    # (owner-only file, hot-reloaded). Adapters resolve their key references
+    # through it at each request, so no key is inlined in this file. The web
+    # Models page's key inputs write it through `credentials.set`; nothing hoists
+    # the document into the process environment, which would make every stored key
+    # read as an unrotatable ambient override.
+    - id: credentials
+      name: '@deepseek-ai/dsh-credentials-local'
+
+    # The pi-ai multi-provider twin, mounted dormant: zero routes (and no extra
+    # models in the picker) until a `llm-pi-ai:` settings section supplies provider
+    # profiles — then those routes register live, keys resolving per request
+    # through their apiKeyEnv references, and drop again when the section empties.
+    # Supplying those profiles is exactly what the web Models page does. Which
+    # adapters exist is composition; which providers run is the user's settings
+    # document.
+    - id: llm-pi-ai
+      name: '@deepseek-ai/dsh-llm-pi-ai'
+
+    - id: session-persistence-jsonl
+      name: '@deepseek-ai/dsh-session-persistence-jsonl'
+      config:
+        root: !!js dshHomePath('sessions')
+
+    # Raw configs can supply a process-local path or disable this shared session
+    # capability. The neutral default is process-local and opens only when used.
+    - id: session-query-sqlite
+      name: '@deepseek-ai/dsh-session-query-sqlite'
+      config:
+        path: ':memory:'
+        openAt: first-search
+
+    # Session telemetry, on for every dsh mode: mirrors every session-log
+    # event (assistant/chunk projected to first-of-step) plus ops markers onto
+    # OTLP/HTTP log records, streaming on the batch processor's cadence
+    # (10s/batch here) — not at exit; a crash loses at most the last unexported
+    # interval. No telemetry/record redaction rule is mounted yet, so exports
+    # are the raw captured copy; the deployment stance, env seams, and
+    # follow-ups are pinned in the web-telemetry-default-mount Agent Note.
+    # DSH_TELEMETRY_OTLP_URL overrides the production endpoint, and a non-empty
+    # DSH_TELEMETRY_DISABLED — any value, including '0'/'false' — opts the
+    # process out (the launchers patch the row disabled; config cannot disable
+    # a row). Exports carry the harness home's anonymous user id ($DSH_HOME/.userid,
+    # random UUID; delete the file to reset the identity) as the Resource's
+    # user.id. The exporter/processor values normally bound the shutdown drain
+    # to ~1s against an unreachable collector: exporter.timeoutMillis is both
+    # the per-attempt socket timeout and the retry deadline (1s effectively
+    # disables the SDK's 5-try backoff), while maxExportBatchSize == maxQueueSize
+    # (both explicit) makes the drain a single batch. The SDK awaits
+    # exporter.forceFlush() outside exportTimeoutMillis, so the backend's 3s
+    # shutdownTimeoutMillis is the load-bearing outer bound when a transport
+    # promise never settles. Every CLI exit path drains it by disposing the root
+    # on SIGINT/SIGTERM.
+    - id: telemetry-otel
+      name: '@deepseek-ai/dsh-session-telemetry-otel'
+      config:
+        shutdownTimeoutMillis: 3000
+        exporter:
+          url: !!js process.env.DSH_TELEMETRY_OTLP_URL ?? 'https://harness-telemetry.deepseeksvc.com/v1/logs'
+          compression: gzip
+          timeoutMillis: 1000
+        processor:
+          scheduledDelayMillis: 10000
+          maxQueueSize: 2048
+          maxExportBatchSize: 2048
+          exportTimeoutMillis: 1500
+
+    - id: subprocess
+      name: '@deepseek-ai/dsh-subprocess-local'
+
+    # Every shipped CLI mode starts with the same file-effect boundary.
+    # The environment remains an explicit deployment override; otherwise fresh
+    # sessions pin workspace-write + ask through the permission service below.
+    - id: sandbox
+      name: '@deepseek-ai/dsh-sandbox-local'
+
+    - id: sandbox-policy
+      name: '@deepseek-ai/dsh-sandbox-policy'
+      config:
+        mode: !!js process.env.DSH_PERMISSION_MODE ?? 'workspace-write'
+        workspaceRoot: !!js process.cwd()
+
+    - id: bash-sandbox
+      name: '@deepseek-ai/dsh-bash-sandbox'
+      config:
+        timeoutMs: 60000
+
+    - id: approval
+      name: '@deepseek-ai/dsh-user-approval'
+      config:
+        policy: !!js "(process.env.DSH_PERMISSION_MODE ?? 'workspace-write') === 'danger-full-access' ? 'never' : 'ask'"
+
+    - id: permission
+      name: '@deepseek-ai/dsh-permission'
+      config:
+        presets:
+          read-only:
+            sandbox: read-only
+            approval: ask
+          workspace-write:
+            sandbox: workspace-write
+            approval: ask
+          danger-full-access:
+            sandbox: danger-full-access
+            approval: never
+
+    - id: bash-env
+      name: '@deepseek-ai/dsh-bash-env'
+
+    - id: tool-bash
+      name: '@deepseek-ai/dsh-tool-bash'
+
+    - id: tool-tasks
+      name: '@deepseek-ai/dsh-tool-tasks'
+
+    - id: fs-policy
+      name: '@deepseek-ai/dsh-fs-policy'
+
+    - id: tool-fs
+      name: '@deepseek-ai/dsh-tool-fs'
+
+    - id: tool-fs-search
+      name: '@deepseek-ai/dsh-tool-fs-search'
+      config:
+        sampleOverCapGlobResults: false
+
+    - id: workspace-context
+      name: '@deepseek-ai/dsh-workspace-context'
+      config:
+        maxBytes: 65536
+
+    - id: skill
+      name: '@deepseek-ai/dsh-skill'
+
+    - id: skill-local
+      name: '@deepseek-ai/dsh-skill-local'
+
+    - id: tool-skill
+      name: '@deepseek-ai/dsh-tool-skill'
+
+    - id: commands
+      name: '@deepseek-ai/dsh-commands'
+
+    - id: goal
+      name: '@deepseek-ai/dsh-goal'
+
+    - id: goal-session
+      name: '@deepseek-ai/dsh-goal-session'
+
+    - id: command-goal
+      name: '@deepseek-ai/dsh-command-goal'
+
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed only to keep the request shape stable. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+    - id: token-meter
+      name: '@deepseek-ai/dsh-token-meter'
+
+    - id: compact-basic
+      name: '@deepseek-ai/dsh-compact-basic'
+
+    # Human `/compact`: one useful reduction below the automatic threshold. Backend
+    # independent, so it follows whichever compaction service this leaf mounts.
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: subagent
+      name: '@deepseek-ai/dsh-subagent'
+
+    - id: subagent-spawn
+      name: '@deepseek-ai/dsh-subagent-spawn'
+      config:
+        providerName: spawn
+
+    - id: subagent-fork
+      name: '@deepseek-ai/dsh-subagent-fork'
+      config:
+        providerName: fork
+
+    # Continuable background children are selected per delegation tool. The
+    # separately loaded follow-up tool registers the one global `send_message`.
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    # Optional direct-child return channel; absent from roots and one-shot agents.
+    - id: tool-subagent-report
+      name: '@deepseek-ai/dsh-tool-subagent-report'
+
+    - id: workflow-workerthread
+      name: '@deepseek-ai/dsh-workflow-workerthread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: timeout-policy
+      name: '@deepseek-ai/dsh-timeout-policy'
+
+    - id: spill-local
+      name: '@deepseek-ai/dsh-spill-local'
+
+    - id: spill-policy
+      name: '@deepseek-ai/dsh-spill-policy'
+      config:
+        maxInlineBytes: 50000
+
+    # Durability checkpoints before each model request and top-level dispatch.
+    - id: session-checkpoint-policy
+      name: '@deepseek-ai/dsh-session-checkpoint-policy'
+
+    # Compacts oversized tool results before the broader conversation compactor
+    # runs, preserving the model-visible result within the configured budget.
+    - id: tool-result-prune
+      name: '@deepseek-ai/dsh-compact-tool-result-prune'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+    - id: tool-todo
+      name: '@deepseek-ai/dsh-tool-todo'
+
+    # Persisted same-session goals reach the model and the slash menu here; the
+    # domain, driver, and `/goal` command are above.
+    - id: tool-goal
+      name: '@deepseek-ai/dsh-tool-goal'
+
+    # Fresh-agent Ralph iteration over a build-time-fixed script.
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+    - id: tool-str-replace-editor
+      name: '@deepseek-ai/dsh-tool-str-replace-editor'
+      config:
+        maxOutputChars: 16000
+
+    # Consecutive-repeat reminders on the tool chain.
+    - id: repeat-tool-guard
+      name: '@deepseek-ai/dsh-repeat-tool-guard'
+      config:
+        thresholds: [3, 5, 8]
+        argumentsPreviewChars: 500
+
+    # Every mode enables the stable web_search model surface. DeepSeek search
+    # resolves the same DEEPSEEK_API_KEY credential the Models page manages for
+    # chat, at each search; its Messages endpoint is separate from the
+    # chat-completions endpoint, so it takes its own base-URL override. Fetch stays
+    # disabled and no fetch provider is mounted: that provider defers SSRF
+    # protection and the model would choose the request target. Search is a full
+    # auxiliary model request with server-side retrieval, so this shipped DeepSeek
+    # route gets 60s while the provider-neutral tool default remains 30s.
+    - id: web
+      name: '@deepseek-ai/dsh-web'
+      config:
+        searchProvider: deepseek-official
+
+    - id: web-search-deepseek
+      name: '@deepseek-ai/dsh-web-search-deepseek'
+      config:
+        apiKeyEnv: DEEPSEEK_API_KEY
+        baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
+
+    - id: tool-web
+      name: '@deepseek-ai/dsh-tool-web'
+      config:
+        fetch: false
+        searchTimeoutMs: 60000
+
+    # ── rows every mode mounts, whose values each overlay may state ──────────────
+
+    # The tool registry. Presentation mode is a deployment choice; omitting it here
+    # keeps the schema default (native).
+    - id: tools
+      name: '@deepseek-ai/dsh-tools'
+
+    # The deployment persona is a deployment choice; plan-mode and tool plugins own
+    # their own prompt sections.
+    - id: system-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      config:
+        persona: ''
+
+    # Agents created at startup. The base stays empty; raw overlays may create
+    # agents, while Web creates sessions on client request.
+    - id: agent-loop
+      name: '@deepseek-ai/dsh-agent-loop'
+      config:
+        agents: []
+
+    # The sandboxed filesystem provider. `cwd` defaults to `process.cwd()`; an
+    # overlay can pin another workspace.
+    - id: fs-sandbox
+      name: '@deepseek-ai/dsh-fs-sandbox'
+
+    # The native DeepSeek adapter. No key or endpoint is inlined: both resolve per
+    # request from the `llm-deepseek:` settings section over this entry, with the
+    # key coming from the credential store below. Thinking defaults are a deployment
+    # choice.
+    - id: llm-deepseek
+      name: '@deepseek-ai/dsh-llm-deepseek'

packages/bundle/base/package.json

@@ -0,0 +1,111 @@
+{
+  "name": "@deepseek-ai/dsh-base",
+  "description": "The shared dsh core as a profile bundle: every profile's first patch layer, inserting the base plugin rows over the empty profile root",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@cordisjs/plugin-hmr": "workspace:*",
+    "@cordisjs/plugin-timer": "workspace:*",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
+    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-command-compact": "workspace:^",
+    "@deepseek-ai/dsh-command-goal": "workspace:^",
+    "@deepseek-ai/dsh-commands": "workspace:^",
+    "@deepseek-ai/dsh-compact-basic": "workspace:^",
+    "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
+    "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-fs-policy": "workspace:^",
+    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-goal-session": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
+    "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-permission": "workspace:^",
+    "@deepseek-ai/dsh-plan-mode": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
+    "@deepseek-ai/dsh-repository-plugin": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
+    "@deepseek-ai/dsh-session-telemetry-otel": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-title-first-message-llm": "workspace:^",
+    "@deepseek-ai/dsh-settings-local": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-local": "workspace:^",
+    "@deepseek-ai/dsh-spill-policy": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tasks-local": "workspace:^",
+    "@deepseek-ai/dsh-timeout-policy": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
+    "@deepseek-ai/dsh-tool-goal": "workspace:^",
+    "@deepseek-ai/dsh-tool-ralph": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent-control": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent-report": "workspace:^",
+    "@deepseek-ai/dsh-tool-tasks": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@deepseek-ai/dsh-user-interaction": "workspace:^",
+    "@deepseek-ai/dsh-web": "workspace:^",
+    "@deepseek-ai/dsh-web-search-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-workflow-workerthread": "workspace:^",
+    "@deepseek-ai/dsh-workspace-context": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/bundle/base/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @deepseek-ai/dsh-base — the shared dsh core as a profile bundle. The
+ * package's substance is `cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field and resolved by the profile composer through that field;
+ * this module carries no runtime API.
+ * @module @deepseek-ai/dsh-base
+ */
+
+export {}

packages/bundle/base/src/invariant.ts

@@ -0,0 +1,28 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-base`.
+ * @module @deepseek-ai/dsh-base/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-base'
+
+/** Cordis companion plugin name. */
+export const name = 'base-bundle-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+// No runtime invariant: the package is a static patch-list carrier (a YAML
+// document of loader rows owned by other packages); it mounts no service,
+// emits no events, and owns no mutable relation to check. Each inserted row's
+// own package carries that row's invariants.
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/bundle/base/tests/base.spec.ts

@@ -0,0 +1,25 @@
+/**
+ * The bundle's substance is its patch file: the `dsh.bundle.patch` manifest
+ * field must name a real, parseable patch list.
+ */
+
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import * as yaml from 'js-yaml'
+import { entryListSchema } from '@cordisjs/plugin-include'
+
+describe('dsh-base bundle', () => {
+  it('declares a parseable patch list through the dsh.bundle.patch manifest field', () => {
+    const root = fileURLToPath(new URL('..', import.meta.url))
+    const manifest = JSON.parse(readFileSync(resolve(root, 'package.json'), 'utf8')) as { dsh?: { bundle?: { patch?: string } } }
+    expect(manifest.dsh?.bundle?.patch).toBe('./cordis.patch.yml')
+    const parsed = yaml.load(readFileSync(resolve(root, manifest.dsh!.bundle!.patch!), 'utf8'), { schema: entryListSchema })
+    expect(Array.isArray(parsed)).toBe(true)
+    // The base layer is one insert list over the empty profile root.
+    const rows = (parsed as { insert?: { id?: string }[] }[]).flatMap(patch => patch.insert ?? [])
+    expect(rows.length).toBeGreaterThan(50)
+    expect(rows.some(row => row.id === 'agent-loop')).toBe(true)
+  })
+})

packages/bundle/base/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/bundle/headless/README.i18n.yaml

@@ -0,0 +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 packages/bundle/headless/README.md
+README.md: d08fb08e2aca3c4e5ccd733b37fc415d492974ca
+README.zh.md: 99a64ef04c4fd8fb0c6a979d3f09f1bd98b434a0

packages/bundle/headless/README.md

@@ -0,0 +1,18 @@
+# `@deepseek-ai/dsh-headless`
+
+English | [中文](README.zh.md)
+
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh --profile headless "task"`), and fails loud when a task is given to a profile without this row.
+
+## Model Experience
+
+None, as the runner submits the task as an ordinary user message over the shared composition; prompts and tools belong to the base/web bundles.
+
+#### KV Cache effect
+
+None; the runner adds nothing to the request prefix.
+
+## Known Limitations and Deferred Work
+
+- **One turn only** — the runner anchors on the first message-triggered turn and exits at its end; queued follow-ups and multi-turn tasks are out of scope.
+- **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.

packages/bundle/headless/README.zh.md

@@ -0,0 +1,18 @@
+# `@deepseek-ai/dsh-headless`
+
+[English](README.md) | 中文
+
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，聚合该轮次最终的 assistant 文本，写到 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh --profile headless "task"`）；如果向没有这一行的 profile 传入任务，则大声失败。
+
+## 模型体验
+
+无。runner 把任务作为普通用户消息经共享组合提交；提示词与工具归 base／web 组合包所有。
+
+#### KV Cache 影响
+
+无；runner 不向请求前缀添加任何内容。
+
+## 已知限制与延期工作
+
+- **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
+- **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时大声失败，直到宿主提供该 seam。

packages/bundle/headless/cordis.patch.yml

@@ -0,0 +1,21 @@
+# The dsh-headless bundle patch: one-shot task mode over dsh-base +
+# dsh-web-app. The web composition stays mounted (the session is observable
+# in a browser while it runs); this layer silences the URL line and the
+# GUI-orientation surface context (this user is not in the GUI), moves the
+# webserver to an OS-assigned port so parallel headless runs never collide,
+# and mounts the one-shot runner. The launcher patches the runner's `task`.
+
+- id: webserver
+  config:
+    host: 127.0.0.1
+    port: 0
+
+- id: web-runtime
+  config:
+    mode: production
+    printUrl: false
+    surfaceContext: false
+
+- insert:
+    - id: headless-runner
+      name: '@deepseek-ai/dsh-headless'

packages/bundle/headless/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@deepseek-ai/dsh-headless",
+  "description": "The dsh one-shot bundle: a patch layer over dsh-base + dsh-web-app plus the runner plugin driving one task turn through the in-process API carrier",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/bundle/headless/src/index.ts

@@ -0,0 +1,173 @@
+/**
+ * @deepseek-ai/dsh-headless — the one-shot headless bundle: the bundle patch
+ * (`cordis.patch.yml`) rides over dsh-base + dsh-web-app (the headless
+ * session is web-observable while it runs — same composition), and this
+ * runner plugin drives one task through the in-process API carrier
+ * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
+ * chain — serialization, zod, SSE framing — really runs), prints the final
+ * assistant text at agent quiescence, and exits (completed → 0, else 1). The
+ * task text arrives as launcher-patched config
+ * (`dsh --profile headless "task"`).
+ * @module @deepseek-ai/dsh-headless
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
+// Empty type imports carry the httpServer and agent/status Context merges used below.
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-agent'
+// Empty type import carries the loader Context merge for the settlement await.
+import type {} from '@cordisjs/plugin-loader'
+import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+
+/** Stable Cordis plugin name. */
+export const name = 'headless-runner'
+
+/** Services required before the one-shot turn can start. */
+export const inject = ['apiProxy', 'httpServer']
+
+/** Plugin config: the task, patched in by the launcher. */
+export interface Config {
+  /** The prompt text for the single turn. */
+  task: string
+}
+
+export const Config: z<Config> = z.object({
+  task: z.string().required(),
+})
+
+/** Outcome of one headless run: aggregated final text plus the last turn-end reason kind. */
+interface TurnOutcome {
+  text: string
+  reason: string
+}
+
+/**
+ * The process-facing effects of one run, injectable for tests: output
+ * streams and the exit request (the launcher wires it to its bounded
+ * shutdown controller).
+ */
+export interface HeadlessIo {
+  stdout: { write(chunk: string): unknown }
+  stderr: { write(chunk: string): unknown }
+  /** Request process exit with `code` after the tree disposes. */
+  exit(code: number): void
+}
+
+/** Host seam: the launcher provides the exit wiring before the tree mounts. */
+declare module 'cordis' {
+  interface Context {
+    /** Process-facing effects for the one-shot headless runner. */
+    headlessIo?: HeadlessIo
+  }
+}
+
+/** Unwrap an RpcResponse or fail loud: business errors print and exit 1. */
+async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
+  if (response.result.ok) return response.result.value
+  const { code, message } = response.result.error
+  io.stderr.write(`dsh: ${code}: ${message}\n`)
+  io.exit(1)
+  // Exit is asynchronous (bounded tree disposal); park this turn forever so
+  // no further request rides a session that is already being torn down.
+  return new Promise<never>(() => {})
+}
+
+/**
+ * Consume mux frames until the agent reaches idle, per the one-shot CLI
+ * idle-to-idle contract: the stream opens immediately before the prompt, and
+ * its first observed turn/start begins the task. Text is the last committed
+ * assistant message of the whole interval (steering or injected work may run
+ * further turns before quiescence), and the outcome reason is the final
+ * turn/end's kind. Idleness is signalled out of band by the caller's
+ * `agent/status` subscription; the stream itself carries no status frame.
+ * @param frames - the mux stream opened before the prompt.
+ * @param sessionId - the headless session.
+ * @param idle - resolves when the agent reaches quiescence.
+ * @param io - process-facing effects for stream diagnostics.
+ * @returns the aggregated outcome.
+ */
+async function consumeUntilIdle(
+  frames: AsyncIterable<RpcRequest<MuxFrame>>,
+  sessionId: SessionId,
+  idle: Promise<void>,
+  io: HeadlessIo,
+): Promise<TurnOutcome> {
+  let started = false
+  let text = ''
+  let reason: string = 'error'
+  void (async () => {
+    try {
+      for await (const frame of frames) {
+        const payload = frame.payload
+        if (payload.type === 'stream/error') return
+        if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
+        const event = payload.event
+        if (event.type === 'turn/start') {
+          started = true
+          continue
+        }
+        if (!started) continue
+        if (event.type === 'assistant/message') {
+          const joined = event.data.message.content.filter(block => block.type === 'text').map(block => block.text).join('')
+          if (joined !== '') text = joined
+        }
+        if (event.type === 'turn/end') reason = event.data.reason.kind
+      }
+    } catch (error: unknown) {
+      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
+    }
+  })()
+  await idle
+  return { text, reason }
+}
+
+/**
+ * Run one headless task to quiescence and request exit (completed → 0, else 1).
+ * @param ctx - plugin context carrying apiProxy, httpServer, and the launcher's headlessIo.
+ * @param config - validated {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const io = ctx.headlessIo
+  if (io === undefined) {
+    throw new Error('headless-runner: the launcher must provide ctx.headlessIo before the tree mounts')
+  }
+  // Fire-and-forget by design: the run outlives plugin activation, and every
+  // failure path inside ends in io.exit, not a rejection.
+  void (async () => {
+    // The Loader mounts sibling rows concurrently and this plugin's inject
+    // gate covers only apiProxy/httpServer; prompting before the agent loop,
+    // adapters, and tools settle would fail the turn on a half-mounted tree.
+    // The old launcher ran strictly after settled boot — preserve that.
+    // A tree disposed mid-settlement (early SIGTERM) has nothing to run.
+    await ctx.get('loader')?.await()
+    if (ctx.get('httpServer') === undefined) return
+    // The headless session is web-observable while it runs (same composition).
+    io.stderr.write(`dsh: observing at http://127.0.0.1:${String(ctx.httpServer.port)}\n`)
+    const api = new InProcessApiClient(toFetchHandler(ctx.apiProxy))
+    const created = await unwrap(await api.sessions.create({}), io)
+    // Open the stream before prompting so no frame is lost. The quiescence
+    // anchor below is an in-process ctx subscription, so a remote-carrier
+    // port of this runner must replace it with a wire-visible idle signal.
+    const abort = new AbortController()
+    const frames = api.events.mux({}, abort.signal)
+    const idle = new Promise<void>((resolve) => {
+      ctx.on('agent/status', ({ agent, status }) => {
+        if (agent.id === created.sessionId && status === 'idle') resolve()
+      })
+    })
+    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
+    await unwrap(await api.sessions.prompt({
+      sessionId: created.sessionId,
+      mode: 'queue',
+      content: [{ type: 'text', text: config.task }],
+    }), io)
+    const outcome = await done
+    io.stdout.write(outcome.text + '\n')
+    abort.abort()
+    io.exit(outcome.reason === 'completed' ? 0 : 1)
+  })()
+}

packages/bundle/headless/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-headless`.
+ * @module @deepseek-ai/dsh-headless/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-headless'
+
+/** Cordis companion plugin name. */
+export const name = 'headless-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the runner is a one-shot driver over the API carrier
+ * whose observable contract (final text on stdout, exit code by turn-end
+ * reason) is process-level and owned by the launcher e2e; it registers
+ * nothing and holds no mutable relation to audit inside the tree.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/bundle/headless/tests/headless.spec.ts

@@ -0,0 +1,218 @@
+/**
+ * One-shot runner behavior over a scripted in-process API: idle-to-idle
+ * aggregation (last text of the whole interval), exit-code mapping by the
+ * final turn-end reason, stream-error and RPC-error paths, and the
+ * launcher-owned `ctx.headlessIo` requirement.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { apply, Config, type HeadlessIo } from '../src/index.ts'
+
+interface ScriptedEvent { type: string; seq?: number; time?: number; sessionId?: string; data: Record<string, unknown> }
+
+let nextSeq = 0
+/** Stamp the envelope fields the wire schema requires. */
+function stamped(event: ScriptedEvent): ScriptedEvent {
+  nextSeq += 1
+  return { seq: nextSeq, time: nextSeq, ...event }
+}
+
+interface RpcShapedRequest { rpcId: string }
+
+/** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
+function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): unknown {
+  return {
+    sessions: {
+      create: (request: RpcShapedRequest) =>
+        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
+      prompt: (request: RpcShapedRequest) => Promise.resolve(options.promptFails === true
+        // A code from the closed wire union: the carrier schema rejects invented codes.
+        ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
+        : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+    },
+    events: {
+      mux: async function* () {
+        for (const event of events) {
+          if (event.type === 'stream/error') {
+            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
+            continue
+          }
+          const { sessionId = 'S1', ...rest } = event
+          yield { rpcId: 'e', payload: { type: 'session/event', sessionId, event: stamped(rest) } }
+        }
+      },
+    },
+  }
+}
+
+/**
+ * Mount the runner against a scripted API, emit the idle transition after the
+ * scripted frames drain, and wait for its exit request.
+ */
+async function run(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): Promise<{ code: number; out: string; err: string }> {
+  const ctx = new Context()
+  let out = ''
+  let err = ''
+  const exited = new Promise<number>((resolve) => {
+    const io: HeadlessIo = {
+      stdout: { write: (chunk: string) => { out += chunk; return true } },
+      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      exit: resolve,
+    }
+    ctx.provide('headlessIo', io)
+  })
+  ctx.provide('apiProxy', scriptedApi(events, options) as never)
+  ctx.provide('httpServer', { port: 12345 } as never)
+  apply(ctx, { task: 'do the thing' })
+  // Quiescence is out of band: give the scripted stream a beat to drain, then
+  // flip the agent idle exactly as the loop would. Foreign agents and
+  // non-idle transitions must not settle the run.
+  await new Promise(resolve => setTimeout(resolve, 10))
+  ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
+  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
+  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+  const code = await exited
+  await ctx.fiber.dispose()
+  return { code, out, err }
+}
+
+const startupTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 0, trigger: { kind: 'startup' } } }
+const messageTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } }
+const text = (turn: number, value: string): ScriptedEvent => ({
+  type: 'assistant/message',
+  data: { turn, message: { content: [{ type: 'text', text: value }] } },
+})
+const end = (turn: number, reason: string): ScriptedEvent => ({ type: 'turn/end', data: { turn, reason: { kind: reason } } })
+
+describe('headless runner', () => {
+  it('aggregates to quiescence: last text wins across turns, final turn-end reason maps to exit 0', async () => {
+    const { code, out, err } = await run([
+      // Frames before the first turn/start are outside the task interval.
+      { type: 'assistant/message', data: { turn: 0, message: { content: [{ type: 'text', text: 'pre-task noise' }] } } },
+      startupTurn,
+      // Off-session, non-text, and text-empty frames never affect the aggregate.
+      { type: 'assistant/message', sessionId: 'OTHER', data: { turn: 1, message: { content: [{ type: 'text', text: 'other session' }] } } },
+      { type: 'assistant/message', data: { turn: 1, message: { content: [{ type: 'tool_call', text: 'ignored' }] } } },
+      text(0, 'draft'),
+      end(0, 'completed'),
+      messageTurn,
+      text(1, 'final answer'),
+      end(1, 'completed'),
+    ])
+    expect(code).toBe(0)
+    expect(out).toBe('final answer\n')
+    expect(err).toContain('observing at http://127.0.0.1:12345')
+  })
+
+  it('exits 1 when the final turn ends for any other reason', async () => {
+    const { code } = await run([messageTurn, end(1, 'aborted')])
+    expect(code).toBe(1)
+  })
+
+  it('exits 1 when no turn ever starts (idle without work)', async () => {
+    const { code, out } = await run([])
+    expect(code).toBe(1)
+    expect(out).toBe('\n')
+  })
+
+  it('keeps the error outcome after a stream error ends the frame consumer early', async () => {
+    const { code } = await run([messageTurn, { type: 'stream/error', data: {} }, end(1, 'completed')])
+    // The consumer stopped at the stream error; the completed turn-end after
+    // it is never observed, so the reason stays 'error'.
+    expect(code).toBe(1)
+  })
+
+  it('prints an RPC business error and exits 1 without waiting for idle', async () => {
+    const ctx = new Context()
+    let err = ''
+    const exited = new Promise<number>((resolve) => {
+      ctx.provide('headlessIo', {
+        stdout: { write: () => true },
+        stderr: { write: (chunk: string) => { err += chunk; return true } },
+        exit: resolve,
+      } satisfies HeadlessIo)
+    })
+    ctx.provide('apiProxy', scriptedApi([messageTurn, end(1, 'completed')], { promptFails: true }) as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    apply(ctx, { task: 't' })
+    expect(await exited).toBe(1)
+    expect(err).toContain('agent-busy')
+    await ctx.fiber.dispose()
+  })
+
+  it('reports the stream-failed diagnostic when the event channel dies, still settling at idle', async () => {
+    const ctx = new Context()
+    let err = ''
+    const exited = new Promise<number>((resolve) => {
+      ctx.provide('headlessIo', {
+        stdout: { write: () => true },
+        stderr: { write: (chunk: string) => { err += chunk; return true } },
+        exit: resolve,
+      } satisfies HeadlessIo)
+    })
+    ctx.provide('apiProxy', {
+      sessions: {
+        create: (request: RpcShapedRequest) =>
+          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
+        prompt: (request: RpcShapedRequest) =>
+          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+      },
+      events: {
+        // Synchronous throw: the SSE response never forms, so the client-side
+        // iterable rejects — the runner's own catch path, not a carrier frame.
+        mux: () => { throw new Error('channel exploded') },
+      },
+    } as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    apply(ctx, { task: 't' })
+    await new Promise(resolve => setTimeout(resolve, 10))
+    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+    expect(await exited).toBe(1)
+    expect(err).toContain('event stream failed')
+    await ctx.fiber.dispose()
+  })
+
+  it('waits for Loader settlement and abandons the run when the tree died during it', async () => {
+    const ctx = new Context()
+    let err = ''
+    let exited = false
+    ctx.provide('headlessIo', {
+      stdout: { write: () => true },
+      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      exit: () => { exited = true },
+    } satisfies HeadlessIo)
+    ctx.provide('apiProxy', scriptedApi([]) as never)
+    // The webserver is provided by a child fiber whose disposal (early
+    // SIGTERM during the boot window) removes the service; settlement
+    // resolves only afterwards, and the runner must abandon rather than
+    // crash on the torn-down port read.
+    const webserverFiber = ctx.plugin((childCtx: Context) => {
+      childCtx.provide('httpServer', { port: 1 } as never)
+    })
+    await webserverFiber
+    let release: () => void
+    const settlement = new Promise<void>((resolve) => { release = resolve })
+    ctx.provide('loader', { await: () => settlement } as never)
+    apply(ctx, { task: 't' })
+    await webserverFiber.dispose()
+    release!()
+    await new Promise(resolve => setTimeout(resolve, 10))
+    expect(err).toBe('')
+    expect(exited).toBe(false)
+    await ctx.fiber.dispose()
+  })
+
+  it('fails loud without the launcher-owned headlessIo seam', () => {
+    const ctx = new Context()
+    ctx.provide('apiProxy', scriptedApi([]) as never)
+    ctx.provide('httpServer', { port: 1 } as never)
+    expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.headlessIo')
+  })
+
+  it('validates config: the task is required', () => {
+    expect(() => new Config({ } as never)).toThrow()
+    expect(new Config({ task: 'x' })).toEqual({ task: 'x' })
+  })
+})

packages/bundle/headless/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../host/apiproxy"
+    },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/bundle/web-app/README.i18n.yaml

@@ -0,0 +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 packages/bundle/web-app/README.md
+README.md: 95cdbc9694b44539742e5b871157eefa7cb4c290
+README.zh.md: b8d6e9d80bac82a7798cc07d3a34c01d219f2174

packages/bundle/web-app/README.md

@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+English | [中文](README.zh.md)
+
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection, storage) and the browser plugin roster, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses`/`printUrl` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top and silences the URL line.
+
+## Model Experience
+
+### Web-surface prompt section and bash runtime variables
+
+#### What the model sees
+
+The `app:web-surface` global section (order −98) orients the model to the GUI: the canonical local URL, the "this page" referent, the HMR/rebuild update contract for the active mode, and the instruction not to start replacement servers. `DSH_WEB_URL` and `DSH_WEB_MODE` additionally appear in the managed bash environment with their descriptions, resolved per invocation from the live server.
+
+#### Token effect
+
+One prompt paragraph per session plus two managed-environment variable lines; constant per process.
+
+#### KV Cache effect
+
+The prompt section sits near the system prompt's head and is stable for the life of the process (port and mode are boot facts), so it does not invalidate the cache across turns.
+
+## Known Limitations and Deferred Work
+
+- **The frontend dist must be built** — `require.resolve` of the dist fails loud at activation with a build hint; there is no source-serving fallback.
+- **`lanAddresses` is a boot-time snapshot** — interface changes after boot are not re-advertised; the printed LAN URL always matches the configured trust fence.

packages/bundle/web-app/README.zh.md

@@ -0,0 +1,26 @@
+# `@deepseek-ai/dsh-web-app`
+
+[English](README.md) | 中文
+
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses`／`printUrl` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层并关闭 URL 行。
+
+## 模型体验
+
+### Web 表层提示词段落与 bash 运行时变量
+
+#### 模型看到的内容
+
+全局段落 `app:web-surface`（顺序 −98）向模型说明 GUI：规范的本地 URL、「this page」指代什么、当前模式下 HMR（热模块替换）／重建的更新契约，以及不要启动替代服务器的指令。`DSH_WEB_URL` 与 `DSH_WEB_MODE` 还会连同各自描述出现在受管 bash 环境中，每次调用时从运行中的服务器解析。
+
+#### Token 影响
+
+每个会话一段提示词，外加两行受管环境变量；每个进程内保持恒定。
+
+#### KV Cache 影响
+
+该提示词段落位于系统提示词靠前位置，且在进程整个生命周期内稳定（端口与模式是启动期事实），因此不会使跨轮次缓存失效。
+
+## 已知限制与延期工作
+
+- **前端 dist 必须已构建**：对 dist 的 `require.resolve` 在激活时大声失败并给出构建提示；没有从源码直接服务的回退路径。
+- **`lanAddresses` 是启动期快照**：启动后的网卡变化不会重新公告；打印的 LAN URL 始终与配置的信任栅栏一致。

packages/bundle/web-app/cordis.patch.yml

@@ -0,0 +1,191 @@
+# The dsh-web-app bundle patch: the browser surface over the dsh-base layer.
+# Applied after dsh-base's insert; rows here override base rows by id, with
+# the profile's own cordis.patch.yml and any --patch overlays still to come.
+#
+# A patch replaces the targeted row's whole `config`, so each row below
+# restates every key it owns. The `dsh web` launcher alias turns --host/--port/
+# --dev/--workspace-root/--trusted-host into further patches over these rows
+# (`--dev` inserts the dsh-client-hmr row).
+
+# ── surface-specific values the base deliberately omits ─────────────────────
+
+- id: system-prompt
+  config:
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+# TODO: Re-enable shared HMR for Web after its reload lifecycle is tested.
+- id: hmr
+  disabled: true
+
+# Web content search runs on an ephemeral in-memory index. The service
+# activates at boot, while first-search defers the node:sqlite import and
+# in-memory handle so Node 22 startup stays quiet until content search
+# actually uses SQLite. That search then reconciles this boot's sources.
+- id: session-query-sqlite
+  config:
+    path: ':memory:'
+    openAt: first-search
+
+- id: tools
+  config:
+    # TEMPORARY workaround: DSH_TOOLS_MODE (native|code|both) opts a whole dsh
+    # process into Code Mode while per-session tool-mode selection is being
+    # designed; unset keeps the schema default (native). Remove the env seam
+    # once the web UI owns the choice per session.
+    mode: !!js process.env.DSH_TOOLS_MODE
+
+- id: llm-deepseek
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+
+# ── web-only host rows, the transport layer, and the browser roster ─────────
+
+# `dshClient` rows are the browser roster the modules node half scans into
+# window.__DSH_BOOT__; the modules row is simultaneously a host row.
+- insert:
+    - id: session-projection
+      name: '@deepseek-ai/dsh-session-projection'
+
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
+    - id: storage
+      name: '@deepseek-ai/dsh-storage'
+
+    - id: storage-json
+      name: '@deepseek-ai/dsh-storage-json'
+      config:
+        root: !!js dshHomePath('storages')
+
+    - id: storage-domain
+      name: '@deepseek-ai/dsh-storage-domain'
+      config:
+        backend: json
+
+    - id: workspace
+      name: '@deepseek-ai/dsh-workspace'
+
+    - id: session-projection-cache
+      name: '@deepseek-ai/dsh-session-projection-cache'
+      config:
+        writeEveryEvents: 200
+        writeIntervalMs: 5000
+
+    # Resolve bind host, SSH launch, and display once at boot, then mount the
+    # matching dual-face directory picker. Mount -native or -browse directly in
+    # an overlay to pin the interaction.
+    - id: directory-picker
+      name: '@deepseek-ai/dsh-host-directory-picker-auto'
+
+    # The API gateway: the transport-agnostic dispatch face every client shape
+    # shares. provider/model are the host default routing — the profile json's
+    # mapping target (user config overrides these engineering defaults).
+    - id: api-gateway
+      name: '@deepseek-ai/dsh-host-apiproxy'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+
+    # ── layer 2: transport/service ──────────────────────────────────────────────
+
+    # Plain route-registration carrier; host and port arrive as `dsh web`
+    # flag patches over these defaults. The dist is served by the web-runtime
+    # row below through the fallback seat.
+    - id: webserver
+      name: '@deepseek-ai/dsh-host-webserver'
+      config:
+        host: 127.0.0.1
+        port: 3080
+
+    # Web glue owned by this bundle: resolves the built frontend dist (an
+    # assembly fact of dsh-web-app, never user config), mounts the
+    # frontend-static fallback owner, registers the web-surface prompt
+    # section and bash runtime variables, and prints the URL line. `dsh web`
+    # patches mode/lanAddresses over these defaults.
+    - id: web-runtime
+      name: '@deepseek-ai/dsh-web-app'
+      config:
+        mode: production
+        printUrl: true
+
+    # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──
+
+    # Dual-face: node half scans this very tree for dshClient rows, composes
+    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
+    # module table the shell kernel constructs before cordis exists (§4.7 —
+    # adopted as a plugin entry by the kernel, never fetched).
+    - id: modules
+      name: '@deepseek-ai/dsh-client-modules'
+
+    # Owns both ends of the web transport: node half binds the gateway to the
+    # webserver under /api; browser half is the fetch/SSE client.
+    - id: connection
+      name: '@deepseek-ai/dsh-client-connection'
+
+    - id: client-runtime
+      name: '@deepseek-ai/dsh-client-runtime'
+
+    - id: ui-theme
+      name: '@deepseek-ai/dsh-client-ui-theme'
+
+    - id: locale
+      name: '@deepseek-ai/dsh-client-locale'
+
+    - id: ui-layout
+      name: '@deepseek-ai/dsh-client-ui-layout'
+
+    - id: ui-sidebar
+      name: '@deepseek-ai/dsh-client-ui-sidebar'
+
+    - id: ui-settings
+      name: '@deepseek-ai/dsh-client-ui-settings'
+
+    - id: ui-settings-general
+      name: '@deepseek-ai/dsh-client-ui-settings-general'
+
+    - id: ui-models
+      name: '@deepseek-ai/dsh-client-ui-models'
+
+    - id: ui-conversation
+      name: '@deepseek-ai/dsh-client-ui-conversation'
+
+
+    - id: ui-workspace
+      name: '@deepseek-ai/dsh-client-ui-workspace'
+
+    # Input triggers: the '/' | '@' pipeline (ui-slash), the command surface over
+    # it (ui-command), and the two reference sources (ui-skill / ui-subagent).
+    - id: ui-slash
+      name: '@deepseek-ai/dsh-client-ui-slash'
+
+    - id: ui-command
+      name: '@deepseek-ai/dsh-client-ui-command'
+
+    - id: ui-skill
+      name: '@deepseek-ai/dsh-client-ui-skill'
+
+    - id: ui-subagent
+      name: '@deepseek-ai/dsh-client-ui-subagent'
+
+    # Goal surface: GoalBar in the input dock over the goal session projection.
+    - id: ui-goal
+      name: '@deepseek-ai/dsh-client-ui-goal'
+
+    # Model selection: the /model popupSelect + composer seat over session.models.
+    - id: ui-model
+      name: '@deepseek-ai/dsh-client-ui-model'
+
+    - id: ui-permission
+      name: '@deepseek-ai/dsh-client-ui-permission'
+
+    # Plan control: the composer plan seat over the plan projection + /plan channel.
+    - id: ui-plan
+      name: '@deepseek-ai/dsh-client-ui-plan'
+
+    - id: ui-question
+      name: '@deepseek-ai/dsh-client-ui-question'
+
+    - id: ui-trajectory
+      name: '@deepseek-ai/dsh-client-ui-trajectory'

packages/bundle/web-app/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@deepseek-ai/dsh-web-app",
+  "description": "The dsh browser-surface bundle: the web patch layer over dsh-base plus the runtime glue plugin (frontend dist serving, web-surface prompt, bash runtime variables, URL line)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "cordis.patch.yml",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-hmr": "workspace:^",
+    "@deepseek-ai/dsh-client-locale": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-command": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-conversation": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-goal": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-layout": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-model": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-models": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-permission": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-plan": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-question": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-settings-general": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-sidebar": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-skill": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slash": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-subagent": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-theme": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+    "@deepseek-ai/dsh-frontend": "workspace:^",
+    "@deepseek-ai/dsh-frontend-static": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-auto": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-browse": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
+    "@deepseek-ai/dsh-storage": "workspace:^",
+    "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "@deepseek-ai/dsh-storage-json": "workspace:^",
+    "@deepseek-ai/dsh-workspace": "workspace:^",
+    "schemastery": "^3.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-bash-env": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/bundle/web-app/src/index.ts

@@ -0,0 +1,157 @@
+/**
+ * @deepseek-ai/dsh-web-app — the browser-surface bundle's runtime glue plugin
+ * plus the bundle patch (`cordis.patch.yml`, declared by the `dsh.bundle.patch`
+ * manifest field). The plugin owns what used to be launcher code: it resolves
+ * the built frontend dist (workspace knowledge of this bundle, never user
+ * config), mounts the `frontend-static` fallback owner over it, registers the
+ * web-surface prompt section and the bash-visible web runtime variables, and
+ * prints the URL line when configured to. Flag-derived values (`mode`,
+ * `lanAddresses`, `printUrl`) arrive as launcher patches over this row.
+ * @module @deepseek-ai/dsh-web-app
+ */
+
+import { createRequire } from 'node:module'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import * as FrontendStatic from '@deepseek-ai/dsh-frontend-static'
+import type {} from '@cordisjs/plugin-loader'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-bash-env'
+
+/** Stable Cordis plugin name. */
+export const name = 'web-app'
+
+/** Services required before the web runtime can mount. */
+export const inject = ['httpServer']
+
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development'
+
+/** Plugin config: the surface facts the launcher patches over this bundle's defaults. */
+export interface Config {
+  /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
+  mode: WebMode
+  /** Print the URL line on activation; a headless layer over this bundle turns it off. */
+  printUrl: boolean
+  /**
+   * Register the model-visible surface context (the `app:web-surface` prompt
+   * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
+   * layer turns it off: its user is not interacting through the GUI, so the
+   * orientation text would be false.
+   */
+  surfaceContext: boolean
+  /**
+   * LAN IPv4 addresses sampled once by the launcher when the effective bind
+   * is all-interfaces — the exact snapshot the /api trust fence was
+   * configured with, so the printed LAN URL can never name an address the
+   * fence rejects. Empty on a loopback bind.
+   */
+  lanAddresses: string[]
+}
+
+export const Config: z<Config> = z.object({
+  mode: z.union([z.const('production'), z.const('development')]).default('production'),
+  printUrl: z.boolean().default(true),
+  surfaceContext: z.boolean().default(true),
+  lanAddresses: z.array(String).default([]),
+})
+
+/** Environment variable naming the canonical local URL of this Web GUI. */
+const DSH_WEB_URL = 'DSH_WEB_URL' as const
+/** Environment variable naming the Web runtime mode. */
+const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
+
+// Display-only mirror of the webserver schema's loopback host: the address the
+// local URL always prints. Not a source of truth — the schema is.
+const LOOPBACK_HOST = '127.0.0.1'
+
+/** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
+function webSurfacePrompt(webUrl: string, mode: WebMode): string {
+  const updateContract = mode === 'development'
+    ? 'This Web process was launched with `dsh web --dev`, so its client-plugin HMR receiver is active. '
+      + 'No-refresh updates occur only when `pnpm run dev:web` is also running from this same checkout to rebuild client-plugin bundles; verify that watcher before promising automatic updates. '
+      + 'Client-plugin changes then reload automatically, while apps/web shell and other plain-package changes still require a rebuild and page refresh. '
+    : 'This Web process was launched without `--dev`, so HMR is inactive: rebuild the affected Web artifacts and verify this existing URL after a page refresh. '
+      + 'If the user wants no-refresh client-plugin updates, explain that this GUI must be restarted with `dsh web --dev` and `pnpm run dev:web` must also run from this same checkout; do not present either command alone as sufficient. '
+  return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. `
+    + 'When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. '
+    + 'The browser provides no implicit DOM, route, or screenshot context. '
+    + updateContract
+    + 'Starting another server does not update this GUI. '
+    + 'The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. '
+    + 'Do not start a replacement server unless the user asks; if one is needed, use a managed background task and verify its exact URL.'
+}
+
+/** Resolve the canonical loopback URL from the active Web server. */
+function localWebUrl(ctx: Context): string {
+  const port = ctx.get('httpServer')?.port
+  if (port === undefined) throw new Error('web-app: httpServer service missing while resolving Web runtime')
+  return `http://${LOOPBACK_HOST}:${String(port)}`
+}
+
+/** Dist location is workspace knowledge of this bundle: resolved through the frontend package exports, not configured. */
+function resolveDistIndex(): string {
+  const require = createRequire(import.meta.url)
+  try {
+    return require.resolve('@deepseek-ai/dsh-frontend/dist/index.html')
+  } catch {
+    /* v8 ignore next 2 -- reachable only on a checkout without a built dist; the test tree builds it */
+    throw new Error('web-app: frontend dist not built; run pnpm run build from the repository root first')
+  }
+}
+
+/** Test seam: hosts with no built frontend dist substitute the resolver; production never touches this. */
+export const internals: { resolveDistIndex: () => string } = { resolveDistIndex }
+
+/**
+ * Mount the Web runtime: dist serving, surface prompt, bash runtime
+ * variables, and the URL line.
+ * @param ctx - plugin context carrying the httpServer service.
+ * @param config - validated {@link Config}.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() })
+  if (config.surfaceContext) {
+    ctx.inject(['systemPrompt'], (promptCtx) => {
+      promptCtx.systemPrompt.section({
+        name: 'app:web-surface',
+        order: -98,
+        text: () => webSurfacePrompt(localWebUrl(promptCtx), config.mode),
+      })
+    })
+    ctx.inject(['bashEnv'], (runtimeCtx) => {
+      runtimeCtx.bashEnv.register({
+        name: 'web-runtime',
+        variables: {
+          [DSH_WEB_URL]: { description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session.' },
+          [DSH_WEB_MODE]: { description: 'Web runtime mode: production, or development when the client-plugin HMR receiver is active.' },
+        },
+        resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx), [DSH_WEB_MODE]: config.mode }),
+      })
+    })
+  }
+  if (config.printUrl) {
+    // The URL line is a readiness signal: supervisors (and the keyless CLI
+    // smoke) RPC as soon as they observe it, so it must not print while
+    // sibling rows (the /api route owner) are still mounting. Await Loader
+    // settlement first; a hand-built tree without a Loader prints at once.
+    const printUrl = (): void => {
+      // The launcher's boot-time LAN snapshot, not a fresh sample: the printed
+      // LAN URL must name an address the /api trust fence was configured with.
+      const lanCandidate = config.lanAddresses[0]
+      const port = ctx.httpServer.port
+      console.log(`dsh web: ${localWebUrl(ctx)}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${String(port)})`}`)
+    }
+    const loader = ctx.get('loader')
+    if (loader === undefined) printUrl()
+    else {
+      void loader.await().then(() => {
+        // The tree can be disposed while settlement was in flight (early
+        // SIGTERM); a URL line for a dead server would only mislead, and
+        // reading the torn-down port would turn a clean shutdown into a crash.
+        if (ctx.get('httpServer') !== undefined) printUrl()
+      })
+    }
+  }
+}

packages/bundle/web-app/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-web-app`.
+ * @module @deepseek-ai/dsh-web-app/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-web-app'
+
+/** Cordis companion plugin name. */
+export const name = 'web-app-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: every contribution (frontend-static child plugin,
+ * prompt section, bashEnv registration) is registry-disposed with the fiber,
+ * and each owning registry's package carries that relation's invariant; the
+ * package holds no mutable state of its own to audit.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/bundle/web-app/tests/web-app.spec.ts

@@ -0,0 +1,197 @@
+/**
+ * Web runtime glue behavior: dist resolution through the bundle's own seam,
+ * the frontend-static child claiming the fallback seat, the web-surface
+ * prompt section and bash runtime variables, and URL-line printing with the
+ * launcher's LAN snapshot.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import type { HttpServerService } from '@deepseek-ai/dsh-host-webserver'
+import { apply, Config, internals } from '../src/index.ts'
+
+let dist: string | undefined
+
+afterEach(() => {
+  vi.restoreAllMocks()
+  internals.resolveDistIndex = originalResolve
+  if (dist !== undefined) rmSync(dist, { recursive: true, force: true })
+  dist = undefined
+})
+
+const originalResolve = internals.resolveDistIndex
+
+/** Stage a dist fixture and point the bundle's resolver at it. */
+function stageDist(): string {
+  dist = mkdtempSync(join(tmpdir(), 'dsh-web-app-'))
+  mkdirSync(join(dist, 'dist'))
+  const index = join(dist, 'dist', 'index.html')
+  writeFileSync(index, '<head></head><body>shell</body>')
+  internals.resolveDistIndex = () => index
+  return index
+}
+
+/** A fake httpServer capturing the fallback seat and index taps. */
+function fakeHttpServer(): { server: HttpServerService; seat: () => unknown } {
+  let fallback: unknown
+  const server = {
+    port: 4567,
+    registerFallback: (handler: unknown) => {
+      fallback = handler
+      return () => { fallback = undefined }
+    },
+    applyIndexTaps: (html: string) => html,
+  } as unknown as HttpServerService
+  return { server, seat: () => fallback }
+}
+
+interface BashContribution {
+  name: string
+  variables: Record<string, { description: string }>
+  resolve: () => Record<string, string>
+}
+
+describe('web-app runtime glue', () => {
+  it('mounts dist serving, prompt section, bash variables, and prints the URL with the LAN snapshot', async () => {
+    stageDist()
+    const ctx = new Context()
+    const { server, seat } = fakeHttpServer()
+    ctx.provide('httpServer', server)
+    const contributions: BashContribution[] = []
+    ctx.provide('bashEnv', {
+      register: (contribution: BashContribution) => {
+        contributions.push(contribution)
+        return () => {}
+      },
+    } as never)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'development', printUrl: true, surfaceContext: true, lanAddresses: ['192.168.1.5'] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    // Settle the injected registrations.
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    expect(seat()).toBeDefined() // frontend-static claimed the fallback
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567 (LAN: http://192.168.1.5:4567)')
+    const assembly = await ctx.systemPrompt.assemble()
+    const section = assembly.sections.find(entry => entry.name === 'app:web-surface')
+    expect(section?.text).toContain('http://127.0.0.1:4567')
+    expect(section?.text).toContain('--dev')
+    const webRuntime = contributions.find(contribution => contribution.name === 'web-runtime')
+    expect(webRuntime?.resolve()).toEqual({ DSH_WEB_URL: 'http://127.0.0.1:4567', DSH_WEB_MODE: 'development' })
+    await ctx.fiber.dispose()
+  })
+
+  it('stays quiet in production mode with printUrl off and reports the production update contract', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.find(entry => entry.name === 'app:web-surface')?.text)
+      .toContain('without `--dev`')
+    await ctx.fiber.dispose()
+  })
+
+  it('skips the surface context when disabled (the one-shot layer): no prompt section, no bash variables', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const contributions: BashContribution[] = []
+    ctx.provide('bashEnv', {
+      register: (contribution: BashContribution) => {
+        contributions.push(contribution)
+        return () => {}
+      },
+    } as never)
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: false, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    const assembly = await ctx.systemPrompt.assemble()
+    expect(assembly.sections.some(entry => entry.name === 'app:web-surface')).toBe(false)
+    expect(contributions).toEqual([])
+    await ctx.fiber.dispose()
+  })
+
+  it('prints the loopback-only URL line when no LAN snapshot exists', async () => {
+    stageDist()
+    const ctx = new Context()
+    ctx.provide('httpServer', fakeHttpServer().server)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(ctx, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
+    await ctx.fiber.dispose()
+  })
+
+  it('defers the URL line until Loader settlement and drops it when the server is gone', async () => {
+    stageDist()
+    // Settlement path: the line waits for loader.await() so supervisors can
+    // RPC immediately after observing it.
+    const settled = new Context()
+    settled.provide('httpServer', fakeHttpServer().server)
+    let release: () => void
+    const settlement = new Promise<void>((resolve) => { release = resolve })
+    settled.provide('loader', { await: () => settlement } as never)
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    apply(settled, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    release!()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).toHaveBeenCalledWith('dsh web: http://127.0.0.1:4567')
+    await settled.fiber.dispose()
+
+    // Torn-down path: settlement resolves after the webserver is gone — no
+    // line, no crash.
+    log.mockClear()
+    const torn = new Context()
+    const child = torn.plugin((childCtx: Context) => {
+      childCtx.provide('httpServer', fakeHttpServer().server)
+    })
+    await child
+    let releaseTorn: () => void
+    const tornSettlement = new Promise<void>((resolve) => { releaseTorn = resolve })
+    torn.provide('loader', { await: () => tornSettlement } as never)
+    apply(torn, new Config({ mode: 'production', printUrl: true, surfaceContext: true, lanAddresses: [] }))
+    await child.dispose() // the httpServer service goes away
+    releaseTorn!()
+    await new Promise(resolve => setTimeout(resolve, 0))
+    expect(log).not.toHaveBeenCalled()
+    await torn.fiber.dispose()
+  })
+
+  it('fails loud when the prompt section resolves against a portless webserver', async () => {
+    stageDist()
+    const ctx = new Context()
+    // A webserver whose bound port is gone (torn down mid-request): the
+    // section must throw, never render a URL with an undefined port.
+    const { server } = fakeHttpServer()
+    Object.defineProperty(server, 'port', { get: () => undefined })
+    ctx.provide('httpServer', server)
+    apply(ctx, new Config({ mode: 'production', printUrl: false, surfaceContext: true, lanAddresses: [] }))
+    await ctx.plugin(SystemPrompt, { persona: '' })
+    await new Promise(resolve => setTimeout(resolve, 0))
+    await expect(ctx.systemPrompt.assemble()).rejects.toThrow('httpServer service missing')
+    await ctx.fiber.dispose()
+  })
+
+  it('resolves the real built frontend dist through the package exports, failing loud unbuilt', () => {
+    // The production resolver (not the test seam). A built checkout resolves
+    // the frontend package's index.html; a dist-less one (the CI coverage
+    // lane runs before any build) must fail with the build hint, never a
+    // silent fallback.
+    try {
+      expect(originalResolve()).toMatch(/dist[/\\]index\.html$/)
+    } catch (error) {
+      expect((error as Error).message).toContain('frontend dist not built')
+    }
+  })
+})

packages/bundle/web-app/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../host/frontend-static"
+    },
+    {
+      "path": "../../host/webserver"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../bash/bash-env"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

packages/client/AGENTS.md

@@ -86,7 +86,7 @@ If `test:gui` is red on code you did not touch, neither silently fix nor ignore
 Bringing up a new `packages/client/<name>` plugin package (ui-workspace is the latest walked example; ui-sidebar/ui-question are good skeletons to copy):
 
 1. **Package skeleton**: `package.json` (`@deepseek-ai/dsh-client-<name>`, exports `.`/`./invariant`/`./client`/`./src/*`/`./package.json`, `dshClient` manifest, `files` list), `tsconfig.json` (extends `tsconfig.base.client.json`, one `references` entry per workspace dependency plus `support/invariants`), `tsdown.config.ts` (`clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])`), `src/index.ts` (empty node-half apply), `src/invariant.ts` (companion with a real reason), `src/css-modules.d.ts` when using CSS Modules, `README.md` with the Model Experience section.
-2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `apps/cli/config/web.cordis.yml`; an `apps/cli/package.json` dependency (Loader resolves each config-tree package against the composing app's URL — a row whose package is not an `apps/cli` dependency fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
+2. **Three registration surfaces, all required** (missing any one fails at a different, later point): the `tsconfig.client.json` aggregate `references` entry; a `dshClient` row in `packages/bundle/web-app/cordis.patch.yml`; a `packages/bundle/web-app/package.json` dependency (profile boots resolve bare row names through the healed `$DSH_HOME/profiles/node_modules` fallback, which mirrors the app's and each bundle's declared dependencies — a row whose package no manifest declares fails to import). `pnpm-workspace.yaml` already globs `packages/*/*`.
 3. **dshClient manifest semantics**: `platform: 'web'` always; `immediately: true` only for stage-one-prefetch infrastructure rows. `inject` lists package-name dependency edges — they are **informational only** (preflight display, HMR diffing); they do not sequence entry activation or apply order. Activation order is cordis fiber inject waiting on *services*, nothing else.
 4. **Registering into another package's slot**: apply order is unconstrained, and a business service is not a declaration barrier. Use `ctx.slots.inject(name, () => ctx.slots.register(...))`; it waits on the actual declaration, removes the contribution when that declaration collapses, reruns after redeclaration, and leaves with the caller's plugin fiber. Return a generator yielding each registration when several contributions must install and roll back atomically. A bare `slots.register` into an undeclared slot remains an error; keep service edges only for services the contribution actually reads.
 5. Rebuild the bundle (`pnpm --filter <pkg> bundle`) before probing a live `dsh web` server — the registry serves `lib/client.js`, not sources.

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

@@ -29,6 +29,8 @@ export interface SessionListEntry {
   projectionValues?: Readonly<Partial<SessionProjectionMap>>
   /** User interaction currently blocking this session, derived from live mux frames. */
   pendingInteraction?: PendingInteractionStatus
+  /** Finished running while not selected and not yet opened — the sidebar's green "done" reminder (clears on select or the next run). */
+  completed: boolean
   /** Lineage indent depth: root = 0; the UI just multiplies by the indent width. */
   depth: number
 }
@@ -39,11 +41,13 @@ export interface SessionListEntry {
  * hydrated list from mutable timestamps.
  * @param summaries - the host's session.list items.
  * @param pendingInteractions - current manager-owned interaction status by session.
+ * @param completed - sessions with a pending completion reminder (manager-owned live fact; absent = false).
  * @returns display rows in render order.
  */
 export function flattenLineage(
   summaries: readonly TitledSessionSummary[],
   pendingInteractions?: ReadonlyMap<SessionId, PendingInteractionStatus>,
+  completed?: ReadonlySet<SessionId>,
 ): SessionListEntry[] {
   const byId = new Map<SessionId, TitledSessionSummary>()
   for (const s of summaries) byId.set(s.sessionId, s)
@@ -72,6 +76,7 @@ export function flattenLineage(
     out.push({
       ...s,
       ...(pendingInteraction === undefined ? {} : { pendingInteraction }),
+      completed: completed?.has(s.sessionId) ?? false,
       depth,
     })
     const kids = children.get(s.sessionId)

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

@@ -109,6 +109,14 @@ export class SessionManager {
    *  sessions never instantiated. Cleared per connection generation — the reopen replay re-adds
    *  still-pending requests — and on session-removed. */
   private readonly pendingInteractions = new Map<SessionId, Map<string, PendingInteractionStatus>>()
+  /**
+   * Sessions that finished running while not selected — the sidebar's green
+   * "done" reminder (manager-owned, survives connection generations; cleared
+   * on select and session-removed, re-armed by the next completion).
+   */
+  private readonly completedNotifications = new Set<SessionId>()
+  /** Last-observed running bits per session; the true→false edge here arms {@link completedNotifications}. */
+  private readonly prevRunning = new Map<SessionId, boolean>()
   /** Per-session projection value stores, retained independently of instance arrival (the
    *  title-snapshot precedent, generalized): push frames land here whether or not the Session
    *  is instantiated (list rows read the 'title' key), and an instantiated Session adopts the
@@ -175,6 +183,8 @@ export class SessionManager {
         : this.catalogs.get(address.parentSessionId)?.parentAvailable ?? false,
     )
     this.selected = sessionId
+    // Looking at the session consumes its completion reminder (dot clears).
+    this.completedNotifications.delete(sessionId)
     void this.refreshSubagents(sessionId)
     this.notifier.notifyNow()
   }
@@ -192,6 +202,7 @@ export class SessionManager {
     this.addresses.set(address.childSessionId, address)
     this.sessions.get(address.childSessionId)?.configureSubagent(address, catalog?.parentAvailable ?? false)
     this.selected = address.childSessionId
+    this.completedNotifications.delete(address.childSessionId)
     void this.refreshSubagents(address.childSessionId)
     this.notifier.notifyNow()
   }
@@ -414,13 +425,28 @@ export class SessionManager {
       try {
         const { result } = await this.api.sessions.list({})
         if (result.ok) {
-          let summaries = this.listPhase === 'pending'
+          const baseline = this.listPhase === 'pending'
             ? result.value.items
             : mergeOrderedBaseline(established, result.value.items, summary => summary.sessionId)
-          for (const mutation of mutations) summaries = applyMutation(summaries, mutation)
+          // Seed first observations from the pull-time baseline BEFORE replaying
+          // in-flight mutations, then reconcile the reminders after EVERY
+          // replayed mutation: an edge that happens entirely between mutations
+          // (baseline idle → running → idle) must still arm, which a single
+          // sync on the folded result would collapse away.
+          for (const s of baseline) {
+            if (!this.prevRunning.has(s.sessionId)) this.prevRunning.set(s.sessionId, s.running)
+          }
+          let summaries = baseline
+          for (const mutation of mutations) {
+            summaries = applyMutation(summaries, mutation)
+            this.summaries = summaries
+            this.syncCompletedNotifications()
+          }
           this.summaries = summaries
           this.listState = 'idle'
           this.listPhase = 'ready'
+          // Covers the empty-mutations pull (a plain baseline carries no edge).
+          this.syncCompletedNotifications()
           // Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source).
           for (const s of this.summaries) {
             const session = this.sessions.get(s.sessionId)
@@ -566,6 +592,8 @@ export class SessionManager {
   private recordMutation(mutation: SessionListMutation): void {
     this.listMutations?.push(mutation)
     this.summaries = applyMutation(this.summaries, mutation)
+    // Eager edge reconciliation — a snapshot-build-time pass would miss consecutive status frames.
+    this.syncCompletedNotifications()
     this.notifier.markDirty()
   }
 
@@ -893,6 +921,38 @@ export class SessionManager {
     })
   }
 
+  /**
+   * Reconcile completion reminders against the latest summaries, eagerly after
+   * every mutation and pull (a snapshot-build-time pass would collapse
+   * consecutive status frames into one observation). A running→idle edge of a
+   * non-selected session arms its reminder; running disarms it; removal drops
+   * it. First observation only records the running bit — sessions already
+   * idle at load get no reminder.
+   */
+  private syncCompletedNotifications(): void {
+    const seen = new Set<SessionId>()
+    for (const s of this.summaries) {
+      seen.add(s.sessionId)
+      const prev = this.prevRunning.get(s.sessionId)
+      if (prev === undefined) {
+        this.prevRunning.set(s.sessionId, s.running)
+        continue
+      }
+      if (prev && !s.running) {
+        if (s.sessionId !== this.selected) this.completedNotifications.add(s.sessionId)
+      } else if (s.running) {
+        this.completedNotifications.delete(s.sessionId)
+      }
+      this.prevRunning.set(s.sessionId, s.running)
+    }
+    for (const id of this.prevRunning.keys()) {
+      if (!seen.has(id)) this.prevRunning.delete(id)
+    }
+    for (const id of this.completedNotifications) {
+      if (!seen.has(id)) this.completedNotifications.delete(id)
+    }
+  }
+
   private buildListSnapshot(): SessionListSnapshot {
     const merged: TitledSessionSummary[] = this.summaries.map((summary) => {
       // List rows read the generic 'title' projection key (host-computed unit
@@ -914,7 +974,7 @@ export class SessionManager {
       const status = statuses.find(candidate => candidate !== 'approval') ?? statuses[0]
       if (status !== undefined) pendingInteractions.set(sessionId, status)
     }
-    const fresh = flattenLineage(merged, pendingInteractions)
+    const fresh = flattenLineage(merged, pendingInteractions, this.completedNotifications)
     const items = fresh.map((entry) => {
       const prev = this.entryCache.get(entry.sessionId)
       if (
@@ -924,6 +984,7 @@ export class SessionManager {
         && prev.origin === entry.origin && prev.title === entry.title && prev.depth === entry.depth
         && prev.pendingInteraction === entry.pendingInteraction
         && prev.projectionValues === entry.projectionValues
+        && prev.completed === entry.completed
       ) return prev
       this.entryCache.set(entry.sessionId, entry)
       return entry

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

@@ -51,6 +51,8 @@ export interface SessionSummary {
   running: boolean
   /** User interaction currently blocking this session (sidebar amber-dot state). */
   pendingInteraction?: PendingInteractionStatus
+  /** Finished while not selected and not yet opened — the sidebar's green "done" reminder. Absent = false. */
+  completed?: boolean
   /**
    * Empty-log bit (host summary derivation mirror). New Session reuses a blank
    * one targeting the same workspace. Filtering stays with the consumer: the
@@ -614,6 +616,7 @@ export class SessionsService implements ISessions {
         id: entry.sessionId,
         displayTitle: displayTitleOf(entry.title, entry.cwd, entry.sessionId),
         running: entry.running,
+        ...(entry.completed ? { completed: true } : {}),
         blank: entry.blank,
         updatedAt: entry.updatedAt,
         ...(entry.pendingInteraction === undefined

packages/client/runtime/tests/lineage.spec.ts

@@ -52,4 +52,11 @@ describe('flattenLineage', () => {
       warnSpy.mockRestore()
     }
   })
+
+  it('projects the completion-reminder set into rows (absent = false)', () => {
+    const out = flattenLineage([s('a', 10), s('b', 20)], undefined, new Set(['b' as SessionId]))
+    expect(out.find(e => e.sessionId === 'a')?.completed).toBe(false)
+    expect(out.find(e => e.sessionId === 'b')?.completed).toBe(true)
+    expect(flattenLineage([s('a', 10)])[0]?.completed).toBe(false)
+  })
 })

packages/client/runtime/tests/manager.spec.ts

@@ -985,3 +985,128 @@ describe('pending-interaction list status', () => {
     expect(session.getSnapshot().pending).toEqual([])
   })
 })
+
+describe('completed reminder', () => {
+  const status = (rpcId: string, sessionId: SessionId, running: boolean) => ({
+    rpcId: rpcId as never,
+    payload: { type: 'host/session-status' as const, sessionId, running },
+  })
+  const added = (rpcId: string, sessionId: SessionId) => ({
+    rpcId: rpcId as never,
+    payload: { type: 'host/session-added' as const, sessionId, blank: false },
+  })
+  const entry = (manager: SessionManager, sessionId: SessionId) =>
+    manager.getListSnapshot().items.find(item => item.sessionId === sessionId)
+
+  it('arms on a running→idle flip of a non-selected session and clears on select', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    // Opening the session consumes the reminder.
+    manager.select(S2)
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('never arms for the session being watched and re-arms after a switch-away re-run', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S2)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(false) // watched to completion: no reminder
+    // Switch away; a fresh run completing again arms the reminder.
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s3', S2, true))
+    manager.handleHostEnvelope(status('s4', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('a re-run disarms the reminder while running and re-arms on its completion', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    // The user starts a new run without opening the session: running wins.
+    manager.handleHostEnvelope(status('s3', S2, true))
+    expect(entry(manager, S2)?.completed).toBe(false)
+    manager.handleHostEnvelope(status('s4', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('session-removed drops the reminder and a re-add starts clean', () => {
+    const manager = new SessionManager(new FakeApiClient())
+    manager.handleHostEnvelope(added('h1', S1))
+    manager.handleHostEnvelope(added('h2', S2))
+    manager.select(S1)
+    manager.handleHostEnvelope(status('s1', S2, true))
+    manager.handleHostEnvelope(status('s2', S2, false))
+    expect(entry(manager, S2)?.completed).toBe(true)
+    manager.handleHostEnvelope({ rpcId: 'rm' as never, payload: { type: 'host/session-removed', sessionId: S2 } })
+    expect(manager.getListSnapshot().items.find(item => item.sessionId === S2)).toBeUndefined()
+    manager.handleHostEnvelope(added('h3', S2))
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('a list refresh carrying the running→idle transition arms the reminder', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: true })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: false })] as never[] }))
+    await manager.refreshList()
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('never arms for sessions already idle at first observation', async () => {
+    const api = new FakeApiClient()
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    const manager = new SessionManager(api)
+    await manager.refreshList()
+    manager.select(S1)
+    expect(entry(manager, S2)?.completed).toBe(false)
+    api.onList = () => Promise.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 201 })] as never[] }))
+    await manager.refreshList()
+    expect(entry(manager, S2)?.completed).toBe(false)
+  })
+
+  it('arms a completion that happened during an in-flight first pull (baseline running, replayed idle)', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const refresh = manager.refreshList()
+    // The session finishes while the first pull is still in flight; the pull
+    // response recorded it as running at pull time.
+    manager.handleHostEnvelope(status('s-mid', S2, false))
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200, running: true })] as never[] }))
+    await refresh
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+
+  it('arms when a session ran and completed entirely between in-flight mutations (baseline idle)', async () => {
+    const api = new FakeApiClient()
+    const gate = deferred<Awaited<ReturnType<FakeApiClient['onList']>>>()
+    api.onList = () => gate.promise
+    const manager = new SessionManager(api)
+    const refresh = manager.refreshList()
+    // The unknown session starts and finishes while the first pull is in
+    // flight; the pull-time baseline recorded it idle, so the running→idle
+    // edge lives entirely inside the replayed mutations.
+    manager.handleHostEnvelope(status('s-start', S2, true))
+    manager.handleHostEnvelope(status('s-finish', S2, false))
+    gate.resolve(ok({ items: [summary(S1), summary(S2, { updatedAt: 200 })] as never[] }))
+    await refresh
+    expect(entry(manager, S2)?.completed).toBe(true)
+  })
+})

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

@@ -2,5 +2,5 @@
 # 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 packages/client/ui-command/README.md
-README.md: a19bfe7135acc5408448dc73d04813ed4104dd48
-README.zh.md: 79d903b916728c1200ab1311055f2be190008787
+README.md: bc7386c8fca3b5c623473328bee6322fa7295277
+README.zh.md: 478ee4ccee4558c70075baa45ab34ac6e3d71617

packages/client/ui-command/README.md

@@ -8,6 +8,8 @@ Client command surface (`ctx.command`): the session-keyed command-directory cach
 
 `CommandDirectory` (`src/client/directory.ts`) is the one wire-derived cache, keyed by session. Ordinary sessions fetch through `command.list({sessionId})`, and the source's scope-birth `warm` hook prewarms the session's entry. Catalog-addressed continuable children resolve an empty command directory locally: `command.list` is Agent-bound, so prewarming it would activate a child merely to view persisted history. 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.
 
+Menu queries fuzzy-match ordered, case-insensitive subsequences of command names. Prefixes rank first; separator boundaries, adjacent characters, and shorter gaps rank the remaining matches, with directory and contribution order breaking ties. This affects discovery only: space and Enter still require an exact command name. Rationale: [Web slash-command fuzzy discovery](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md).
+
 `PopupSelectController` (`src/client/popup.ts`) is the headless shell state: `PopupSelectView` self-registers into `conversation.input.overlay` (the SlotMap key is ui-conversation's; this package pulls the declaration in with a type-only import — no runtime edge). The shell is a transient layer holding focus while open; token-segment consumption after onSelect runs both branches through `consumeTokenSegment` (menu-path span CAS, enter-path bare-token equality) against the draft face the wiring layer binds via `bindDraft`.
 
 The `/client` export surface is the plugin body (`apply`/`inject`), `CommandService`, the directory and popup classes with their state types, and the frozen contract types; the shell component itself is internal to the overlay registration.

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

@@ -8,6 +8,8 @@
 
 `CommandDirectory`（`src/client/directory.ts`）是唯一的 wire 派生缓存，以会话为 key。普通会话通过 `command.list({sessionId})` 拉取，source 的 scope 出生 `warm` 钩子会预热该会话的缓存项。由目录寻址的可继续子代理会在客户端解析为空命令目录：`command.list` 绑定 Agent，若预热它，就会仅因查看持久化历史而激活子代理。缓存项由 `commands/changed` 类型化事件软失效（重拉在途期间旧快照继续服务），由 `connection/reset` 硬失效，并以 epoch 把关，被取代的旧拉取永远无法覆盖更新的结果。`matchSpace` 只凭该缓存同步应答；`matchEnter` 在 SubmitAttempt 信号上强等缓存，预热失败即拒绝——`/` 开头的一行绝不会被静默降级为普通提示词。
 
+菜单查询会按顺序且不区分大小写地模糊匹配命令名的子序列。前缀排名最高；其余匹配项按分隔符边界优先、相邻字符优先、间隔越短越优先的规则排序，若仍同分，则以目录顺序和 contribution 顺序打破平局。此行为只影响命令发现：space 和 Enter 仍要求命令名精确匹配。原理：[Web 斜杠命令模糊发现](../../../.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md)。
+
 `PopupSelectController`（`src/client/popup.ts`）是无头的壳状态：`PopupSelectView` 自行注册进 `conversation.input.overlay`（SlotMap key 归 ui-conversation 所有；本包只以 type-only 导入引入该声明——没有运行时依赖边）。壳是打开期间持有焦点的瞬态层；onSelect 之后的 token 片段消费在两条分支上都经 `consumeTokenSegment` 执行（菜单路径做 span CAS，回车路径做裸 token 相等比较），作用于接线层经 `bindDraft` 绑定的草稿表层。
 
 `/client` 导出表层是插件主体（`apply`／`inject`）、`CommandService`、目录类和 popup 类及其状态类型，以及冻结的契约类型；壳组件本身是 overlay 注册的内部实现。

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

@@ -2,9 +2,10 @@
  * CommandService (`ctx.command`): the '/' command source over the
  * session-keyed directory, the client-contribution registry, and the
  * per-session popupSelect controllers. Candidate synthesis merges the host
- * catalog with contributions by availability, then query/position filtering;
- * a host/contribution name collision fails loud. Every execute addresses the
- * session's agent by sessionId — sessions are always agent-backed.
+ * catalog with contributions by availability, then fuzzy query/position
+ * filtering; a host/contribution name collision fails loud. Every execute
+ * addresses the session's agent by sessionId — sessions are always
+ * agent-backed.
  */
 import { Service } from 'cordis'
 import type { Context } from 'cordis'
@@ -27,6 +28,69 @@ interface LiveState {
   readonly popups: Map<SessionId, PopupSelectController<ClientSessionContext>>
 }
 
+/** One fuzzy match with its stable source position. */
+interface RankedCandidate {
+  readonly candidate: SlashCandidate
+  readonly index: number
+  readonly prefix: boolean
+  readonly score: number
+}
+
+/** Extra weight for command-name starts and separator boundaries. */
+function boundaryBonus(name: string, index: number): number {
+  return index === 0 || name.charAt(index - 1) === '-' || name.charAt(index - 1) === '_' ? 8 : 0
+}
+
+/**
+ * Score the strongest ordered-subsequence alignment in O(name × query).
+ * Boundary and adjacent matches earn weight; skipped and leading characters
+ * cost weight.
+ */
+function fuzzyScore(name: string, query: string): number | undefined {
+  if (query === '') return 0
+  if (query.length > name.length) return undefined
+  const noMatch = Number.NEGATIVE_INFINITY
+  let previous = Array<number>(name.length).fill(noMatch)
+  for (let index = 0; index < name.length; index++) {
+    if (name.charAt(index) === query.charAt(0)) previous[index] = 1 + boundaryBonus(name, index) - index
+  }
+  for (let queryIndex = 1; queryIndex < query.length; queryIndex++) {
+    const current = Array<number>(name.length).fill(noMatch)
+    let bestGapped = noMatch
+    for (let index = 0; index < name.length; index++) {
+      const gappedIndex = index - 2
+      if (gappedIndex >= 0) {
+        const prior = previous[gappedIndex] ?? noMatch
+        if (prior !== noMatch) bestGapped = Math.max(bestGapped, prior + gappedIndex)
+      }
+      if (name.charAt(index) !== query.charAt(queryIndex)) continue
+      const bonus = 1 + boundaryBonus(name, index)
+      const adjacent = index > 0 ? previous[index - 1] ?? noMatch : noMatch
+      if (adjacent !== noMatch) current[index] = adjacent + bonus + 4
+      if (bestGapped !== noMatch) current[index] = Math.max(current[index] ?? noMatch, bestGapped + bonus + 1 - index)
+    }
+    previous = current
+  }
+  let best = noMatch
+  for (const score of previous) best = Math.max(best, score)
+  return best === noMatch ? undefined : best
+}
+
+/** Case-insensitive fuzzy filtering with stable ordering for equal matches. */
+function fuzzyCandidates(candidates: readonly SlashCandidate[], rawQuery: string): readonly SlashCandidate[] {
+  const query = rawQuery.toLowerCase()
+  if (query === '') return candidates
+  const ranked: RankedCandidate[] = []
+  candidates.forEach((candidate, index) => {
+    const name = candidate.name.toLowerCase()
+    const score = fuzzyScore(name, query)
+    if (score !== undefined) ranked.push({ candidate, index, prefix: name.startsWith(query), score })
+  })
+  ranked.sort((left, right) =>
+    Number(right.prefix) - Number(left.prefix) || right.score - left.score || left.index - right.index)
+  return ranked.map(match => match.candidate)
+}
+
 /** Command surface: session-keyed directory + '/' source + contribution registry + per-session popups. */
 export class CommandService extends Service implements CommandServiceContract {
   static inject = ['slash', 'sessions', 'connection']
@@ -147,7 +211,7 @@ export class CommandService extends Service implements CommandServiceContract {
     }
   }
 
-  /** Menu candidates: host catalog + contribution availability, then query/position filtering. */
+  /** Menu candidates: host catalog + contribution availability, then position filtering and fuzzy name ranking. */
   private async candidates(session: ClientSessionContext, req: CandidateRequest): Promise<readonly SlashCandidate[]> {
     const list = await this.directory.ensureReady(session.sessionId, req.signal)
     const rows: SlashCandidate[] = []
@@ -163,9 +227,10 @@ export class CommandService extends Service implements CommandServiceContract {
       }
       rows.push({ name: contribution.name, description: contribution.description })
     }
-    return rows
-      .filter(c => c.name.startsWith(req.query))
-      .filter(c => req.position === 'leading' || c.hint === undefined)
+    return fuzzyCandidates(
+      rows.filter(c => req.position === 'leading' || c.hint === undefined),
+      req.query,
+    )
   }
 
   /** Decision table, menu column: contribution/decorated-host → popup; host input → claim; host bare → detached execute. */

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

@@ -164,13 +164,33 @@ describe('candidates', () => {
     expect(b.listCalls).toEqual([])
   })
 
-  it('pulls the session catalog; prefix filter and hint mapping apply', async () => {
+  it('pulls the session catalog; fuzzy filter and hint mapping apply', async () => {
     const { source, listCalls } = await bench()
     const list = await source.candidates(proj('s1'), req('g'))
     expect(listCalls).toEqual([{ sessionId: sid('s1') }])
     expect(list).toEqual([{ name: 'goal', description: 'leadingInput kind', hint: 'goal text' }])
   })
 
+  it('matches case-insensitive subsequences and ranks prefixes, boundaries, adjacency, gaps, then source order', async () => {
+    const commands: CommandDescriptor[] = [
+      { name: 'q-xylophone', description: '' },
+      { name: 'qx-long', description: '' },
+      { name: 'fabulous', description: '' },
+      { name: 'foo-bar', description: '' },
+      { name: 'zuv', description: '' },
+      { name: 'zu1v', description: '' },
+      { name: 'yu1v', description: '' },
+      { name: 'zu12v', description: '' },
+    ]
+    const { source } = await bench({ commands: () => Promise.resolve({ commands }) })
+    const names = async (query: string) => (await source.candidates(proj('s1'), req(query))).map(c => c.name)
+    await expect(names('QX')).resolves.toEqual(['qx-long', 'q-xylophone'])
+    await expect(names('fb')).resolves.toEqual(['foo-bar', 'fabulous'])
+    await expect(names('uv')).resolves.toEqual(['zuv', 'zu1v', 'yu1v', 'zu12v'])
+    await expect(names('zzz')).resolves.toEqual([])
+    await expect(names('query-longer-than-every-name')).resolves.toEqual([])
+  })
+
   it('catalogs are per session: another session pulls its own key', async () => {
     const { source, listCalls } = await bench()
     const names = (await source.candidates(proj('s2'), req(''))).map(c => c.name)
@@ -195,10 +215,10 @@ describe('candidates', () => {
     expect(s2Names).not.toContain('theme')
   })
 
-  it('contribution rows ride the same query prefix filter', async () => {
+  it('contribution rows ride the same fuzzy query filter', async () => {
     const { command, source } = await bench()
     command.register(themeContribution())
-    const names = (await source.candidates(proj('s1'), req('th'))).map(c => c.name)
+    const names = (await source.candidates(proj('s1'), req('tm'))).map(c => c.name)
     expect(names).toEqual(['theme'])
   })
 

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

@@ -2,5 +2,5 @@
 # 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 packages/client/ui-conversation/README.md
-README.md: 7bd0d551fc41967326dd9860f5c31a99ea3c254a
-README.zh.md: d339f6423d9a9f77c02d86ad0b8e57bd0baba52b
+README.md: bbd115eac0eb914914dc11e504639633c801abdd
+README.zh.md: 843b49e311fbf1a9157413c42a0ef3e9828284bc

packages/client/ui-conversation/README.md

@@ -6,9 +6,9 @@ Conversation domain: skeleton (header/tabs/composer/empty state), chat view (gro
 
 Compaction renders as one collapsed row at the checkpoint's flow position without replacing the transcript above it. The disclosure renders the checkpoint's `compact/summary` provenance; when that event is outside the loaded window, the row remains visible but non-expandable. The framed checkpoint payload is model-facing and never renders.
 
-The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it a scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
+The resident conversation shell survives no-session and session transitions. Without a current session it renders a disabled input bar; its root-scoped `conversation.hero.workspace` slot hosts the Workspace picker. Selecting a Workspace connects or reuses its Host-owned blank session and opens that session without replacing the shell. The root always owns the same scrollport and Hero/composer subtree; separate strict-session header and body outlets fill their regions when the first Session arrives, so the Workspace picker, scroll body, composer seat, and textarea retain their React and DOM identity. Blank sessions render the same composer body as active sessions, while the InputHub carries drafts across Workspace switches and mirrors them into the session store. In the active phase the session header shows only the current session title and view tabs as ordinary column chrome; fork lineage remains session data and is not projected into the header. Beneath it the scrollport (`data-conversation-scroll`) holds the flowing views and the sticky composer stack (stats dock + input docks + bar). That scrollport reserves its scrollbar gutter unconditionally, and a view opting into a composer overlay leaves it a scroll container, so the input card keeps one horizontal position whether or not the transcript scrolls and whichever view tab is shown ([decision](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)). Wheel over the textarea chains: the capped draft scrolls locally until its edge, then forwards to that host.
 
-The view ring is a slot: the conversation registration declares the session-scoped `'conversation.view'` list in its `children` table, ConversationRoot renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
+The view ring is a slot: the strict session-body registration declares the session-scoped `'conversation.view'` list in its `children` table, that body renders the active entry through its renderSlot share (`only: <active id>`), and view tabs project from registration options (`id`/`order`/`label`). The chat view is this package's own entry; plugins such as ui-trajectory contribute tabs through `ctx.slots.register`, and each view owns its chrome.
 
 Approvals take over the composer through the chain this package declares: `ApprovalPanel` registers as a selector-routed `'conversation.composer'` entry (the ui-question pattern) and occupies the composer in place of the InputBar while an approval wait is pending (amber strip, justification headline, paired command line from the running call's args, one-shot refuse/allow). The `PendingApproval` domain face in `contract/slots.ts` owns the wire encoding — the `ApprovalResponsePayload` value with the audit correlation — over the runtime's `PendingWait` carrier; the broadcast `approval/resolved` frame settles the wait and restores the composer. The runtime manager projects every approval or question wait through `SessionSummary.pendingInteraction`, including sessions never instantiated; `ui-workspace` owns its sidebar presentation. Pending waits leave the message flow entirely: questions (ui-question) and approvals (ApprovalPanel) both answer through the composer takeover, so no display-only placeholder card remains. The composer's bottom-row Access seat mounts `PermissionSelect`, fed by the host-computed `permissions` projection through the standard-kit `useProjection` (key absence hides the chip); the chip opens a Menu-primitive dropdown whose kebab-case preset names render as title-case labels. Safe preset picks submit `/permission <preset>` immediately through the bar's injected `command` callback, while `danger-full-access` is presented as `Full access` and first opens an in-page Modal risk confirmation. The enabling action stays disabled until the user checks the acknowledgement; cancel, Escape, close, and mask click submit nothing.
 

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

@@ -6,9 +6,9 @@
 
 压缩（compaction）在检查点自身的消息流位置渲染为一行折叠标记，不替换其上方的 transcript（文本记录）。展开内容来自检查点溯源的 `compact/summary`；该事件位于已加载窗口之外时，标记仍然可见但不可展开。面向模型的带框检查点载荷绝不渲染。
 
-常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
+常驻会话壳会跨无会话与会话状态切换而保留。没有当前会话时，它会渲染禁用输入栏；其根作用域的 `conversation.hero.workspace` slot 承载 Workspace 选择器。选择 Workspace 会连接或复用由 Host 拥有的空白会话，并在不替换会话壳的情况下打开该会话。根组件始终拥有同一个滚动容器与 Hero／编辑器子树；首个会话到达时，彼此独立的严格会话页头和主体 outlet 只填入各自区域，因此 Workspace 选择器、滚动主体、编辑器 seat 与 textarea 都保留原有 React 和 DOM identity。空白会话与活跃会话渲染相同的输入区主体；InputHub 则在 Workspace 切换间携带草稿，并将草稿镜像到会话 store。活跃阶段，会话标题栏作为普通列 chrome，仅显示当前会话标题和视图标签；fork 谱系仍保留为会话数据，不投影到标题栏。其下滚动容器（`data-conversation-scroll`）承载流动排版的各视图与 sticky 编辑器栈（统计 dock＋输入区 dock＋输入栏）。该滚动容器无条件预留自己的滚动条槽，选用编辑器 overlay 的视图也仍把它保留为滚动容器，因此无论对话记录是否滚动、无论展示哪个视图标签，输入卡片都保持同一个横向位置（[决策](../../../.agents/notes/implemented/bug-fix/2026-08-04-composer-tab-gutter-reservation.md)）。textarea 上的滚轮会链式处理：限高草稿先在本地滚动，到达边缘后再转交给该宿主。
 
-视图环是一个 slot：会话注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，ConversationRoot 通过 renderSlot share 渲染活跃配置项（`only: <active id>`），视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
+视图环是一个 slot：严格会话主体注册在 `children` 表中声明 Session scope 的 `'conversation.view'` 列表，并通过自身的 renderSlot share 渲染活跃配置项（`only: <active id>`）；视图标签页则从注册选项（`id`／`order`／`label`）投影而来。聊天视图是该包自身的配置项；ui-trajectory 等插件通过 `ctx.slots.register` 贡献标签页，每个视图负责自己的 chrome。
 
 会话页头会在标题旁声明并渲染 Session scope 的 `'conversation.session.header.actions'` 列表，使功能插件无需进入骨架即可贡献控件。编辑器链的 currency 包含当前对话 `session`；ui-subagent 会选取 one-shot 或 parent 不可用的已寻址会话，并按原因显示只读文案，而普通 InputBar 会让所有已寻址 child 仅保留 Send，因为继续执行服务不公开逐 Activation 取消操作，`session.cancel` 也会绕过其所有权。
 

packages/client/ui-conversation/src/client/apply.ts

@@ -8,7 +8,7 @@ import type {} from '@deepseek-ai/dsh-client-locale/client'
 import type { ViewTab } from './contract/views.ts'
 import type {
   ApprovalWait, ChatScrollPosition, ChatViewInjected, ComposerBarInjected, ComposerChainProps, ConversationInjected,
-  ConversationSessionInjected, DetailsInjected,
+  ConversationSessionHeaderInjected, ConversationSessionInjected, DetailsInjected,
 } from './contract/slots.ts'
 import type { InputNotice } from './input/contract.ts'
 import { resolveToolPath } from './contract/tool-call-model.ts'
@@ -33,7 +33,7 @@ import { askQuestionToolview } from './toolviews/ask-question-row.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
 import { queueDockEntry } from './queue/QueueDock.tsx'
 import { ConversationRoot } from './skeleton/ConversationRoot.tsx'
-import { ConversationSession } from './skeleton/ConversationSession.tsx'
+import { ConversationSession, ConversationSessionHeader } from './skeleton/ConversationSession.tsx'
 import { DetailsPanel } from './skeleton/DetailsPanel.tsx'
 import { en, NS, zh, type ConversationKey } from './locales.ts'
 
@@ -123,6 +123,11 @@ export function apply(ctx: Context): void {
     }
     return tabs
   }
+  const views = {
+    list: viewTabs,
+    subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
+    version: () => slots.getVersion('conversation.view'),
+  }
 
   // The per-session input machine registry (InputService face; published as
   // ctx.conversation.input by the service below sharing this one instance).
@@ -151,6 +156,7 @@ export function apply(ctx: Context): void {
     locale: NS,
     children: {
       'conversation.session': { kind: 'single', scope: 'session' },
+      'conversation.session.header': { kind: 'single', scope: 'session' },
       'conversation.composer': { kind: 'chain', scope: 'session' },
       'conversation.composer.bar': { kind: 'single', scope: 'session-maybe' },
       'conversation.input.overlay': { kind: 'list', scope: 'session' },
@@ -176,27 +182,36 @@ export function apply(ctx: Context): void {
     }),
   }, ConversationRoot)
 
-  // The strict session subtree owns only per-session store and view content;
-  // the resident parent keeps Hero and composer layout identity stable.
+  // The strict session body fills the resident scrollport without owning it;
+  // the Hero/composer path therefore stays fixed while the first blank
+  // session appears after a Workspace pick.
   slots.register({
     name: 'conversation.session',
-    locale: NS,
     children: {
       'conversation.view': { kind: 'list', scope: 'session' },
-      'conversation.session.header.actions': { kind: 'list', scope: 'session' },
     },
     store: chatStore,
     inject: (sessionId: SessionId, _actions: BoundActions<typeof chatStore>): ConversationSessionInjected => ({
-      views: {
-        list: viewTabs,
-        subscribe: fn => slots.subscribe('conversation.view', fn),
-        version: () => slots.getVersion('conversation.view'),
-      },
+      views,
       bindDraftMirror: write => inputHub.shell(sessionId).bindMirror(write),
-      open: (id) => { sessions.open(id) },
     }),
   }, ConversationSession)
 
+  // Header chrome sits above the resident scrollport but shares the same
+  // per-session chat store (active view) as its body and view entries.
+  slots.register({
+    name: 'conversation.session.header',
+    locale: NS,
+    children: {
+      'conversation.session.header.actions': { kind: 'list', scope: 'session' },
+    },
+    store: chatStore,
+    inject: (): ConversationSessionHeaderInjected => ({
+      views,
+      open: (id) => { sessions.open(id) },
+    }),
+  }, ConversationSessionHeader)
+
   // The default composer body: its own single slot inside the composer
   // chain's fallback (decision 20). Public machine surface arrives via the
   // provide channel above; the keyboard command face and the stop/retry

packages/client/ui-conversation/src/client/contract/slots.ts

@@ -13,19 +13,20 @@ import type { CallId, SelectionTarget, ViewTab } from './views.ts'
 declare module '@deepseek-ai/dsh-client-ui-slots' {
   interface SlotMap {
     /**
-     * Strict-session content inside the resident conversation shell. This
-     * subtree owns the per-session chat store, header, and view ring and is
-     * remounted when the current session id changes.
+     * Strict-session body inside the resident conversation scrollport. It
+     * owns the per-session draft mirror and active view ring.
      */
-    'conversation.session': { kind: 'single'; scope: 'session'; owner: ConversationSessionOwnerProps }
+    'conversation.session': { kind: 'single'; scope: 'session' }
+    /** Strict-session header above the resident conversation scrollport. */
+    'conversation.session.header': { kind: 'single'; scope: 'session' }
     /** Session-header actions contributed by feature plugins. */
     'conversation.session.header.actions': { kind: 'list'; scope: 'session'; owner: ConversationHeaderActionOwnerProps }
     /**
      * The conversation view ring: one list entry per view tab (chat here;
      * trajectory/waterfall from ui-trajectory), rendered one-at-a-time by
-     * ConversationRoot via `only: <active id>`. Declared by this package's
-     * 'conversation' entry (declaring is claiming). Session scope: views read
-     * the conversation snapshot through the standard kit.
+     * the session body via `only: <active id>`. Declared by this package's
+     * body entry (declaring is claiming). Session scope: views read the
+     * conversation snapshot through the standard kit.
      */
     'conversation.view': { kind: 'list'; scope: 'session'; owner: ConvViewOwnerProps }
     /**
@@ -122,22 +123,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
   }
 }
 
-/** Owner share of the strict session content seat. */
-export interface ConversationSessionOwnerProps {
-  /**
-   * Wrap the view ring in the transcript scrollport that also hosts the
-   * sticky composer seat (whole `'conversation.composer'` chain output).
-   * Supplied for every real session (hero/settling/active) so the composer
-   * keeps one tree seat across the blank → active flip; the header stays
-   * outside that wrapper as ordinary column chrome (`flex: none`), while
-   * active CSS sticks the seat to the bottom of the same scrollport so wheel
-   * over the footer scrolls the flow.
-   * @param view - the session view-ring content (null while blank chrome is hidden).
-   * @returns the scrollport containing `view` and the sticky composer seat.
-   */
-  wrapActiveBody?: (view: ReactNode) => ReactNode
-}
-
 /** Header actions derive their state from the standard session/global kit. */
 export interface ConversationHeaderActionOwnerProps {}
 
@@ -228,7 +213,7 @@ export type CommandRowProps = PropsRuntime<'conversation.chat.commandview'>
  */
 export type ConvViewProps = PropsRuntime<'conversation.view'>
 
-/** The shared chat store handle type (apply constructs one; the conversation, details, and chat-view registrations all declare it). */
+/** The shared chat store handle type declared by the Session header/body, details, and chat-view registrations. */
 export type ChatStore = ReturnType<typeof createChatStore>
 
 /** Business callbacks injected into the conversation slot. */
@@ -240,7 +225,7 @@ export interface ConversationInjected {
   selectWorkspace: (workspaceId: WorkspaceId) => Promise<void>
 }
 
-/** Business callbacks injected into the strict session content seat. */
+/** Business callbacks injected into the strict Session body seat. */
 export interface ConversationSessionInjected {
   /** Views projected from the `conversation.view` slot ledger. */
   views: {
@@ -250,6 +235,16 @@ export interface ConversationSessionInjected {
   }
   /** Bind the input machine's draft persistence mirror to the session store. */
   bindDraftMirror: (write: (text: string) => void) => () => void
+}
+
+/** Business callbacks injected into the strict session header seat. */
+export interface ConversationSessionHeaderInjected {
+  /** Views projected from the `conversation.view` slot ledger. */
+  views: {
+    list: () => readonly ViewTab[]
+    subscribe: (fn: () => void) => () => void
+    version: () => number
+  }
   /** Select a real Session through the runtime navigation owner. */
   open: (sessionId: SessionId) => void
 }
@@ -354,7 +349,8 @@ export interface ComposerChainProps {
  */
 export type ConversationSlotProps =
   PropsRuntime<'conversation'> & PropsRenderSlots<
-    | 'conversation.session' | 'conversation.composer' | 'conversation.composer.bar'
+    | 'conversation.session' | 'conversation.session.header'
+    | 'conversation.composer' | 'conversation.composer.bar'
     | 'conversation.input.overlay'
     | 'conversation.input.dock' | 'conversation.composer.dock'
     | 'conversation.input.left' | 'conversation.input.right'
@@ -363,12 +359,19 @@ export type ConversationSlotProps =
   & ConversationInjected
   & PropsLocale<'conversation'>
 
-/** Full strict-session content props: per-session store, view ring, callbacks, and the locale seat. */
+/** Full strict-session body props: per-session store, view ring, and draft mirror. */
 export type ConversationSessionSlotProps =
   PropsRuntime<'conversation.session'>
-  & PropsRenderSlots<'conversation.view' | 'conversation.session.header.actions'>
+  & PropsRenderSlots<'conversation.view'>
   & PropsStore<ChatStore>
   & ConversationSessionInjected
+
+/** Full strict-session header props: shared store, tabs/actions render shares, navigation, and locale. */
+export type ConversationSessionHeaderSlotProps =
+  PropsRuntime<'conversation.session.header'>
+  & PropsRenderSlots<'conversation.session.header.actions'>
+  & PropsStore<ChatStore>
+  & ConversationSessionHeaderInjected
   & PropsLocale<'conversation'>
 
 /** The pending approval carrier the owner dispatches into the composer chain. */

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

@@ -15,7 +15,8 @@ export type { ConversationKey } from './locales.ts'
 export type {
   ChatStore, ChatViewInjected, ChatViewSlotProps, CommandRowOwnerProps, CommandRowProps, ComposerBarInjected,
   ComposerChainProps, ConversationInjected,
-  ConversationSessionInjected, ConversationSlotProps, ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
+  ConversationSessionHeaderInjected, ConversationSessionInjected, ConversationSlotProps,
+  ConvViewOwnerProps, ConvViewProps, DetailsInjected, DetailsSlotProps,
   EmptyWorkspaceOwnerProps, ToolRowOwnerProps, ToolRowProps,
 } from './contract/slots.ts'
 // Export discipline: packages/client/AGENTS.md.

packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css

@@ -31,8 +31,8 @@
   border-bottom: 1px solid var(--dsw-alias-border-l2);
 }
 
-/* Blank hero/settling: keep the header node mounted (stable Session tree for
-   the wrapActiveBody composer) without taking column space. */
+/* Blank hero/settling: keep the strict Session header mounted without taking
+   column space; the root-owned scrollport and composer remain below it. */
 .headerHidden {
   display: none;
 }

packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx

@@ -2,7 +2,7 @@
 // chain, AND the composer bar (session-maybe slot) stay mounted across
 // no-session/session transitions — the bar renders inert via owner props.
 
-import { useCallback, useEffect, useRef, useState, type ReactNode } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import clsx from 'clsx'
 import type { WorkspaceId } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSlotProps, InputZone } from '../contract/slots.ts'
@@ -31,9 +31,8 @@ export function ConversationRoot({
 
   // Publishes the seat's live height as --dsh-composer-height on the scroll
   // body so floating controls (ChatView back-to-bottom) clear the composer as
-  // it grows. Callback ref, not an effect: the seat remounts when the tree
-  // moves between the no-session and session paths. Stable identity so React
-  // reattaches only on those remounts, not on every render.
+  // it grows. Callback ref, not an effect; stable identity prevents observer
+  // churn while the first blank session fills the resident body outlet.
   const seatObserver = useRef<ResizeObserver | null>(null)
   const seatResizeRef = useCallback((seat: HTMLDivElement | null): void => {
     seatObserver.current?.disconnect()
@@ -167,28 +166,13 @@ export function ConversationRoot({
     </div>
   )
 
-  // Header stays column chrome above this scrollport; the sticky composer
-  // seat lives inside it with the transcript. Always wrap while a session
-  // exists (hero/settling/active) so the composer keeps one tree seat across
-  // the blank → active flip — relocating it only in active remounted the textarea.
-  const wrapActiveBody = (view: ReactNode): ReactNode => (
-    <div className={css.scrollBody} data-conversation-scroll="">
-      {view}
-      {composerSeat}
-    </div>
-  )
-
   return (
     <div className={css.root} data-phase={phase}>
-      {/* Mounted for every real session, hero included: ConversationSession
-          keeps a chrome-hidden shell while blank and owns the draft-
-          persistence mirror bind — unmounting it in the hero would lose
-          pre-first-send text on a refresh or scope rebuild. */}
-      {sessionId !== undefined && renderSlot(
-        'conversation.session',
-        { wrapActiveBody },
-      )}
-      {sessionId === undefined ? wrapActiveBody(null) : null}
+      {renderSlot('conversation.session.header', {})}
+      <div className={css.scrollBody} data-conversation-scroll="">
+        {renderSlot('conversation.session', {})}
+        {composerSeat}
+      </div>
     </div>
   )
 }

packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx

@@ -1,14 +1,19 @@
-/** Strict per-session conversation content: header, view ring, and chat store bindings. */
+/** Strict per-session header/body content inserted into the resident conversation layout. */
 
-import { useEffect, useSyncExternalStore, type ReactNode } from 'react'
+import { useEffect, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import type { SessionId, SessionListState, SessionSummary } from '@deepseek-ai/dsh-client-runtime/client'
-import type { ConversationSessionSlotProps } from '../contract/slots.ts'
+import type {
+  ConversationSessionHeaderSlotProps, ConversationSessionSlotProps,
+} from '../contract/slots.ts'
 import css from './ConversationRoot.module.css'
 
-/** Full props composed from the strict session slot contract. */
+/** Full props composed from the strict session body contract. */
 export type ConversationSessionProps = ConversationSessionSlotProps
 
+/** Full props composed from the strict session header contract. */
+export type ConversationSessionHeaderProps = ConversationSessionHeaderSlotProps
+
 interface Breadcrumb {
   readonly id: SessionId
   readonly displayTitle: string
@@ -38,10 +43,15 @@ function equalBreadcrumbs(left: readonly Breadcrumb[], right: readonly Breadcrum
     })
 }
 
-export function ConversationSession({
-  sessionId, useSession, useSessions, useInput, inputActions, useStore, actions,
-  renderSlot, views, bindDraftMirror, open, wrapActiveBody, t,
-}: ConversationSessionProps) {
+/**
+ * Renders Session header chrome above the resident conversation scrollport.
+ * @param props - Strict Session store, view ledger, navigation, render, and locale shares.
+ * @returns the hidden blank-session header or visible title and tabs.
+ */
+export function ConversationSessionHeader({
+  sessionId, useSession, useSessions, useStore, actions,
+  renderSlot, views, open, t,
+}: ConversationSessionHeaderProps) {
   useSyncExternalStore(views.subscribe, views.version)
   const tabs = views.list()
   const activeId = useStore(s => s.view) ?? 'chat'
@@ -49,6 +59,77 @@ export function ConversationSession({
   const ancestry = useSessions(s => deriveAncestry(s, sessionId), equalBreadcrumbs)
   const composerPhase = useSession(s => s.composerPhase)
   const blank = useSession(s => s.blank)
+  const hideChrome = blank && composerPhase === 'blank'
+
+  return (
+    <header
+      className={clsx(css.header, hideChrome && css.headerHidden)}
+      aria-hidden={hideChrome || undefined}
+    >
+      {!hideChrome && (
+        <>
+          <div className={css.titleRow}>
+            <nav className={css.crumbs} aria-label={t('session.hierarchy')}>
+              {ancestry.map((summary, index) => {
+                const last = index === ancestry.length - 1
+                return (
+                  <span key={summary.id} className={css.crumbSeg}>
+                    {index > 0 && <span className={css.crumbSep}>/</span>}
+                    <button
+                      type="button"
+                      className={clsx(css.crumb, last && css.crumbCurrent)}
+                      disabled={last}
+                      onClick={() => { open(summary.id) }}
+                    >
+                      {summary.displayTitle}
+                    </button>
+                  </span>
+                )
+              })}
+              {ancestry.length === 0 && <span className={css.crumbCurrent}>{sessionId}</span>}
+            </nav>
+            <div className={css.headerActions}>
+              {renderSlot('conversation.session.header.actions', {})}
+            </div>
+          </div>
+          {tabs.length > 1 && (
+            <div className={css.tabs} role="tablist">
+              {tabs.map(viewTab => (
+                <button
+                  key={viewTab.id}
+                  type="button"
+                  role="tab"
+                  aria-selected={viewTab.id === active?.id}
+                  className={clsx(css.tab, viewTab.id === active?.id && css.tabActive)}
+                  onClick={() => { actions.setView(viewTab.id) }}
+                >
+                  {viewTab.label}
+                </button>
+              ))}
+            </div>
+          )}
+        </>
+      )}
+    </header>
+  )
+}
+
+/**
+ * Renders the active Session view inside the resident scrollport and keeps
+ * the input draft mirrored while blank Hero chrome is visible.
+ * @param props - Strict Session input/store, view ledger, and render shares.
+ * @returns the active view area, or null while the Session remains blank.
+ */
+export function ConversationSession({
+  useSession, useInput, inputActions, useStore, actions,
+  renderSlot, views, bindDraftMirror,
+}: ConversationSessionProps) {
+  useSyncExternalStore(views.subscribe, views.version)
+  const tabs = views.list()
+  const activeId = useStore(s => s.view) ?? 'chat'
+  const active = tabs.find(view => view.id === activeId) ?? tabs[0]
+  const composerPhase = useSession(s => s.composerPhase)
+  const blank = useSession(s => s.blank)
   const inputState = useInput(s => s)
   const storedDraft = useStore(s => s.draft)
   // `?? null`: persisted snapshots from before the inspect field rehydrate without it.
@@ -62,13 +143,8 @@ export function ConversationSession({
     // the machine mirror, not this seed effect.
   }, [inputActions])
 
-  // Blank hero/settling: keep the same header + body tree shape so a
-  // wrapActiveBody-hosted composer keeps its DOM identity across the first
-  // send (hero → active). Chrome is hidden; the draft-persistence mirror
-  // still runs because this component stays mounted.
-  const hideChrome = blank && composerPhase === 'blank'
-
-  const view: ReactNode = hideChrome ? null : (
+  if (blank && composerPhase === 'blank') return null
+  return (
     <div className={css.viewArea}>
       {active !== undefined && renderSlot('conversation.view', {
         inspect,
@@ -76,59 +152,4 @@ export function ConversationSession({
       }, { only: active.id })}
     </div>
   )
-
-  return (
-    <>
-      <header
-        className={clsx(css.header, hideChrome && css.headerHidden)}
-        aria-hidden={hideChrome || undefined}
-      >
-        {!hideChrome && (
-          <>
-            <div className={css.titleRow}>
-              <nav className={css.crumbs} aria-label={t('session.hierarchy')}>
-                {ancestry.map((summary, index) => {
-                  const last = index === ancestry.length - 1
-                  return (
-                    <span key={summary.id} className={css.crumbSeg}>
-                      {index > 0 && <span className={css.crumbSep}>/</span>}
-                      <button
-                        type="button"
-                        className={clsx(css.crumb, last && css.crumbCurrent)}
-                        disabled={last}
-                        onClick={() => { open(summary.id) }}
-                      >
-                        {summary.displayTitle}
-                      </button>
-                    </span>
-                  )
-                })}
-                {ancestry.length === 0 && <span className={css.crumbCurrent}>{sessionId}</span>}
-              </nav>
-              <div className={css.headerActions}>
-                {renderSlot('conversation.session.header.actions', {})}
-              </div>
-            </div>
-            {tabs.length > 1 && (
-              <div className={css.tabs} role="tablist">
-                {tabs.map(viewTab => (
-                  <button
-                    key={viewTab.id}
-                    type="button"
-                    role="tab"
-                    aria-selected={viewTab.id === active?.id}
-                    className={clsx(css.tab, viewTab.id === active?.id && css.tabActive)}
-                    onClick={() => { actions.setView(viewTab.id) }}
-                  >
-                    {viewTab.label}
-                  </button>
-                ))}
-              </div>
-            )}
-          </>
-        )}
-      </header>
-      {wrapActiveBody !== undefined ? wrapActiveBody(view) : view}
-    </>
-  )
 }

packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx

@@ -123,9 +123,9 @@ export function HeroShell({ t, children }: HeroShellProps) {
           <span className={css.previewBadge}>{t('hero.preview')}</span>
         </div>
         <div className={css.body}>
-          {/* The resident composer (ConversationRoot wrapActiveBody seat; the
-              workspace row rides the stack above the card) is CSS-centered in
-              the session scroll body during hero — see
+          {/* The resident composer (ConversationRoot's root-owned scrollport;
+              the workspace row rides the stack above the card) is CSS-centered
+              in that scroll body during hero — see
               ConversationRoot.module.css [data-phase='hero']. */}
         </div>
       </div>

packages/client/ui-conversation/tests/apply-inject.spec.tsx

@@ -21,7 +21,8 @@ import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type {
-  ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionInjected, DetailsInjected,
+  ChatViewInjected, ComposerBarInjected, ConversationInjected, ConversationSessionHeaderInjected,
+  ConversationSessionInjected, DetailsInjected,
 } from '@deepseek-ai/dsh-client-ui-conversation/client'
 import type { createChatStore } from '../src/client/stores.ts'
 
@@ -70,7 +71,7 @@ async function bench() {
   // The host face (store resolution) exists only inside the installed
   // renderer, so materialize it the way the shell does.
   runtime.renderRoot()
-  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
+  const entryOf = (key: 'conversation' | 'conversation.session' | 'conversation.session.header' | 'conversation.composer.bar' | 'conversation.view' | 'details') =>
     runtime.slots.entries(key)[0]!
   /** Resolve store instance + call the inject the way the outlet would. */
   const conversationSurface = (id: SessionId) => {
@@ -80,6 +81,13 @@ async function bench() {
       id, instance.actions)
     return { instance, injected }
   }
+  const conversationHeaderSurface = (id: SessionId) => {
+    const entry = entryOf('conversation.session.header')
+    const instance = runtime.storeOf('conversation.session.header', id) as ChatInstance
+    const injected = (entry.inject as unknown as (sessionId: SessionId, actions: ChatActions) => ConversationSessionHeaderInjected)(
+      id, instance.actions)
+    return { instance, injected }
+  }
   const residentSurface = (id: SessionId | undefined) => {
     const entry = entryOf('conversation')
     return (entry.inject as unknown as (sessionId: SessionId | undefined) => ConversationInjected)(id)
@@ -111,7 +119,7 @@ async function bench() {
   }
   return {
     runtime, feature, slots: runtime.slots, entryOf,
-    conversationSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
+    conversationSurface, conversationHeaderSurface, residentSurface, composerSurface, chatViewSurface, inputSurface,
     sessionFake, layoutFake,
   }
 }

packages/client/ui-conversation/tests/assembly-surfaces.spec.tsx

@@ -21,11 +21,12 @@
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, waitFor, within } from '@testing-library/react'
+import { useState } from 'react'
 import { LocaleService } from '@deepseek-ai/dsh-client-locale/client'
 import type { ISession, SessionId, TodoItem, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { PropsRenderSlots } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotTestRuntime, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
-import { apply, inject } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { apply, inject, type EmptyWorkspaceOwnerProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
 
 // The service reads its initial locale from the browser; these specs assert
 // the shipped Chinese copy, so they state the browser they assume.
@@ -83,6 +84,16 @@ const LAYOUT_CHILDREN = {
   'details': { kind: 'single', scope: 'session' },
 } as const
 
+/** Stateful occupant proving the root-scoped Hero workspace outlet is not rebuilt. */
+function WorkspaceProbe({ open }: EmptyWorkspaceOwnerProps) {
+  const [count, setCount] = useState(0)
+  return (
+    <button data-testid="workspace-probe" onClick={() => { setCount(value => value + 1) }}>
+      {String(open)}:{count}
+    </button>
+  )
+}
+
 async function bench(nodes: ToolResultNode[], opts?: { blank?: boolean }) {
   const runtime = await SlotTestRuntime.create()
   runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
@@ -188,6 +199,49 @@ describe('resident composer', () => {
     await runtime.dispose()
   })
 
+  it('keeps the complete Hero tree mounted when the first Workspace session appears', async () => {
+    const runtime = await SlotTestRuntime.create()
+    runtime.provide('layout', { openDetails: vi.fn(), closeDetails: vi.fn() })
+    const locale = new LocaleService(runtime.ctx)
+    runtime.provide('locale', locale)
+    runtime.slots.installLocale(locale)
+    await runtime.workspaces.update((draft) => {
+      draft.items = [{ workspaceId: 'w1', title: 'Proj', path: '/proj', sessionIds: [SID] }] as never
+    })
+    await runtime.root.declare(LAYOUT_CHILDREN, AppRoot)
+    await runtime.mount({ inject: [...inject], apply })
+    runtime.slots.register({ name: 'conversation.hero.workspace' }, WorkspaceProbe)
+    const view = runtime.renderRoot()
+
+    const root = view.container.querySelector('[data-phase="hero"]')!
+    const scrollBody = view.container.querySelector('[data-conversation-scroll]')!
+    const composerSeat = view.container.querySelector('[data-composer-seat]')!
+    const textarea = view.container.querySelector('textarea')!
+    const workspaceChip = view.getByRole('button', { name: '选择工作区' })
+    const workspaceProbe = view.getByTestId('workspace-probe')
+    expect(textarea.disabled).toBe(true)
+
+    fireEvent.click(workspaceChip)
+    fireEvent.click(workspaceProbe)
+    expect(workspaceProbe.textContent).toBe('true:1')
+
+    await runtime.sessions.add({
+      id: SID,
+      summary: { title: 'S', displayTitle: 'S', cwd: '/proj', blank: true },
+      snapshot: { blank: true, composerPhase: 'blank' },
+    })
+
+    expect(view.container.querySelector('[data-phase="hero"]')).toBe(root)
+    expect(view.container.querySelector('[data-conversation-scroll]')).toBe(scrollBody)
+    expect(view.container.querySelector('[data-composer-seat]')).toBe(composerSeat)
+    expect(view.container.querySelector('textarea')).toBe(textarea)
+    expect(view.getByRole('button', { name: '选择工作区' })).toBe(workspaceChip)
+    expect(view.getByTestId('workspace-probe')).toBe(workspaceProbe)
+    expect(workspaceProbe.textContent).toBe('true:1')
+    expect(textarea.disabled).toBe(false)
+    await runtime.dispose()
+  })
+
 
   it('the textarea survives the blank→active conversion as the same DOM node', async () => {
     const runtime = await bench([], { blank: true })

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

@@ -45,7 +45,7 @@ async function bench() {
 }
 
 /** First stored entry for a key (inject/store live directly on StoredEntry). */
-function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.view' | 'details') {
+function renderEntryOf(slots: Awaited<ReturnType<typeof bench>>['slots'], key: 'conversation' | 'conversation.session' | 'conversation.session.header' | 'conversation.view' | 'details') {
   return slots.entries(key)[0] as undefined | { inject?: unknown; store?: unknown }
 }
 
@@ -73,6 +73,7 @@ describe('apply wiring', () => {
     const b = await bench()
     const conversation = renderEntryOf(b.slots, 'conversation')
     const conversationSession = renderEntryOf(b.slots, 'conversation.session')
+    const conversationHeader = renderEntryOf(b.slots, 'conversation.session.header')
     const chatView = renderEntryOf(b.slots, 'conversation.view')
     const details = renderEntryOf(b.slots, 'details')
     expect(conversation?.inject).toBeTypeOf('function')
@@ -81,6 +82,7 @@ describe('apply wiring', () => {
     // The shared handle: one apply-built store value on ALL session entries
     // (the session-maybe 'conversation' shell carries no store by design).
     expect(conversationSession?.store).toBeDefined()
+    expect(conversationHeader?.store).toBe(conversationSession?.store)
     expect(details?.store).toBe(conversationSession?.store)
     expect(chatView?.store).toBe(conversationSession?.store)
     // The hero workspace picker hole rides the conversation entry's children

packages/client/ui-conversation/tests/selection-survival.spec.tsx

@@ -15,16 +15,17 @@ type ChatInstance = ReturnType<ReturnType<typeof createChatStore>['create']>
 async function bench() {
   const runtime = await SlotTestRuntime.create()
   const chat = createChatStore()
-  // The apply.ts shape: one shared handle across both strict-session slot
-  // registrations ('conversation.session'/'details'); the session-maybe
-  // 'conversation' shell carries no store by design. The slots must first
-  // exist in the ledger — the test root declares them (the AppFrame role).
+  // The apply.ts shape: one shared handle across the strict Session header,
+  // body, and details registrations; the session-maybe 'conversation' shell
+  // carries no store by design. The slots must first exist in the ledger.
   await runtime.root.declare({
     'conversation': { kind: 'single', scope: 'session-maybe' },
     'conversation.session': { kind: 'single', scope: 'session' },
+    'conversation.session.header': { kind: 'single', scope: 'session' },
     'details': { kind: 'single', scope: 'session' },
   }, (_p: { renderSlot?: unknown }) => null)
   runtime.slots.register({ name: 'conversation.session', store: chat }, () => null)
+  runtime.slots.register({ name: 'conversation.session.header', store: chat }, () => null)
   runtime.slots.register({ name: 'details', store: chat }, () => null)
   runtime.renderRoot() // materializes the host face storeOf resolves through
   return { runtime, chat }

packages/client/ui-conversation/tests/skeleton.spec.tsx

@@ -18,7 +18,7 @@ import { createChatStore } from '../src/client/stores.ts'
 import { SessionInputShell } from '../src/client/input/facade.ts'
 import { en, zh } from '../src/client/locales.ts'
 import { ConversationRoot } from '../src/client/skeleton/ConversationRoot.tsx'
-import { ConversationSession } from '../src/client/skeleton/ConversationSession.tsx'
+import { ConversationSession, ConversationSessionHeader } from '../src/client/skeleton/ConversationSession.tsx'
 import { HeroShell } from '../src/client/skeleton/EmptyHero.tsx'
 import { InputBar } from '../src/client/skeleton/InputBar.tsx'
 import type { InputBarProps } from '../src/client/skeleton/InputBar.tsx'
@@ -122,6 +122,33 @@ function mount(
   const renderSlot = ((key: string, owner: object, opts?: { only?: string }) => {
     slotCalls.push(key)
     if (key === 'conversation.hero.workspace') { pickerOwner = owner; return null }
+    if (key === 'conversation.session.header') {
+      return (
+        <ConversationSessionHeader
+          sessionId={SID}
+          SessionProvider={({ children }) => children(SID)}
+          useSession={useSession}
+          useSessions={props.useSessions}
+          useWorkspaces={props.useWorkspaces}
+          useProjection={(() => undefined)}
+          useInput={useInput}
+          inputActions={inputActions}
+          useStore={bindSnapshotSelector(chat)}
+          actions={chat.actions}
+          renderSlot={renderSlot as never}
+          views={{
+            list: () => [
+              { id: 'chat', label: 'Chat' },
+              { id: 'trajectory', label: 'Trajectory' },
+            ],
+            subscribe: () => () => {},
+            version: () => 1,
+          }}
+          open={open}
+          t={t}
+        />
+      )
+    }
     if (key === 'conversation.session') {
       return (
         <ConversationSession
@@ -145,9 +172,6 @@ function mount(
             version: () => 1,
           }}
           bindDraftMirror={write => wiring.bindMirror(write)}
-          open={open}
-          t={t}
-          {...owner}
         />
       )
     }
@@ -340,7 +364,7 @@ describe('ConversationRoot resident composer', () => {
     const before = b.view.getByRole('textbox')
     fireEvent.change(before, { target: { value: 'kept across flip' } })
     // First message landed: content exists, phase leaves blank. Composer
-    // already sat in the Session scrollport during hero, so the textarea
+    // already sat in the resident scrollport during hero, so the textarea
     // node and InputHub draft both survive.
     b.session.set(conversationSnapshot({ composerPhase: 'active', blank: false }))
     b.rerender()

packages/client/ui-trajectory/tests/views.spec.tsx

@@ -21,7 +21,10 @@ import type {
   SessionHistorySnapshot, SessionId, SessionListState, WorkspaceListState,
 } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConvViewProps, ViewTab } from '@deepseek-ai/dsh-client-ui-conversation/client'
-import { ConversationSession, type ConversationSessionProps } from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationSession.tsx'
+import {
+  ConversationSession, ConversationSessionHeader,
+  type ConversationSessionHeaderProps, type ConversationSessionProps,
+} from '@deepseek-ai/dsh-client-ui-conversation/src/client/skeleton/ConversationSession.tsx'
 import { createChatStore } from '@deepseek-ai/dsh-client-ui-conversation/src/client/stores.ts'
 import { zh as conversationZh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.ts'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-trajectory/client'
@@ -35,12 +38,9 @@ import { createTrajectoryDurationStore } from '../src/client/duration-store.ts'
 import { deriveTrajectoryTimeline } from '../src/client/timeline.ts'
 
 const SID = 's1' as SessionId
-
-// Stub of the conversation package's standard locale seat (this spec mounts
-// its ConversationSession chrome); answers from the zh dictionary and falls
-// back to the key like the real chain.
-const tConversation: ConversationSessionProps['t'] =
+const tConversation: ConversationSessionHeaderProps['t'] =
   key => (conversationZh as Record<string, string>)[key] ?? key
+
 afterEach(cleanup)
 // The chat store persists under its declared key; clear so one case's active
 // view cannot rehydrate into the next.
@@ -180,7 +180,7 @@ function tabsOf(slots: SlotsService): ViewTab[] {
     .map(e => ({ id: e.options.id!, label: resolveSlotLabel(e.options.label) ?? e.options.id! }))
 }
 
-/** Mount the strict session content over the ring ledger with an outlet-faithful renderSlot. */
+/** Mount the strict Session header/body over the ring ledger with outlet-faithful render shares. */
 function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES) {
   const sessionSnapshot = createSnapshotStore({
     running: false, removed: false, promptError: null, nodes,
@@ -190,6 +190,13 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
   })
   const useSession = bindSnapshotSelector(sessionSnapshot) as unknown as UseSession<ConversationSnapshot>
   const chat = createChatStore().create()
+  const views = {
+    list: () => tabsOf(slots),
+    subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
+    version: () => slots.getVersion('conversation.view'),
+  }
+  const useInput = bindSnapshotSelector(createSnapshotStore({ draft: '', draftRev: 0, phase: 'plain', queue: [] })) as never
+  const inputActions = { setDraft: vi.fn(), submit: vi.fn() }
   // Minimal outlet twin: resolve the ring entry by the `only` filter and
   // render it with the session standard kit (what SlotOutlet does for a
   // list-kind session slot, minus machinery).
@@ -222,27 +229,39 @@ function mount(slots: SlotsService, nodes: ConversationSnapshot['nodes'] = NODES
     )
   }) as unknown as ConversationSessionProps['renderSlot']
   return render(
-    <ConversationSession
-      sessionId={SID}
-      t={tConversation}
-      SessionProvider={({ children }) => children(SID)}
-      useSession={useSession}
-      useSessions={emptySessions()}
-      useWorkspaces={emptyWorkspaces()}
-      useProjection={(() => undefined)}
-      useStore={bindSnapshotSelector(chat)}
-      actions={chat.actions}
-      renderSlot={renderSlot}
-      views={{
-        list: () => tabsOf(slots),
-        subscribe: (fn: () => void) => slots.subscribe('conversation.view', fn),
-        version: () => slots.getVersion('conversation.view'),
-      }}
-      useInput={bindSnapshotSelector(createSnapshotStore({ draft: '', draftRev: 0, phase: 'plain', queue: [] })) as never}
-      inputActions={{ setDraft: vi.fn(), submit: vi.fn() }}
-      bindDraftMirror={() => () => {}}
-      open={vi.fn()}
-    />,
+    <>
+      <ConversationSessionHeader
+        sessionId={SID}
+        SessionProvider={({ children }) => children(SID)}
+        useSession={useSession}
+        useSessions={emptySessions()}
+        useWorkspaces={emptyWorkspaces()}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        renderSlot={() => null}
+        views={views}
+        useInput={useInput}
+        inputActions={inputActions}
+        open={vi.fn()}
+        t={tConversation}
+      />
+      <ConversationSession
+        sessionId={SID}
+        SessionProvider={({ children }) => children(SID)}
+        useSession={useSession}
+        useSessions={emptySessions()}
+        useWorkspaces={emptyWorkspaces()}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        renderSlot={renderSlot}
+        views={views}
+        useInput={useInput}
+        inputActions={inputActions}
+        bindDraftMirror={() => () => {}}
+      />
+    </>,
   )
 }
 

packages/client/ui-workspace/src/client/locales.ts

@@ -49,6 +49,7 @@ export const zh = {
   'status.waitingApproval': '等待审批',
   'status.planReview': '计划待审',
   'status.waitingAnswer': '等待回答',
+  'status.completed': '已完成',
   'hover.created': '创建于 {time}',
   'hover.copied': '已复制',
   'date.ymd': '{y}年{m}月{d}日',
@@ -109,6 +110,7 @@ export const en = {
   'status.waitingApproval': 'Waiting for approval',
   'status.planReview': 'Plan awaiting review',
   'status.waitingAnswer': 'Waiting for answer',
+  'status.completed': 'Completed',
   'hover.created': 'Created {time}',
   'hover.copied': 'Copied',
   'date.ymd': '{y}-{m}-{d}',

packages/client/ui-workspace/src/client/rows/Rows.tsx

@@ -173,7 +173,7 @@ function assertNever(value: never): never {
 
 /** Session status presentation; pending user interaction outranks the running state. */
 function sessionStatus(
-  node: Pick<SessionNode, 'pendingInteraction' | 'running'>,
+  node: Pick<SessionNode, 'pendingInteraction' | 'running' | 'completed'>,
   t: RowTranslate,
 ): { state: StateDotState; label: string } {
   switch (node.pendingInteraction) {
@@ -185,10 +185,11 @@ function sessionStatus(
     default: return assertNever(node.pendingInteraction)
   }
   if (node.running) return { state: 'ongoing', label: t('status.running') }
+  if (node.completed) return { state: 'done', label: t('status.completed') }
   return { state: 'done', label: t('status.idle') }
 }
 
-/** Hover-card body: full title, relative time, and interaction/running/idle status. */
+/** Hover-card body: full title, relative time, and interaction/running/completed/idle status. */
 function SessionHoverContent({ node, now, t }: { node: SessionNode; now: number; t: RowTranslate }) {
   const status = sessionStatus(node, t)
   return (
@@ -251,7 +252,7 @@ export function SearchResultItem({ result, currentId, onOpen, t }: {
     >
       <span className={css.searchResultHeading}>
         <span className={css.slot}>
-          {status.state !== 'done' && (
+          {(status.state !== 'done' || result.completed) && (
             <>
               <StateDot state={status.state} />
               <span className={css.visuallyHidden}>{status.label}</span>
@@ -351,8 +352,11 @@ export function SessionNodeItem({ node, currentId, now, onOpen, onRename, onFork
           drag.drop(rowHalf(e))
         }}
     >
+      {/* Pending interactions and running outrank the idle state; a
+          finished-but-unviewed session shows the green done reminder dot
+          (cleared by opening the session). */}
       <span className={css.slot}>
-        {status.state !== 'done' && (
+        {(status.state !== 'done' || row.completed) && (
           <>
             <StateDot state={status.state} />
             <span className={css.visuallyHidden}>{status.label}</span>

packages/client/ui-workspace/src/client/tree.ts

@@ -24,6 +24,8 @@ export interface SessionNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+  completed: boolean
   updatedAt: number
 }
 
@@ -54,6 +56,8 @@ export interface SearchResultNode {
   /** The runtime Session list reports an interaction awaiting this user. */
   pendingInteraction?: PendingInteractionStatus
   running: boolean
+  /** Finished running while not selected and not yet opened (the green "done" reminder dot). */
+  completed: boolean
   snippet?: string
 }
 
@@ -175,6 +179,7 @@ function sessionNode(s: SessionSummary): SessionNode {
     title: sessionTitle(s),
     blank: s.blank,
     running: s.running,
+    completed: s.completed === true,
     updatedAt: s.updatedAt,
     ...(s.pendingInteraction === undefined ? {} : { pendingInteraction: s.pendingInteraction }),
   }
@@ -330,6 +335,7 @@ export function deriveSearchResults(
         ...(summary.pendingInteraction === undefined
           ? {}
           : { pendingInteraction: summary.pendingInteraction }),
+        completed: summary.completed === true,
         ...match === undefined ? {} : { snippet: match.snippet },
       }
     }),

packages/client/ui-workspace/tests/rows.spec.tsx

@@ -64,6 +64,7 @@ describe('workspace browser rows', () => {
       title: 'Result title',
       workspace: 'Workspace context',
       running: true,
+      completed: false,
       snippet: 'matching message excerpt',
     }
     render(<SearchResultItem result={result} currentId={result.id} onOpen={onOpen} t={t} />)
@@ -85,7 +86,7 @@ describe('workspace browser rows', () => {
   ] as const)('shows %s ahead of running in search results', (pendingInteraction, label) => {
     const result: SearchResultNode = {
       id: sid(pendingInteraction), title: 'Needs input', workspace: 'Project',
-      pendingInteraction, running: true,
+      pendingInteraction, running: true, completed: false,
     }
     render(<SearchResultItem result={result} currentId={undefined} onOpen={vi.fn()} t={t} />)
     const row = screen.getByRole('treeitem')
@@ -114,7 +115,7 @@ describe('workspace browser rows', () => {
 
   it('renders and opens a selected running Session row', () => {
     const node: SessionNode = {
-      id: sid('session'), title: 'Session', blank: false, running: true, updatedAt: 0,
+      id: sid('session'), title: 'Session', blank: false, running: true, completed: false, updatedAt: 0,
     }
     const onOpen = vi.fn()
     render(
@@ -130,6 +131,38 @@ describe('workspace browser rows', () => {
     expect(onOpen).toHaveBeenCalledWith(node.id)
   })
 
+  it('shows the green done dot only on a finished, unviewed session (running wins the slot)', () => {
+    const renderRow = (over: Partial<SessionNode>) => render(
+      <SessionNodeItem
+        node={{ id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0, ...over }}
+        currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t}
+      />,
+    )
+    const stateDot = (view: ReturnType<typeof renderRow>) =>
+      view.container.querySelector('[data-state]')
+    // No completion reminder, not running: no state dot at all.
+    const plain = renderRow({})
+    expect(stateDot(plain)).toBeNull()
+    plain.unmount()
+    // Completed while unviewed: the green done dot.
+    const done = renderRow({ completed: true })
+    expect(done.container.querySelector('[data-state="done"]')).not.toBeNull()
+    done.unmount()
+    // Running wins the slot: the animated ongoing dot, no done dot.
+    const running = renderRow({ completed: true, running: true })
+    expect(running.container.querySelector('[data-state="ongoing"]')).not.toBeNull()
+    expect(running.container.querySelector('[data-state="done"]')).toBeNull()
+  })
+
+  it('shows the green done dot on a finished search result row', () => {
+    render(<SearchResultItem
+      result={{ id: sid('result'), title: 'Done', workspace: 'Workspace', running: false, completed: true }}
+      currentId={undefined} onOpen={vi.fn()} t={t}
+    />)
+    expect(screen.getByRole('treeitem').querySelector('[data-state="done"]')).not.toBeNull()
+  })
+
   it('workspace row menu opens on the ellipsis, renames, and shows the danger delete row', () => {
     const onRename = vi.fn()
     const onDelete = vi.fn()
@@ -198,7 +231,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s-blank'), title: 'ignored', blank: true, running: false, updatedAt: 0,
+        id: sid('s-blank'), title: 'ignored', blank: true, running: false, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={node.id} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -224,7 +257,7 @@ describe('workspace browser rows', () => {
     const onFork = vi.fn()
     const onArchive = vi.fn()
     const node: SessionNode = {
-      id: sid('s1'), title: 'One', blank: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'One', blank: false, running: false, completed: false, updatedAt: 0,
     }
     render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={onOpen}
       onRename={onRename} onFork={onFork} onArchive={onArchive} t={t} />)
@@ -257,7 +290,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Hovered', blank: false, running: true, updatedAt: 0,
+        id: sid('s1'), title: 'Hovered', blank: false, running: true, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={60_000} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -288,7 +321,7 @@ describe('workspace browser rows', () => {
     try {
       const node: SessionNode = {
         id: sid(pendingInteraction), title: 'Needs input', blank: false,
-        pendingInteraction, running: true, updatedAt: 0,
+        pendingInteraction, running: true, completed: false, updatedAt: 0,
       }
       const view = render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -314,7 +347,7 @@ describe('workspace browser rows', () => {
     vi.useFakeTimers()
     try {
       const node: SessionNode = {
-        id: sid('s1'), title: 'Quiet', blank: false, running: false, updatedAt: 0,
+        id: sid('s1'), title: 'Quiet', blank: false, running: false, completed: false, updatedAt: 0,
       }
       render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
         onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
@@ -327,9 +360,26 @@ describe('workspace browser rows', () => {
     }
   })
 
+  it('completed hover card shows the Completed status line', () => {
+    vi.useFakeTimers()
+    try {
+      const node: SessionNode = {
+        id: sid('s1'), title: 'Done', blank: false, running: false, completed: true, updatedAt: 0,
+      }
+      render(<SessionNodeItem node={node} currentId={undefined} now={0} onOpen={vi.fn()}
+        onRename={vi.fn()} onFork={vi.fn()} onArchive={vi.fn()} t={t} />)
+      fireEvent.pointerEnter(screen.getByRole('treeitem').parentElement as HTMLElement)
+      act(() => { vi.advanceTimersByTime(500) })
+      // Row's visually-hidden reminder label plus the hover card's status line.
+      expect(screen.getAllByText('已完成')).toHaveLength(2)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
   it('draggable row wires start/end and gates hover/drop on an active same-group drag', () => {
     const node: SessionNode = {
-      id: sid('s1'), title: 'Drag me', blank: false, running: false, updatedAt: 0,
+      id: sid('s1'), title: 'Drag me', blank: false, running: false, completed: false, updatedAt: 0,
     }
     const inactive = dragProps()
     const { rerender } = render(

packages/client/ui-workspace/tests/tree.spec.ts

@@ -77,6 +77,22 @@ describe('deriveGroups', () => {
     expect(strayGroups.map(group => group.key)).toEqual(['first'])
   })
 
+  it('projects the completion reminder into session and search rows (absent = false)', () => {
+    const done = { ...summary('done', 3), completed: true }
+    const plain = summary('plain', 2)
+    const sessions = list(done, plain)
+    const groups = deriveGroups(
+      sessions, [workspace('first', ['done', 'plain'])], noArchive, view(['first']),
+    )
+    const doneNode = groups[0]!.sessions.find(session => session.id === done.id)!
+    const plainNode = groups[0]!.sessions.find(session => session.id === plain.id)!
+    expect(doneNode.completed).toBe(true)
+    expect(plainNode.completed).toBe(false)
+    expect(deriveFlat(sessions, noArchive).find(node => node.id === done.id)!.completed).toBe(true)
+    const search = deriveSearchResults(sessions, [workspace('first', ['done', 'plain'])], 'done', noArchive, { items: [], hasMore: false }, 10)
+    expect(search.items[0]?.completed).toBe(true)
+  })
+
   it('hides subagent-origin sessions without hiding ordinary forks', () => {
     const parent = summary('parent', 1)
     const fork = { ...summary('fork', 2), parentId: parent.id }
@@ -259,6 +275,7 @@ describe('deriveSearchResults', () => {
           workspace: 'Alpha',
           running: false,
           pendingInteraction: 'plan-review',
+          completed: false,
           snippet: 'title session body excerpt',
         },
         {
@@ -266,12 +283,14 @@ describe('deriveSearchResults', () => {
           title: 'Ordinary title',
           workspace: 'Needle Workspace',
           running: false,
+          completed: false,
         },
         {
           id: contentHit.id,
           title: 'content-hit',
           workspace: 'c',
           running: false,
+          completed: false,
           snippet: 'body needle excerpt',
         },
       ],

packages/compact/compact-basic/src/index.ts

@@ -144,9 +144,7 @@ export class BasicCompactService extends CompactService {
     }
 
     ctx.on('agent/pre-step', async (
-      agent: Agent,
-      _messages,
-      { signal },
+      { agent, signal },
       next,
     ): Promise<PreStepDecision> => {
       if (!signal.aborted) {
@@ -165,7 +163,7 @@ export class BasicCompactService extends CompactService {
       return next()
     })
 
-    ctx.on('agent/status', (agent, status) => {
+    ctx.on('agent/status', ({ agent, status }) => {
       if (status === 'idle') this.overflowRetries.delete(agent)
     })
 
@@ -178,12 +176,9 @@ export class BasicCompactService extends CompactService {
     })
 
     ctx.on('agent/request-error', async (
-      agent,
-      context,
-      signal,
+      { agent, failure, signal },
       next,
     ) => {
-      const { failure } = context
       if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next()
       this.overflowAgents.set(agent.session, agent)
       const target = routedTarget(agent.session)

packages/compact/compact-basic/tests/compact-basic.spec.ts

@@ -1372,7 +1372,7 @@ describe('default one-shot summarizer', () => {
 describe('automatic listener and loader composition', () => {
   function preStep(ctx: Context, owner: Agent, signal = SIGNAL) {
     return agentEvents(ctx, owner).waterfall(
-      'agent/pre-step', [], { turn: 1, step: 1, signal },
+      'agent/pre-step', { messages: [], turn: 1, step: 1, signal },
       () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
     )
   }
@@ -1388,8 +1388,7 @@ describe('automatic listener and loader composition', () => {
     const turn = owner.session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 1
     return agentEvents(ctx, owner).waterfall(
       'agent/request-error',
-      { turn, step: 1, provider: 'test', failure, retryPolicy: undefined },
-      signal,
+      { turn, step: 1, provider: 'test', failure, retryPolicy: undefined, signal },
       next,
     ).then(action => action?.kind === 'retry')
   }

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -175,7 +175,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -217,7 +217,7 @@ function overflowHistorySeed(): SessionEvent[] {
 describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', () => {
   it('uses the model actually routed by agent/request for post-step pressure', async () => {
     const { ctx } = await harness(8)
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => ({
+    ctx.on('agent/request', async (_payload, next) => ({
       ...await next(), provider: 'mock', model: 'mock',
     }))
     try {
@@ -315,7 +315,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
       await ctx.plugin(AgentLoop, { agents: [] })
       await ctx.plugin(TokenMeterService)
       ctx.llm.registerAdapter(['mock'], adapter)
-      ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => ({
+      ctx.on('agent/request', async (_payload, next) => ({
         ...await next(), provider: 'mock', model: 'mock',
       }))
       await ctx.plugin(BasicCompactService, {

packages/context/time-context/src/index.ts

@@ -157,9 +157,7 @@ export function apply(ctx: Context, config: Config): void {
   const resolvedTimeZone = formatter.resolvedOptions().timeZone
 
   ctx.on('agent/pre-step', async (
-    agent: Agent,
-    _messages,
-    { turn, step, signal },
+    { agent, turn, step, signal },
     next,
   ): Promise<PreStepDecision> => {
     const decision = await next()

packages/context/time-context/tests/time-context.spec.ts

@@ -82,8 +82,7 @@ async function fire(
 ): Promise<void> {
   const decision = await agentEvents(ctx, agent).waterfall(
     'agent/pre-step',
-    [],
-    { turn, step, signal },
+    { messages: [], turn, step, signal },
     () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
   )
   if (decision.kind === 'enter') {
@@ -378,7 +377,7 @@ describe('real agent-loop request history', () => {
   ] as const)('does not commit a preparation reading when a downstream pre-step listener %s', async (mode) => {
     const adapter = new ScriptedAdapter([textResponse('unused')])
     const ctx = await loopHarness(adapter)
-    ctx.on('agent/pre-step', (subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (mode === 'throws') throw new Error('later pre-step failure')
       subject.cancel({ kind: 'user' })
       return next()

packages/context/tmux-context/src/index.ts

@@ -216,9 +216,7 @@ export function apply(ctx: Context, config: Config): void {
   validateRefreshInterval(refreshIntervalMs)
 
   ctx.on('agent/pre-step', async (
-    agent: Agent,
-    _messages,
-    { turn, step, signal },
+    { agent, turn, step, signal },
     next,
   ): Promise<PreStepDecision> => {
     const decision = await next()

packages/context/tmux-context/tests/tmux-context.spec.ts

@@ -138,8 +138,7 @@ async function fire(
 ): Promise<void> {
   const decision = await agentEvents(ctx, agent).waterfall(
     'agent/pre-step',
-    [],
-    { turn, step, signal },
+    { messages: [], turn, step, signal },
     () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
   )
   if (decision.kind === 'enter') {

packages/context/workspace-context/src/index.ts

@@ -213,9 +213,7 @@ export function apply(ctx: Context, config: Config): void {
   }
 
   ctx.on('agent/pre-step', async (
-    agent: Agent,
-    messages,
-    { step, signal },
+    { agent, messages, step, signal },
     next,
   ): Promise<PreStepDecision> => {
     const decision = await next()

packages/context/workspace-context/tests/workspace-context.e2e.ts

@@ -57,7 +57,7 @@ async function harness(): Promise<{ ctx: Context; agent: Agent }> {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()

packages/context/workspace-context/tests/workspace-context.spec.ts

@@ -209,8 +209,7 @@ async function workspaceContextOf(agent: Agent): Promise<UserMessage> {
 
 async function syncWorkspaceContext(ctx: Context, agent: Agent): Promise<void> {
   await agentEvents(ctx, agent).waterfall(
-    'agent/pre-step', [],
-    { turn: 1, step: 1, signal: testToolSignal },
+    'agent/pre-step', { messages: [], turn: 1, step: 1, signal: testToolSignal },
     async () => ({ kind: 'enter' as const, messages: [] }),
   )
 }
@@ -245,15 +244,13 @@ async function composeBaselinePrefix(ctx: Context, agent: Agent): Promise<Messag
   const signal = AbortSignal.timeout(1000)
   await agentEvents(ctx, agent).waterfall(
     'agent/pre-step',
-    [],
-    { turn: 1, step: 1, signal },
+    { messages: [], turn: 1, step: 1, signal },
     () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
   )
   const claimed = agent.inbox.claim('next-step', 1)
   const decision = await agentEvents(ctx, agent).waterfall(
     'agent/pre-step',
-    claimed,
-    { turn: 1, step: 2, signal },
+    { messages: claimed, turn: 1, step: 2, signal },
     () => Promise.resolve({ kind: 'enter' as const, messages: claimed }),
   )
   const entered = decision.kind === 'enter' ? decision.messages : []
@@ -969,8 +966,7 @@ describe('workspace context request injection', () => {
       const original = stubAgent(root)
       await agentEvents(ctx, original).waterfall(
         'agent/pre-step',
-        [],
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
       )
       const inserted = original.inbox.nextStep[0]
@@ -979,12 +975,11 @@ describe('workspace context request injection', () => {
       await fiber.dispose()
       await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
       const resumed = stubAgent(root, [...original.session.events])
-      agentEvents(ctx, resumed).emit('agent/session-start', 'resume')
+      agentEvents(ctx, resumed).emit('agent/session-start', { source: 'resume' })
       const claimed = resumed.inbox.claim('next-step', 1)
       const decision = await agentEvents(ctx, resumed).waterfall(
         'agent/pre-step',
-        claimed,
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: claimed }),
       )
       if (decision.kind !== 'enter') throw new Error('recovered baseline was rejected')
@@ -1016,8 +1011,7 @@ describe('workspace context request injection', () => {
       const original = stubAgent(root)
       await agentEvents(ctx, original).waterfall(
         'agent/pre-step',
-        [],
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
       )
       const stale = original.inbox.nextStep[0]
@@ -1027,12 +1021,11 @@ describe('workspace context request injection', () => {
       await fiber.dispose()
       await ctx.plugin(workspaceContext, { dshHome: home, maxBytes: 65536 })
       const resumed = stubAgent(root, [...original.session.events])
-      agentEvents(ctx, resumed).emit('agent/session-start', 'resume')
+      agentEvents(ctx, resumed).emit('agent/session-start', { source: 'resume' })
       const staleClaim = resumed.inbox.claim('next-step', 1)
       const staleDecision = await agentEvents(ctx, resumed).waterfall(
         'agent/pre-step',
-        staleClaim,
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: staleClaim, turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: staleClaim }),
       )
 
@@ -1071,8 +1064,7 @@ describe('workspace context request injection', () => {
       const original = stubAgent(root)
       await agentEvents(originalCtx, original).waterfall(
         'agent/pre-step',
-        [],
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
       )
       const stale = original.inbox.nextStep[0]
@@ -1082,12 +1074,11 @@ describe('workspace context request injection', () => {
       if (provideFs) await resumedCtx.plugin(LocalFileSystem, { cwd: '/' })
       await resumedCtx.plugin(workspaceContext, { dshHome: home, maxBytes })
       const resumed = stubAgent(root, [...original.session.events])
-      agentEvents(resumedCtx, resumed).emit('agent/session-start', 'resume')
+      agentEvents(resumedCtx, resumed).emit('agent/session-start', { source: 'resume' })
       const claimed = resumed.inbox.claim('next-step', 1)
       const decision = await agentEvents(resumedCtx, resumed).waterfall(
         'agent/pre-step',
-        claimed,
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: claimed, turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve({ kind: 'enter' as const, messages: claimed }),
       )
 
@@ -1191,8 +1182,7 @@ describe('workspace context request injection', () => {
 
       const decision = await agentEvents(ctx, agent).waterfall(
         'agent/pre-step',
-        [prompt],
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: [prompt], turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve(downstream),
       )
 
@@ -1249,8 +1239,7 @@ describe('workspace context request injection', () => {
 
       const decision = await agentEvents(ctx, agent).waterfall(
         'agent/pre-step',
-        [],
-        { turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
+        { messages: [], turn: 1, step: 1, signal: AbortSignal.timeout(1000) },
         () => Promise.resolve(downstream),
       )
 
@@ -1356,7 +1345,7 @@ describe('workspace context request injection', () => {
       const resumed = stubAgent(root, [...original.session.events])
 
       // Resume announces its lifecycle start before the first step.
-      agentEvents(ctx, resumed).emit('agent/session-start', 'resume')
+      agentEvents(ctx, resumed).emit('agent/session-start', { source: 'resume' })
       await composeBaselinePrefix(ctx, resumed)
 
       const baselines = baselineEvents(resumed)
@@ -1404,7 +1393,7 @@ describe('workspace context request injection', () => {
       await write(join(root, 'AGENTS.md'), 'repo rule')
       const ctx = new Context()
       await mountWorkspaceContext(ctx, { dshHome: home, maxBytes: 65536 })
-      ctx.on('agent/pre-step', async (_agent, _messages, _context, next) => {
+      ctx.on('agent/pre-step', async (_payload, next) => {
         const decision = await next()
         if (decision.kind === 'reject') return decision
         return {
@@ -1678,8 +1667,7 @@ describe('workspace context request injection', () => {
       const reason = new Error('cancel prefix')
       const pending = agentEvents(ctx, stubAgent(root)).waterfall(
         'agent/pre-step',
-        [],
-        { turn: 1, step: 1, signal: controller.signal },
+        { messages: [], turn: 1, step: 1, signal: controller.signal },
         () => Promise.resolve({ kind: 'enter' as const, messages: [] }),
       )
 
@@ -3868,8 +3856,7 @@ describe('workspace context inbox synchronization', () => {
       controller.abort(new Error('abort pre-step reconciliation'))
 
       await expect(agentEvents(ctx, agent).waterfall(
-        'agent/pre-step', [],
-        { turn: 1, step: 1, signal: controller.signal },
+        'agent/pre-step', { messages: [], turn: 1, step: 1, signal: controller.signal },
         async () => ({ kind: 'enter' as const, messages: [] }),
       )).rejects.toThrow('abort pre-step reconciliation')
 
@@ -3979,8 +3966,7 @@ describe('workspace context inbox synchronization', () => {
       const downstream = { kind: 'enter' as const, messages: claimed }
 
       const decision = await agentEvents(ctx, agent).waterfall(
-        'agent/pre-step', claimed,
-        { turn: 1, step: 1, signal: testToolSignal },
+        'agent/pre-step', { messages: claimed, turn: 1, step: 1, signal: testToolSignal },
         async () => downstream,
       )
 

packages/cordis/repository-plugin/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/cordis/repository-plugin/README.md
-README.md: 2555876734ddcab7b0bc0f25780010bef0c97a01
-README.zh.md: 41341f7d7ed92ac071dde274a0328784bc2888d4
+README.md: 33cd763d7dbe21b72f9e604b7b2e313081cf656f
+README.zh.md: 903dfbe601cc76acb0c1e87453dc03ef0321409b

packages/cordis/repository-plugin/README.md

@@ -30,7 +30,7 @@ Place an ordinary package in the repository's `.dsh-plugin` directory:
 
 ## Standalone app configuration
 
-The shipped `dsh` base used by raw-config, Web, and headless modes contains an empty `repository-plugins` row. A Web or headless user enables exact GitHub generations by replacing that row's config in `$DSH_HOME/config.yaml` (default `~/.dsh/config.yaml`); a raw-config deployment patches the same row in its explicit overlay:
+The shipped `dsh-base` bundle every profile starts from contains an empty `repository-plugins` row. A user enables exact GitHub generations by replacing that row's config in a user patch layer — `$DSH_HOME/profiles/<name>/cordis.patch.yml`, or the home-level `$DSH_HOME/cordis.patch.yml` shared by every profile; a `--patch` overlay patches the same row for one run:
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@ The shipped `dsh` base used by raw-config, Web, and headless modes contains an e
 
 Each source must use `github:owner/repository#<ref>`. Omitting `&path:` selects `/.dsh-plugin`; an explicit path is absolute within the repository and must end in `.dsh-plugin`. A commit ref gives the clearest immutable identity, while tags and branches remain accepted exact config values. `cacheDir` may override the default `$DSH_HOME/cache/repository-plugins` cache root.
 
-Web watches `config.yaml` through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. Headless reads the file only at startup, and raw-config mode reads only its explicit overlay. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
+Long-lived surfaces watch both `cordis.patch.yml` layers through Cordis HMR. A valid source-list change installs and swaps the complete repository Plugin generation; a failed fetch, prepare, import, or Plugin application keeps the last good tree and broadcasts `hmr/config-update-failed(filename, error)`. One-shot runs read the layers only at startup, and a `--patch` overlay is never watched. An identical source string permanently reuses its prepared cache entry, so selecting changed code requires a ref, path, or other source-config change. App integration rationale: [config-only repository Plugins Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md).
 
 ## Preparation
 

packages/cordis/repository-plugin/README.zh.md

@@ -30,7 +30,7 @@
 
 ## 独立应用配置
 
-随附 `dsh` 中供原始配置、Web 与无头模式使用的基础配置包含一个空 `repository-plugins` 配置项。Web 或无头用户可在 `$DSH_HOME/config.yaml`（默认 `~/.dsh/config.yaml`）中替换该配置项的配置，以启用精确指定的 GitHub generation；原始配置部署则在显式 overlay 中 patch 同一配置项：
+每个 profile 都以之为起点的随附 `dsh-base` 组合包包含一个空 `repository-plugins` 配置项。用户可在用户 patch 层中替换该配置项的配置来启用精确指定的 GitHub generation：写入 `$DSH_HOME/profiles/<name>/cordis.patch.yml`，或写入各 profile 共享的 home 级 `$DSH_HOME/cordis.patch.yml`；`--patch` overlay 则只为单次运行 patch 同一配置项：
 
 ```yaml
 - id: repository-plugins
@@ -43,7 +43,7 @@
 
 每个源都必须采用 `github:owner/repository#<ref>`。省略 `&path:` 时选择 `/.dsh-plugin`；显式路径是仓库内的绝对路径，并且必须以 `.dsh-plugin` 结尾。commit ref 提供最清晰的不可变身份；tag 和 branch 仍可作为精确配置值使用。`cacheDir` 可覆盖默认缓存根 `$DSH_HOME/cache/repository-plugins`。
 
-Web 通过 Cordis HMR（热模块替换）监视 `config.yaml`。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。无头模式只在启动时读取该文件，原始配置模式只读取其显式 overlay。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
+长期运行的 surface 通过 Cordis HMR（热模块替换）监视两个 `cordis.patch.yml` 层。有效的源列表变更会安装并替换整套 repository Plugin generation；拉取、准备、导入或插件应用失败时，最后一个可用树保持运行，并广播 `hmr/config-update-failed(filename, error)`。一次性运行只在启动时读取这些层，`--patch` overlay 则从不被监视。相同的源字符串会永久复用其已准备缓存条目，因此必须改变 ref、路径或其他源配置，才能选择发生变化的代码。应用集成依据见[仅凭配置接入 repository Plugin 的 Agent Note](../../../.agents/notes/implemented/feature/2026-07-30-config-only-repository-plugins.md)。
 
 ## 准备阶段
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -396,9 +396,17 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'registerUpgrade(route: WebUpgradeRoute): () => void',
         jsDoc: '/**\n * Register an exact-path HTTP upgrade route. Duplicate paths throw because\n * one socket can have only one protocol owner.\n * @param route - pathname and handler owning negotiation plus socket use.\n * @returns the disposer removing the route.\n */',
       },
+      {
+        signature: 'registerFallback(handler: WebRoute[\'handler\']): () => void',
+        jsDoc: '/**\n * Claim the fallback seat: the handler answering every request no named\n * route matches (the SPA dist server in the shipped Web composition). One\n * owner only — a second registration throws, because two fallbacks cannot\n * compose.\n * @param handler - owns the full response lifecycle of unmatched requests.\n * @returns the disposer releasing the seat.\n */',
+      },
       {
         signature: 'tapIndex(transform: (html: string) => string): () => void',
-        jsDoc: '/**\n * Register an index.html transform, applied to every index response in\n * registration order.\n * @param transform - pure html-to-html function.\n * @returns the disposer removing the transform.\n */',
+        jsDoc: '/**\n * Register an index.html transform, applied by the fallback owner to every\n * index response ({@link applyIndexTaps}) in registration order.\n * @param transform - pure html-to-html function.\n * @returns the disposer removing the transform.\n */',
+      },
+      {
+        signature: 'applyIndexTaps(html: string): string',
+        jsDoc: '/**\n * Run an index.html body through the registered taps in registration order\n * — called by the fallback owner on every index response it renders.\n * @param html - the raw index.html body.\n * @returns the transformed body.\n */',
       },
     ],
   },
@@ -1225,92 +1233,92 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'agent-loop/config-start-failed',
     mode: 'emit',
-    signature: '\'agent-loop/config-start-failed\'(sessionId: SessionId, error: unknown): void',
-    jsDoc: '/**\n * A declarative agent entry failed before it could publish a live agent.\n * Consumers that buffer work for the configured identity use this\n * transient signal to reject that work instead of waiting forever. Normal\n * factory teardown suppresses failures from the cancelled startup attempt.\n * @param sessionId - exact shared agent/session identity that failed startup.\n * @param error - persistence, setup, or publication failure.\n * @mode emit\n */',
+    signature: '\'agent-loop/config-start-failed\'(payload: { sessionId: SessionId; error: unknown }): void',
+    jsDoc: '/**\n * A declarative agent entry failed before it could publish a live agent.\n * Consumers that buffer work for the configured identity use this\n * transient signal to reject that work instead of waiting forever. Normal\n * factory teardown suppresses failures from the cancelled startup attempt.\n * @param payload.sessionId - exact shared agent/session identity that failed startup.\n * @param payload.error - persistence, setup, or publication failure.\n * @mode emit\n */',
     summary: 'A declarative agent entry failed before it could publish a live agent.',
   },
   {
     name: 'agent/created',
     mode: 'emit',
-    signature: '\'agent/created\'(this: Scoped<Agent>, agent: Agent): void',
-    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving seam.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/created\'(this: Scoped<Agent>, payload: { agent: Agent }): void',
+    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving seam.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param payload.agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A fully configured agent and live session were published.',
   },
   {
     name: 'agent/disposed',
     mode: 'emit',
-    signature: '\'agent/disposed\'(this: Scoped<Agent>, agent: Agent): void',
-    jsDoc: '/**\n * An agent left the registry; AgentLoop emits this after driver quiescence\n * and scoped-registration unwind, but before session detachment. Custom\n * registry users own their driver-ordering contract.\n * @param agent - the exact agent removed from the registry.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/disposed\'(this: Scoped<Agent>, payload: { agent: Agent }): void',
+    jsDoc: '/**\n * An agent left the registry; AgentLoop emits this after driver quiescence\n * and scoped-registration unwind, but before session detachment. Custom\n * registry users own their driver-ordering contract.\n * @param payload.agent - the exact agent removed from the registry.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'An agent left the registry; AgentLoop emits this after driver quiescence and scoped-registration unwind, but before session detachment.',
   },
   {
     name: 'agent/error',
     mode: 'emit',
-    signature: '\'agent/error\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void',
-    jsDoc: '/**\n * A step or turn errored. The machine reports a failure here even when\n * the error has no in-turn position for a durable record.\n * @param agent - the agent whose turn errored.\n * @param turn - the turn in which the failure surfaced.\n * @param step - the step at which the failure surfaced.\n * @param error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/error\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void',
+    jsDoc: '/**\n * A step or turn errored. The machine reports a failure here even when\n * the error has no in-turn position for a durable record.\n * @param payload.agent - the agent whose turn errored.\n * @param payload.turn - the turn in which the failure surfaced.\n * @param payload.step - the step at which the failure surfaced.\n * @param payload.error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A step or turn errored.',
   },
   {
     name: 'agent/inbox/claimed',
     mode: 'emit',
-    signature: '\'agent/inbox/claimed\'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage; turn: number }): void',
-    jsDoc: '/**\n * One message left the inbox inside its open turn. If the proposed step\n * is rejected, the claimed message ends here: it is neither discarded nor\n * re-emitted as a user/message, and the turn closes without a step.\n * @param agent - the agent whose inbox changed.\n * @param event - the claimed message and owning turn.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/inbox/claimed\'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void',
+    jsDoc: '/**\n * One message left the inbox inside its open turn. If the proposed step\n * is rejected, the claimed message ends here: it is neither discarded nor\n * re-emitted as a user/message, and the turn closes without a step.\n * @param payload.agent - the agent whose inbox changed.\n * @param payload.message - the claimed message.\n * @param payload.turn - the owning turn.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'One message left the inbox inside its open turn.',
   },
   {
     name: 'agent/inbox/discarded',
     mode: 'emit',
-    signature: '\'agent/inbox/discarded\'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage }): void',
-    jsDoc: '/**\n * One message was discarded from the live inbox.\n * @param agent - the agent whose inbox changed.\n * @param event - the discarded message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/inbox/discarded\'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void',
+    jsDoc: '/**\n * One message was discarded from the live inbox.\n * @param payload.agent - the agent whose inbox changed.\n * @param payload.message - the discarded message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'One message was discarded from the live inbox.',
   },
   {
     name: 'agent/inbox/inserted',
     mode: 'emit',
-    signature: '\'agent/inbox/inserted\'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage }): void',
-    jsDoc: '/**\n * One message entered the live inbox.\n * @param agent - the agent whose inbox changed.\n * @param event - the inserted message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/inbox/inserted\'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void',
+    jsDoc: '/**\n * One message entered the live inbox.\n * @param payload.agent - the agent whose inbox changed.\n * @param payload.message - the inserted message.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'One message entered the live inbox.',
   },
   {
     name: 'agent/pre-step',
     mode: 'waterfall',
-    signature: '\'agent/pre-step\'(this: Scoped<Agent>, agent: Agent, messages: UserMessage[], context: PreStepContext, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>',
-    jsDoc: '/**\n * Reject a proposed step or replace the messages that enter it. Calling\n * `next()` preserves the current messages.\n * @param agent - the agent proposing the step.\n * @param messages - messages removed from the inbox for this step.\n * @param context - proposed turn and step coordinates plus cancellation.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
+    signature: '\'agent/pre-step\'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>',
+    jsDoc: '/**\n * Reject a proposed step or replace the messages that enter it. Calling\n * `next()` preserves the current messages.\n * @param payload.agent - the agent proposing the step.\n * @param payload.messages - messages removed from the inbox for this step.\n * @param payload.turn - the turn that will own the step.\n * @param payload.step - the step proposed by the loop.\n * @param payload.signal - the current turn\'s cancellation signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Reject a proposed step or replace the messages that enter it.',
   },
   {
     name: 'agent/request',
     mode: 'waterfall',
-    signature: '\'agent/request\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
-    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this seam cannot mutate messages.\n * @param agent - the agent making the model call.\n * @param turn - the open turn number.\n * @param step - the step whose request this is.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
+    signature: '\'agent/request\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
+    jsDoc: '/**\n * Replace the frozen call configuration. `await next()` yields the config\n * the machine would use (agent options on the first request, the logged\n * header afterwards); return a replacement to switch. Model-visible\n * content must use logged channels; this seam cannot mutate messages.\n * @param payload.agent - the agent making the model call.\n * @param payload.turn - the open turn number.\n * @param payload.step - the step whose request this is.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n*/',
     summary: 'Replace the frozen call configuration.',
   },
   {
     name: 'agent/request-error',
     mode: 'waterfall',
-    signature: '\'agent/request-error\'(this: Scoped<Agent>, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>',
-    jsDoc: '/**\n * Handle one failed model-request attempt before the loop retries or closes\n * its step. A listener returns `{ kind: \'retry\' }` without calling `next()`\n * when it owns recovery, or calls `next()` to delegate. The default\n * `undefined` leaves the failure terminal.\n * @param agent - the agent whose request failed.\n * @param context - request coordinates, provider, normalized failure, and serving policy.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
+    signature: '\'agent/request-error\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>',
+    jsDoc: '/**\n * Handle one failed model-request attempt before the loop retries or closes\n * its step. A listener returns `{ kind: \'retry\' }` without calling `next()`\n * when it owns recovery, or calls `next()` to delegate. The default\n * `undefined` leaves the failure terminal.\n * @param payload.agent - the agent whose request failed.\n * @param payload.turn - the turn containing the failed request.\n * @param payload.step - the step containing the failed request attempt.\n * @param payload.provider - the provider selected for the failed request.\n * @param payload.failure - serializable facts normalized at the final adapter boundary.\n * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.\n * @param payload.signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Handle one failed model-request attempt before the loop retries or closes its step.',
   },
   {
     name: 'agent/session-start',
     mode: 'emit',
-    signature: '\'agent/session-start\'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void',
-    jsDoc: '/**\n * The session lifecycle began, once before the first turn. Use\n * `agent.inject()` to seed model-facing context. This is a notification, not\n * a veto; disposal requested by a lifecycle owner is rechecked before the\n * driver starts.\n * @param agent - the agent whose session lifecycle began.\n * @param source - why the session started (fresh startup, resume, …).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/session-start\'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void',
+    jsDoc: '/**\n * The session lifecycle began, once before the first turn. Use\n * `agent.inject()` to seed model-facing context. This is a notification, not\n * a veto; disposal requested by a lifecycle owner is rechecked before the\n * driver starts.\n * @param payload.agent - the agent whose session lifecycle began.\n * @param payload.source - why the session started (fresh startup, resume, …).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'The session lifecycle began, once before the first turn.',
   },
   {
     name: 'agent/status',
     mode: 'emit',
-    signature: '\'agent/status\'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void',
-    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). A waking delivery enters\n * `running` synchronously after reserving cancellation; `idle` means no\n * driver remains scheduled or active.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
+    signature: '\'agent/status\'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void',
+    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`). A waking delivery enters\n * `running` synchronously after reserving cancellation; `idle` means no\n * driver remains scheduled or active.\n * @param payload.agent - the agent whose status flipped.\n * @param payload.status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'Agent status changed (`idle` ⇄ `running`).',
   },
   {
     name: 'agent/turn-stopping',
     mode: 'serial',
-    signature: '\'agent/turn-stopping\'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void',
-    jsDoc: '/**\n * The turn is about to close: the model owes no response (no live tool\n * calls, no fresh steering). Awaited before the boundary commits — a\n * listener that objects steers (`agent.steer(...)`) and the machine\n * re-reads its inbox: fresh steering runs another step, none closes the\n * turn. Data decides, so listener order cannot change the outcome. The\n * inverse control (stop a tool loop early) is data too: a tool result\n * carrying `concludesTurn` ends the turn at its step. The conclusion\n * never short-circuits already-submitted next-step work: same-step\n * `additionalContexts` or racing steering still runs, and the turn\n * closes only when that inbox drains.\n * @param agent - the agent whose turn is at its stop boundary.\n * @param turn - the turn about to close.\n * @param signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode serial\n */',
+    signature: '\'agent/turn-stopping\'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void',
+    jsDoc: '/**\n * The turn is about to close: the model owes no response (no live tool\n * calls, no fresh steering). Awaited before the boundary commits — a\n * listener that objects steers (`agent.steer(...)`) and the machine\n * re-reads its inbox: fresh steering runs another step, none closes the\n * turn. Data decides, so listener order cannot change the outcome. The\n * inverse control (stop a tool loop early) is data too: a tool result\n * carrying `concludesTurn` ends the turn at its step. The conclusion\n * never short-circuits already-submitted next-step work: same-step\n * `additionalContexts` or racing steering still runs, and the turn\n * closes only when that inbox drains.\n * @param payload.agent - the agent whose turn is at its stop boundary.\n * @param payload.turn - the turn about to close.\n * @param payload.signal - the current turn\'s explicit abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode serial\n */',
     summary: 'The turn is about to close: the model owes no response (no live tool calls, no fresh steering).',
   },
   {
@@ -1365,8 +1373,8 @@ export const EVENT_API: readonly EventApiEntry[] = [
   {
     name: 'goal/changed',
     mode: 'emit',
-    signature: '\'goal/changed\'(this: import(\'@deepseek-ai/dsh-scope\').Scoped<Agent>, agent: Agent, change: GoalChanged): void',
-    jsDoc: '/**\n * Goal mutation accepted by one live agent. The matching `goal/change`\n * session event has already committed. Listener failures are contained.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @param agent - agent whose session owns the goal.\n * @param change - fresh current projection or clear tombstone.\n * @mode emit\n */',
+    signature: '\'goal/changed\'(this: import(\'@deepseek-ai/dsh-scope\').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void',
+    jsDoc: '/**\n * Goal mutation accepted by one live agent. The matching `goal/change`\n * session event has already committed. Listener failures are contained.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @param payload.agent - agent whose session owns the goal.\n * @param payload.change - fresh current projection or clear tombstone.\n * @mode emit\n */',
     summary: 'Goal mutation accepted by one live agent.',
   },
   {

packages/cordis/tool-cordis/tests/integration.spec.ts

@@ -28,7 +28,7 @@ async function harness(adapter: MockAdapter): Promise<Context> {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()

packages/core/agent-loop/src/agent.ts

@@ -7,13 +7,15 @@
 import type {
   Agent,
   AgentCancelCause,
+  AgentEventDispatch,
   AgentOptions,
   AgentStatus,
   CancelOptions,
   InboxTarget,
+  PreStepDecision,
   RequestErrorAction,
 } from '@deepseek-ai/dsh-agent'
-import { Inbox, agentCarrier, agentEvents, assembleContextFor, emitAgentEvent } from '@deepseek-ai/dsh-agent'
+import { Inbox, agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent'
 import type { GenerateOptions, LlmCallConfig, Message, PreparedLlmCall } from '@deepseek-ai/dsh-llm'
 import {
   BlockAssembler,
@@ -68,6 +70,9 @@ export class ReactLoopAgent implements Agent {
   readonly scope: Scope
   readonly ctx: Context
 
+  /** Fused dispatcher, built once in the constructor so hot-path dispatches never allocate. */
+  private readonly dispatch: AgentEventDispatch
+
   /** Whether this loop instance has appended its initial/resume request anchor. */
   private requestHeaderLogged = false
   private readonly runtimeContext: RuntimeContextProjection
@@ -78,10 +83,11 @@ export class ReactLoopAgent implements Agent {
     public readonly options: AgentOptions,
     public readonly session: Session,
   ) {
+    this.dispatch = agentEvents(loopCtx, this)
     this.inbox = new Inbox(session, {
-      inserted: (message) => { emitAgentEvent(loopCtx, this, 'agent/inbox/inserted', { message }) },
-      discarded: (message) => { emitAgentEvent(loopCtx, this, 'agent/inbox/discarded', { message }) },
-      claimed: (message, turn) => { emitAgentEvent(loopCtx, this, 'agent/inbox/claimed', { message, turn }) },
+      inserted: (message) => { this.dispatch.emit('agent/inbox/inserted', { message }) },
+      discarded: (message) => { this.dispatch.emit('agent/inbox/discarded', { message }) },
+      claimed: (message, turn) => { this.dispatch.emit('agent/inbox/claimed', { message, turn }) },
     })
     const lastTurn = session.events.findLast(event => event.type === 'turn/start')?.data.turn ?? 0
     this.phase = { kind: 'idle', lastTurn }
@@ -100,7 +106,7 @@ export class ReactLoopAgent implements Agent {
     this.phase = next
     const status = this.status
     if (status !== previousStatus) {
-      emitAgentEvent(this.loopCtx, this, 'agent/status', status)
+      this.dispatch.emit('agent/status', { status })
     }
   }
 
@@ -178,7 +184,7 @@ export class ReactLoopAgent implements Agent {
   private throwError(error: unknown): never {
     const turn = this.phase.kind === 'running' ? this.phase.turn : this.phase.lastTurn
     const step = this.phase.kind === 'running' ? this.phase.step : 0
-    emitAgentEvent(this.loopCtx, this, 'agent/error', turn, step, error)
+    this.dispatch.emit('agent/error', { turn, step, error })
     throw error
   }
 
@@ -204,9 +210,9 @@ export class ReactLoopAgent implements Agent {
     signal.throwIfAborted()
     const sections = renderContextSections(assembly)
     const context = this.runtimeContext.project(joinContextSections(sections), sections)
-    const decision = await agentEvents(this.loopCtx, this).waterfall(
-      'agent/pre-step', claimed, { ...position, signal },
-      () => Promise.resolve({
+    const decision = await this.dispatch.waterfall(
+      'agent/pre-step', { messages: claimed, ...position, signal },
+      (): Promise<PreStepDecision> => Promise.resolve<PreStepDecision>({
         kind: 'enter',
         messages: context === undefined ? claimed : [...claimed, context],
       }),
@@ -266,7 +272,7 @@ export class ReactLoopAgent implements Agent {
         }
         signal.throwIfAborted()
         if (turnEnds && this.inbox.nextStep.length === 0) {
-          await this.loopCtx.serial(agentCarrier(this), 'agent/turn-stopping', this, turn, signal)
+          await this.dispatch.serial('agent/turn-stopping', { turn, signal })
           signal.throwIfAborted()
         }
         if (turnEnds && this.inbox.nextStep.length === 0) break
@@ -323,14 +329,15 @@ export class ReactLoopAgent implements Agent {
       signal.throwIfAborted()
       const finish = assembler.finish
       if (finish.kind === 'error' || finish.kind === 'aborted') {
-        const action = await this.loopCtx.waterfall(
-          agentCarrier(this), 'agent/request-error', this, {
+        const action = await this.dispatch.waterfall(
+          'agent/request-error', {
             turn,
             step,
             provider: request.provider,
             failure: finish.failure,
             retryPolicy: preparedCall?.retryPolicy,
-          }, signal,
+            signal,
+          },
           () => Promise.resolve<RequestErrorAction>(undefined),
         )
         signal.throwIfAborted()
@@ -405,8 +412,8 @@ export class ReactLoopAgent implements Agent {
           ...maxTokens === undefined ? {} : { maxTokens },
         },
     ))
-    const proposedConfig = await this.loopCtx.waterfall(
-      agentCarrier(this), 'agent/request', this, turn, step, signal,
+    const proposedConfig = await this.dispatch.waterfall(
+      'agent/request', { turn, step, signal },
       () => Promise.resolve(seedConfig),
     )
     signal.throwIfAborted()

packages/core/agent-loop/src/index.ts

@@ -175,11 +175,11 @@ declare module 'cordis' {
      * Consumers that buffer work for the configured identity use this
      * transient signal to reject that work instead of waiting forever. Normal
      * factory teardown suppresses failures from the cancelled startup attempt.
-     * @param sessionId - exact shared agent/session identity that failed startup.
-     * @param error - persistence, setup, or publication failure.
+     * @param payload.sessionId - exact shared agent/session identity that failed startup.
+     * @param payload.error - persistence, setup, or publication failure.
      * @mode emit
      */
-    'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
+    'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
   }
 }
 
@@ -351,7 +351,7 @@ export class AgentLoop extends Service implements AgentFactory {
   ): void {
     if (!this.ownership.isActive()) return
     this.ctx.logger.warn(`agent "${configId}": config-driven ${action} of "${sessionId}" failed: ${errorChain(error)}`)
-    const args: unknown[] = ['agent-loop/config-start-failed', sessionId, error]
+    const args: unknown[] = ['agent-loop/config-start-failed', { sessionId, error }]
     for (const callback of this.ctx.events.dispatch('emit', args)) {
       try {
         const returned: unknown = callback(...args)
@@ -400,7 +400,7 @@ export class AgentLoop extends Service implements AgentFactory {
         released.resolve()
       }
     }
-    const disposeAgentListener = ownerCtx.on('agent/disposed', checkReleased)
+    const disposeAgentListener = ownerCtx.on('agent/disposed', () => { checkReleased() })
     const disposeSessionListener = ownerCtx.on('session/disposed', checkReleased)
     try {
       checkReleased()
@@ -525,7 +525,7 @@ export class AgentLoop extends Service implements AgentFactory {
           // A synchronous announce/session-start listener may have started
           // teardown; the machine is already live (delivery works from the
           // session-start seam), so only the liveness recheck is owed.
-          emitAgentEvent(loopCtx, agent, 'agent/session-start', source)
+          emitAgentEvent(loopCtx, agent, 'agent/session-start', { source })
           assertLive()
           return { agent, dispose }
         },

packages/core/agent-loop/tests/agent-initiator.spec.ts

@@ -31,7 +31,7 @@ async function harness(adapter: LlmAdapter): Promise<Harness> {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -164,18 +164,18 @@ describe('AgentLoop initiator scope', () => {
       if (context.agent === agent) capture(context.signal)
       return next()
     })
-    ctx.on('agent/pre-step', async (subject, _message, { signal }, next) => {
+    ctx.on('agent/pre-step', async ({ agent: subject, signal }, next) => {
       if (subject === agent) {
         expect(ctx.agents.requireInitiator()).toBe(agent)
         preStepSignals.push(signal)
       }
       return next()
     })
-    ctx.on('agent/request', async (subject, _turn, _step, signal, next) => {
+    ctx.on('agent/request', async ({ agent: subject, signal }, next) => {
       if (subject === agent) capture(signal)
       return next()
     })
-    ctx.on('agent/turn-stopping', (subject, _turn, signal) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject, signal }) => {
       if (subject === agent) capture(signal)
     })
     ctx.tools.register(defineContentToolFixture({

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

@@ -60,17 +60,17 @@ describe('Agent', () => {
     ctx.on('session/event', (session, event) => {
       if (session === agent.session && event.type === 'turn/start') lifecycle.push('turn/start')
     })
-    ctx.on('agent/inbox/inserted', (subject, event) => {
-      if (subject === agent) inserted.push(event)
+    ctx.on('agent/inbox/inserted', ({ agent: subject, message }) => {
+      if (subject === agent) inserted.push({ message })
     })
-    ctx.on('agent/inbox/claimed', (subject, event) => {
+    ctx.on('agent/inbox/claimed', ({ agent: subject, message, turn }) => {
       if (subject === agent) {
         lifecycle.push('agent/inbox/claimed')
-        claimed.push(event)
+        claimed.push({ message, turn })
       }
     })
-    ctx.on('agent/inbox/discarded', (subject, event) => {
-      if (subject === agent) discarded.push(event)
+    ctx.on('agent/inbox/discarded', ({ agent: subject, message }) => {
+      if (subject === agent) discarded.push({ message })
     })
     const context = createUserMessage({
       content: [{ type: 'text', text: 'discard me' }],
@@ -114,7 +114,7 @@ describe('Agent', () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     const statuses: string[] = []
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent) statuses.push(status)
     })
 
@@ -152,7 +152,7 @@ describe('Agent', () => {
     const ctx = await harness(new MockAdapter([textResponse('ok')]))
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/status', (_subject, status) => {
+    ctx.on('agent/status', ({ status }) => {
       throw new Error(`bad ${status} listener`)
     })
 

packages/core/agent-loop/tests/cancel.spec.ts

@@ -40,7 +40,7 @@ function send(agent: Agent, text: string) {
 /** Resolve on the agent's next idle transition (event-based, not status poll). */
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
     })
   })
@@ -156,7 +156,7 @@ describe('Agent.cancel()', () => {
 
     const running = Promise.withResolvers<undefined>()
     let disposalDone: Promise<void> | undefined
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject !== agent || status !== 'running') return
       disposalDone = handle.dispose()
       running.resolve(undefined)
@@ -200,7 +200,7 @@ describe('Agent.cancel()', () => {
 
     const replacementRegistered = Promise.withResolvers<undefined>()
     let replacementObservation: Promise<{ status: string; requests: number; turns: number }> | undefined
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject !== agent || status !== 'idle' || replacementObservation !== undefined) return
       send(agent, 'cancelled replacement')
       replacementObservation = agent.whenIdle().then(() => ({
@@ -239,7 +239,7 @@ describe('Agent.cancel()', () => {
 
     const replacementRegistered = Promise.withResolvers<undefined>()
     let replacementIdle: Promise<void> | undefined
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject !== agent || status !== 'idle' || replacementIdle !== undefined) return
       send(agent, 'cancelled replacement')
       agent.cancel({ kind: 'user' })
@@ -440,7 +440,7 @@ describe('Agent.cancel()', () => {
     })
 
     let cancelled = false
-    ctx.on('agent/turn-stopping', (subject) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject }) => {
       if (subject === agent && !cancelled) {
         cancelled = true
         agent.cancel({ kind: 'user' })
@@ -465,7 +465,7 @@ describe('Agent.cancel()', () => {
     // durable turn-start commit and must drop the reserved work.
     let streamed = false
     ctx.on('session/event', (_s, event) => { if (event.type === 'assistant/chunk') streamed = true })
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'running') agent.cancel({ kind: 'user' })
     })
 
@@ -485,7 +485,7 @@ describe('Agent.cancel()', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let replaced = false
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject !== agent || status !== 'running' || replaced) return
       replaced = true
       agent.cancel({ kind: 'user' })
@@ -664,7 +664,7 @@ describe('Agent.cancel()', () => {
 
     switch (stage) {
       case 'pre-step':
-        ctx.on('agent/pre-step', async (subject, _message, { signal }, next) => {
+        ctx.on('agent/pre-step', async ({ agent: subject, signal }, next) => {
           if (subject === agent) await blockUntilAbort(signal)
           return next()
         })
@@ -679,13 +679,13 @@ describe('Agent.cancel()', () => {
         })
         break
       case 'request':
-        ctx.on('agent/request', async (subject, _turn, _step, signal, next) => {
+        ctx.on('agent/request', async ({ agent: subject, signal }, next) => {
           if (subject === agent) await blockUntilAbort(signal)
           return next()
         })
         break
       case 'stopping':
-        ctx.on('agent/turn-stopping', async (subject, _turn, signal) => {
+        ctx.on('agent/turn-stopping', async ({ agent: subject, signal }) => {
           if (subject === agent) await blockUntilAbort(signal)
         })
         break

packages/core/agent-loop/tests/config-session-id.spec.ts

@@ -19,7 +19,7 @@ afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive:
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
     })
   })
@@ -170,7 +170,7 @@ describe('config-driven session id', () => {
     await cleanupStarted.promise
     expect(first.status).toBe('idle')
     const failures: unknown[] = []
-    ctx.on('agent-loop/config-start-failed', (_id, error) => { failures.push(error) })
+    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     const secondLoop = await ctx.plugin(AgentLoop, config)
     await new Promise(resolve => setTimeout(resolve, 0))
     expect(ctx.agents.get(sessionId)).toBe(first)
@@ -234,7 +234,7 @@ describe('config-driven session id', () => {
     const failures: { sessionId: SessionId; error: unknown }[] = []
     ctx.on('agent-loop/config-start-failed', () => { throw listenerFailure })
     ctx.on('agent-loop/config-start-failed', () => Promise.reject(asyncListenerFailure) as never)
-    ctx.on('agent-loop/config-start-failed', (sessionId, error) => {
+    ctx.on('agent-loop/config-start-failed', ({ sessionId, error }) => {
       failures.push({ sessionId, error })
     })
     vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(failure)
@@ -274,7 +274,7 @@ describe('config-driven session id', () => {
     // Deliberately violate the normal Error-only rejection rule to exercise the unknown boundary.
     // oxlint-disable-next-line typescript/prefer-promise-reject-errors
     ctx.on('agent-loop/config-start-failed', () => Promise.reject(unrenderable) as never)
-    ctx.on('agent-loop/config-start-failed', (_sessionId, error) => { failures.push(error) })
+    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     vi.spyOn(ctx.sessionPersistence, 'list').mockRejectedValue(unrenderable)
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
 
@@ -307,7 +307,7 @@ describe('config-driven session id', () => {
       const released = vi.fn()
       const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
       const failures: unknown[] = []
-      ctx.on('agent-loop/config-start-failed', (_sessionId, error) => { failures.push(error) })
+      ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
 
       const loop = await ctx.plugin(AgentLoop, {
         agents: [{ id: 'main', sessionId: SessionId('config-exact-dispose'), model: 'mock' }],
@@ -479,7 +479,7 @@ describe('startup reporting after factory teardown', () => {
     gate.promise.catch(() => undefined)
     vi.spyOn(ctx.sessionPersistence, 'list').mockReturnValue(gate.promise)
     const failures: unknown[] = []
-    ctx.on('agent-loop/config-start-failed', (_id, error) => { failures.push(error) })
+    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
 
     const loop = await ctx.plugin(AgentLoop, {

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -40,7 +40,7 @@ async function harness(adapter: MockAdapter) {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -191,7 +191,7 @@ describe('abort during tool execution ends the turn', () => {
     const adapter = new MockAdapter([textResponse('must not run')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a-empty-batch'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/pre-step', (subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (subject !== agent) return next()
       return Promise.resolve({ kind: 'enter', messages: [] })
     })
@@ -288,7 +288,7 @@ describe('abort during tool execution ends the turn', () => {
 
     send(agent, 'leave an unmatched historical call')
     await waitForIdle(ctx, agent)
-    const disposeInjection = ctx.on('agent/pre-step', async (subject, _messages, { turn }, next) => {
+    const disposeInjection = ctx.on('agent/pre-step', async ({ agent: subject, turn }, next) => {
       const decision = await next()
       if (subject === agent && turn === 2 && decision.kind === 'enter') {
         disposeInjection()
@@ -382,7 +382,7 @@ describe('disposal leaves the two-state status contract balanced', () => {
 
     const statuses: string[] = []
     const reasons: TurnEndReason[] = []
-    ctx.on('agent/status', (_agent, status) => void statuses.push(status))
+    ctx.on('agent/status', ({ status }) => void statuses.push(status))
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })
 
     send(agent, 'go')
@@ -411,7 +411,7 @@ describe('disposal leaves the two-state status contract balanced', () => {
       agent = inner.agentLoop.create(SessionId('scoped'), { provider: 'mock', model: 'mock' })
     }, { inject: ['agentLoop'] }))
 
-    ctx.on('agent/status', (_agent, status) => {
+    ctx.on('agent/status', ({ status }) => {
       if (status === 'idle') throw new Error('broken status listener')
     })
 
@@ -457,7 +457,7 @@ describe('adapter registration, routing, and accepted-input ownership', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), {}) // no model — router plugin decides
 
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       return { ...await next(), provider: 'mock', model: 'mock' }
     })
 
@@ -540,7 +540,7 @@ describe('turn numbering continues across seeded sessions', () => {
     ctx2.on('session/event', (_s, event) => { if (event.type === 'turn/start') turns.push(event.data.turn) })
     forked.followup(createUserMessage({ content: [{ type: 'text', text: 'continue' }], source: { kind: 'user' } }))
     await new Promise<void>((resolve) => {
-      ctx2.on('agent/status', (subject, status) => {
+      ctx2.on('agent/status', ({ agent: subject, status }) => {
         if (subject === forked && status === 'idle') resolve()
       })
     })
@@ -586,7 +586,7 @@ describe('a finish-error stream chunk ends the turn as error, not completed', ()
 
     const reasons: TurnEndReason[] = []
     const errors: unknown[] = []
-    ctx.on('agent/error', (_agent, turn, step, error) => {
+    ctx.on('agent/error', ({ turn, step, error }) => {
       expect({ turn, step }).toEqual({ turn: 1, step: 1 })
       errors.push(error)
     })
@@ -710,7 +710,7 @@ describe('turn and step boundary recovery', () => {
       if (event.type === 'step/start' && !threw) { threw = true; throw new Error('boom step-start') }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -743,7 +743,7 @@ describe('turn and step boundary recovery', () => {
       }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -800,7 +800,7 @@ describe('turn and step boundary recovery', () => {
       }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -893,14 +893,14 @@ describe('turn and step boundary recovery', () => {
     }, { inject: ['agentLoop'] }))
 
     let threw = false
-    ctx.on('agent/pre-step', (_subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', (_payload, next) => {
       if (threw) return next()
       threw = true
       void fiber.dispose()
       throw new Error('boom pre-step during disposal')
     })
     const errorEmits: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errorEmits.push(error)
     })
 
@@ -926,7 +926,7 @@ describe('turn and step boundary recovery', () => {
       if (!threw && event.type === 'turn/start') { threw = true; throw new Error('boom turn/start append') }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -959,7 +959,7 @@ describe('turn and step boundary recovery', () => {
       if (event.type === 'step/end' && !threw) { threw = true; throw new Error('boom step-end') }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -1000,7 +1000,7 @@ describe('turn and step boundary recovery', () => {
       if (!threw && event.type === 'step/end') { threw = true; throw new Error('boom step/end listener') }
     })
     const errors: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -1215,7 +1215,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    ctx.on('agent/pre-step', async (_subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', async (_payload, next) => {
       await blocker
       return next()
     })
@@ -1261,7 +1261,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await mountInvariants(ctx)
     ctx.llm.registerAdapter(['mock'], adapter)
 
-    ctx.on('agent/pre-step', async (_subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', async (_payload, next) => {
       await blocker
       return next()
     })

packages/core/agent-loop/tests/coverage-edges.spec.ts

@@ -28,7 +28,7 @@ async function harness(adapter: MockAdapter) {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -120,7 +120,7 @@ describe('thrown-value propagation', () => {
     })
 
     const errors: unknown[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => void errors.push(error))
+    ctx.on('agent/error', ({ error }) => void errors.push(error))
 
     send(agent, 'fails before turn start')
     send(agent, 'survives as the next item')
@@ -143,7 +143,7 @@ describe('thrown-value propagation', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       if (!threwOnce) {
         threwOnce = true
         throw { code: 500 }
@@ -167,7 +167,7 @@ describe('durable error rendering', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threwOnce = false
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       if (!threwOnce) {
         threwOnce = true
         throw new LlmError('server overloaded', 'RATE_LIMIT')
@@ -250,7 +250,7 @@ describe('request-error action edges', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('retry-after-cancel'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/request-error', async (subject) => {
+    ctx.on('agent/request-error', async ({ agent: subject }) => {
       subject.cancel({ kind: 'user' })
       return { kind: 'retry' }
     })
@@ -271,7 +271,7 @@ describe('request-error action edges', () => {
     ])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('retry-raced'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/request-error', async (subject, _context, signal, next) => {
+    ctx.on('agent/request-error', async ({ agent: subject, signal }, next) => {
       await next()
       subject.cancel({ kind: 'user' })
       expect(signal.aborted).toBe(true)
@@ -350,7 +350,7 @@ describe('persistent step-close rejection', () => {
       if (event.type === 'step/end') throw new Error('step close permanently rejected')
     })
     const statuses: string[] = []
-    ctx.on('agent/status', (subject, status) => { if (subject === agent) statuses.push(status) })
+    ctx.on('agent/status', ({ agent: subject, status }) => { if (subject === agent) statuses.push(status) })
 
     send(agent, 'go')
     await agent.whenIdle()
@@ -406,7 +406,7 @@ describe('turn close failure containment', () => {
       }
     })
     const errors: unknown[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => { errors.push(error) })
+    ctx.on('agent/error', ({ error }) => { errors.push(error) })
 
     send(agent, 'go')
     await agent.whenIdle()
@@ -484,11 +484,11 @@ describe('driver bookkeeping edges', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('reject-next-step'), { provider: 'mock', model: 'mock' })
     let proposals = 0
-    ctx.on('agent/pre-step', async (_subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', async (_payload, next) => {
       proposals += 1
       return proposals === 2 ? { kind: 'reject' } : next()
     })
-    ctx.on('agent/turn-stopping', (subject) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject }) => {
       subject.inject(createUserMessage({
         content: [{ type: 'text', text: 'do not enter the next step' }],
         source: { kind: 'plugin', plugin: 'test' },

packages/core/agent-loop/tests/interception.spec.ts

@@ -41,7 +41,7 @@ async function harness(adapter: MockAdapter) {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -65,7 +65,7 @@ describe('agent/pre-step', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const seen: string[] = []
-    ctx.on('agent/pre-step', async (_agent, messages, _signal, next) => {
+    ctx.on('agent/pre-step', async ({ messages }, next) => {
       seen.push(messages[0]!.content.map(b => (b.type === 'text' ? b.text : '')).join(''))
       return next()
     })
@@ -92,8 +92,8 @@ describe('agent/pre-step', () => {
     }))
     const agent = ctx.agentLoop.create(SessionId('prompt-coordinates'), { provider: 'mock', model: 'mock' })
     const seen: Array<{ turn: number; step: number; messages: number }> = []
-    ctx.on('agent/pre-step', async (_agent, messages, context, next) => {
-      seen.push({ turn: context.turn, step: context.step, messages: messages.length })
+    ctx.on('agent/pre-step', async ({ messages, turn, step }, next) => {
+      seen.push({ turn, step, messages: messages.length })
       return next()
     })
 
@@ -113,7 +113,7 @@ describe('agent/pre-step', () => {
     const entered = Promise.withResolvers<undefined>()
     const decision = Promise.withResolvers<PreStepDecision>()
     const observed: UserMessage[] = []
-    ctx.on('agent/pre-step', async (subject, messages) => {
+    ctx.on('agent/pre-step', async ({ agent: subject, messages }) => {
       if (subject !== agent) return { kind: 'enter', messages }
       const message = messages[0]!
       expect(Object.isFrozen(message)).toBe(true)
@@ -161,7 +161,7 @@ describe('agent/pre-step', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    ctx.on('agent/pre-step', async (_agent, messages): Promise<PreStepDecision> =>
+    ctx.on('agent/pre-step', async ({ messages }): Promise<PreStepDecision> =>
       ({
         kind: 'enter',
         messages: [{ ...messages[0]!, content: [{ type: 'text', text: 'REWRITTEN' }] }],
@@ -182,7 +182,7 @@ describe('agent/pre-step', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    ctx.on('agent/pre-step', async (_agent, messages): Promise<PreStepDecision> =>
+    ctx.on('agent/pre-step', async ({ messages }): Promise<PreStepDecision> =>
       ({
         kind: 'enter',
         messages: [...messages, createUserMessage({
@@ -211,15 +211,15 @@ describe('agent/pre-step', () => {
       provider: 'mock',
       model: 'mock',
     })
-    ctx.on('agent/turn-stopping', (subject) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject }) => {
       subject.inject(createUserMessage({
         content: [{ type: 'text', text: 'pending context' }],
         source: { kind: 'plugin', plugin: 'test' },
       }))
     })
-    ctx.on('agent/pre-step', async (_subject, _messages, context, next) => {
+    ctx.on('agent/pre-step', async ({ step }, next) => {
       const decision = await next()
-      return context.step === 1 || decision.kind === 'reject'
+      return step === 1 || decision.kind === 'reject'
         ? decision
         : { kind: 'enter', messages: [] }
     })
@@ -262,7 +262,7 @@ describe('agent/pre-step', () => {
     const decision = Promise.withResolvers<PreStepDecision>()
     let claimed: UserMessage[] = []
     let firstProposal = true
-    ctx.on('agent/pre-step', async (_agent, messages) => {
+    ctx.on('agent/pre-step', async ({ messages }) => {
       if (!firstProposal) return { kind: 'enter', messages }
       firstProposal = false
       claimed = messages
@@ -372,14 +372,14 @@ describe('agent/pre-step', () => {
       provider: 'mock',
       model: 'mock',
     })
-    ctx.on('agent/pre-step', async (_agent, messages, _signal, next) => {
+    ctx.on('agent/pre-step', async ({ messages }, next) => {
       const decision = await next()
       return messages.some(message =>
         message.content.some(block => block.type === 'text' && block.text === 'blocked prompt'))
         ? { kind: 'reject' as const }
         : decision
     })
-    ctx.on('agent/pre-step', async (subject, messages, _signal, next) => {
+    ctx.on('agent/pre-step', async ({ agent: subject, messages }, next) => {
       if (messages.some(message =>
         message.content.some(block => block.type === 'text' && block.text === 'blocked prompt'))) {
         subject.inject(createUserMessage({
@@ -482,7 +482,7 @@ describe('agent/pre-step', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    ctx.on('agent/pre-step', async (_agent, messages, _signal, next): Promise<PreStepDecision> => {
+    ctx.on('agent/pre-step', async ({ messages }, next): Promise<PreStepDecision> => {
       const text = messages.flatMap(message => message.content)
         .map(b => (b.type === 'text' ? b.text : '')).join('')
       return text === 'secret'
@@ -519,17 +519,17 @@ describe('agent/pre-step', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let threw = false
-    ctx.on('agent/pre-step', async (_agent, messages) => {
+    ctx.on('agent/pre-step', async ({ messages }) => {
       if (!threw) { threw = true; throw new Error('prompt hook broke') }
       return { kind: 'enter' as const, messages }
     })
     const errors: Error[] = []
     const reasons: TurnEndReason[] = []
     const statuses: string[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
-    ctx.on('agent/status', (subject, status) => { if (subject === agent) statuses.push(status) })
+    ctx.on('agent/status', ({ agent: subject, status }) => { if (subject === agent) statuses.push(status) })
     ctx.on('session/event', (session, event) => {
       if (session === agent.session && event.type === 'turn/end') reasons.push(event.data.reason)
     })
@@ -559,7 +559,7 @@ describe('agent/session-start', () => {
     const ctx = await harness(adapter)
 
     const sources: SessionStartSource[] = []
-    ctx.on('agent/session-start', (_agent, source) => void sources.push(source))
+    ctx.on('agent/session-start', ({ source }) => void sources.push(source))
 
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     // fires synchronously at create, before any turn
@@ -576,7 +576,7 @@ describe('agent/session-start', () => {
     const adapter = new MockAdapter([textResponse('ok')])
     const ctx = await harness(adapter)
 
-    ctx.on('agent/session-start', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => {
       agent.inject(createUserMessage({ content: [{ type: 'text', text: 'session preamble' }], source: { kind: 'plugin', plugin: 'test' } }))
     })
 
@@ -724,11 +724,11 @@ describe('worked example: a native hook plugin is just a cordis plugin on the se
     name: 'native-guard',
     apply(ctx: Context) {
       // 1. SessionStart: seed a standing instruction.
-      ctx.on('agent/session-start', (agent, source) => {
+      ctx.on('agent/session-start', ({ agent, source }) => {
         agent.inject(createUserMessage({ content: [{ type: 'text', text: `policy active (started: ${source})` }], source: { kind: 'plugin', plugin: 'native-guard' } }))
       })
       // 2. PreStep: reject a forbidden prompt, annotate the rest.
-      ctx.on('agent/pre-step', async (_agent, messages, _signal, next): Promise<PreStepDecision> => {
+      ctx.on('agent/pre-step', async ({ messages }, next): Promise<PreStepDecision> => {
         const text = messages.flatMap(message => message.content)
           .map(b => (b.type === 'text' ? b.text : '')).join('')
         if (text.includes('rm -rf')) {

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

@@ -28,7 +28,7 @@ async function harness(adapter: MockAdapter, persona = '') {
 /** Wait for the agent's next transition to idle after a waking send. */
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -216,7 +216,7 @@ describe('agent loop', () => {
     const adapter = new MockAdapter([textResponse('ok after rescue')])
     const ctx = await harness(adapter, 'In {{cwd}}.')
     const errors: Error[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
@@ -263,7 +263,7 @@ describe('agent loop', () => {
       assembly.variables['model'] = 'mock'
       return next()
     })
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       const config = await next()
       return { ...config, provider: 'mock', model: 'mock' }
     })
@@ -553,7 +553,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('failed-steering'), { provider: 'mock', model: 'mock' })
     let fail = true
-    ctx.on('agent/pre-step', (subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (subject !== agent || !fail) return next()
       fail = false
       subject.steer(createUserMessage({ content: [{ type: 'text', text: 'pending steering' }], source: { kind: 'user' } }))
@@ -713,7 +713,7 @@ describe('agent loop', () => {
 
     let steps = 0
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
-    ctx.on('agent/turn-stopping', (subject) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject }) => {
       if (steps < 3) {
         subject.steer(createUserMessage({ content: [{ type: 'text', text: 'continue' }], source: { kind: 'plugin', plugin: 'loop-test' } }))
       }
@@ -785,7 +785,7 @@ describe('agent loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       const config = await next()
       // The seed is frozen — config is not a mutable per-call knob; a switch
       // is proposed by returning a replacement, and the loop logs it.
@@ -816,7 +816,7 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     const fires: { turn: number; step: number; signal: AbortSignal }[] = []
-    ctx.on('agent/pre-step', (subject, _messages, { turn, step, signal }, next) => {
+    ctx.on('agent/pre-step', ({ agent: subject, turn, step, signal }, next) => {
       if (subject === agent) fires.push({ turn, step, signal })
       return next()
     })
@@ -837,7 +837,7 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let boundaryOpen = true
-    ctx.on('agent/pre-step', (subject, _messages, _context, next) => {
+    ctx.on('agent/pre-step', ({ agent: subject }, next) => {
       if (subject === agent) boundaryOpen = subject.session.events.at(-1)?.type === 'step/start'
       return next()
     })
@@ -855,13 +855,13 @@ describe('agent loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let throwOnce = true
-    ctx.on('agent/pre-step', (_agent, _messages, _context, next) => {
+    ctx.on('agent/pre-step', (_payload, next) => {
       if (throwOnce) { throwOnce = false; throw new Error('boom in pre-step') }
       return next()
     })
 
     const errors: Error[] = []
-    ctx.on('agent/error', (_a, _t, _s, error) => {
+    ctx.on('agent/error', ({ error }) => {
       if (error instanceof Error) errors.push(error)
     })
 
@@ -933,7 +933,7 @@ describe('agent loop', () => {
     ctx.on('session/event', (_session, event) => { if (event.type === 'step/end') steps++ })
     // Force exactly one continuation (step 1 → step 2), then defer to default
     // (step 2 is a plain stop with no tool calls → stops).
-    ctx.on('agent/turn-stopping', (subject) => {
+    ctx.on('agent/turn-stopping', ({ agent: subject }) => {
       if (steps < 2) {
         subject.steer(createUserMessage({ content: [{ type: 'text', text: 'continue after truncation' }], source: { kind: 'plugin', plugin: 'max-tokens-test' } }))
       }
@@ -1296,7 +1296,7 @@ describe('agent loop', () => {
 
     const errors: unknown[] = []
     const reasons: TurnEndReason[] = []
-    ctx.on('agent/error', (_agent, _turn, _step, error) => {
+    ctx.on('agent/error', ({ error }) => {
       errors.push(error)
     })
     ctx.on('session/event', (_s, event) => { if (event.type === 'turn/end') reasons.push(event.data.reason) })

packages/core/agent-loop/tests/properties.spec.ts

@@ -50,7 +50,7 @@ async function harness() {
 /** Resolve on the agent's next transition to idle (event-based, not polled). */
 function nextIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -63,7 +63,7 @@ function nextIdle(ctx: Context, agent: Agent): Promise<void> {
  * the seen list plus a disposer for the listener (per the registry convention). */
 function recordStatus(ctx: Context, agent: Agent): { seen: string[]; dispose: () => void } {
   const seen: string[] = []
-  const dispose = ctx.on('agent/status', (subject, status) => {
+  const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
     if (subject === agent) seen.push(status)
   })
   return { seen, dispose }

packages/core/agent-loop/tests/request-cache.e2e.ts

@@ -59,7 +59,7 @@ async function loopHarness(): Promise<Context> {
 
 function waitForIdle(context: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = context.on('agent/status', (subject, status) => {
+    const dispose = context.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()

packages/core/agent-loop/tests/request-error.spec.ts

@@ -62,12 +62,12 @@ describe('agent/request-error', () => {
       retryPolicy: ResolvedRetryPolicy | undefined
     }[] = []
     const statuses: string[] = []
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent) statuses.push(status)
     })
-    ctx.on('agent/request-error', async (subject, context) => {
+    ctx.on('agent/request-error', async ({ agent: subject, turn, step, failure, retryPolicy }) => {
       expect(subject).toBe(agent)
-      seen.push(context)
+      seen.push({ turn, step, failure, retryPolicy })
       return { kind: 'retry' }
     })
 
@@ -102,7 +102,7 @@ describe('agent/request-error', () => {
     const adapter = new MockAdapter([fail('busy', 'RATE_LIMIT'), textResponse('unused')])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('request-error-cancel'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/request-error', async (subject) => {
+    ctx.on('agent/request-error', async ({ agent: subject }) => {
       subject.cancel({ kind: 'user' })
       return { kind: 'retry' }
     })

packages/core/agent-loop/tests/request-reconstruction.spec.ts

@@ -38,7 +38,7 @@ async function harnessRoutes(
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -122,7 +122,7 @@ describe('request stability across the loop', () => {
     const adapter = new MockAdapter([textResponse('one'), textResponse('two')], reasoning)
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('effort'), { provider: 'mock', model: 'mock' })
-    ctx.on('agent/request', async (_agent, turn, _step, _signal, next) => {
+    ctx.on('agent/request', async ({ turn }, next) => {
       const config = await next()
       return turn === 2 ? { ...config, reasoningEffort: ReasoningEffortId('max') } : config
     })
@@ -198,7 +198,7 @@ describe('request stability across the loop', () => {
       provider: 'deepseek',
       model: 'deepseek-model',
     })
-    ctx.on('agent/request', async (_agent, turn, _step, _signal, next) => {
+    ctx.on('agent/request', async ({ turn }, next) => {
       const config = await next()
       return turn === 2
         ? { ...config, provider: 'other', model: 'other-model' }
@@ -232,7 +232,7 @@ describe('request stability across the loop', () => {
       model: 'deepseek-model',
       maxTokens: 4_096,
     })
-    ctx.on('agent/request', async (_agent, turn, _step, _signal, next) => {
+    ctx.on('agent/request', async ({ turn }, next) => {
       const config = await next()
       return turn === 2
         ? { ...config, provider: 'other', model: 'other-model' }
@@ -460,7 +460,7 @@ describe('request stability across the loop', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
     let injected = false
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       if (!injected) {
         injected = true
         agent.inject(createUserMessage({ content: [{ type: 'text', text: '[late context]' }], source: { kind: 'plugin', plugin: 'test' } }))
@@ -539,7 +539,7 @@ describe('request stability across the loop', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
 
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => {
+    ctx.on('agent/request', async (_payload, next) => {
       const config = await next()
       // next() resolves the SAME frozen seed — in-place shaping after
       // delegation is unrepresentable, so a "mutate what next() returned"
@@ -576,7 +576,7 @@ describe('request stability across the loop', () => {
     send(agent, 'go')
     await waitForIdle(ctx, agent)
     ctx.systemPrompt.section({ name: 'extra', order: 2, text: 'now with guidance' })
-    ctx.on('agent/request', async (_agent, _turn, _step, _signal, next) => ({
+    ctx.on('agent/request', async (_payload, next) => ({
       ...await next(), temperature: 0.5, maxTokens: 99, stop: ['<END>'],
     }))
     send(agent, 'again')
@@ -658,7 +658,7 @@ describe('request/context capacity records', () => {
 
     send(agent, 'first')
     await waitForIdle(ctx, agent)
-    ctx.on('agent/request', (subject, _turn, _step, _signal, next) => subject === agent
+    ctx.on('agent/request', ({ agent: subject }, next) => subject === agent
       ? Promise.resolve({ provider: 'mock', model: 'large' })
       : next())
     send(agent, 'second')
@@ -686,7 +686,7 @@ describe('request/context capacity records', () => {
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(SessionId('capacity-clear'), { provider: 'mock', model: 'known' })
     let model = 'known'
-    ctx.on('agent/request', (subject, _turn, _step, _signal, next) => subject === agent
+    ctx.on('agent/request', ({ agent: subject }, next) => subject === agent
       ? Promise.resolve({ provider: 'mock', model })
       : next())
 

packages/core/agent-loop/tests/resume.spec.ts

@@ -66,7 +66,7 @@ function preparationFromSnapshot(
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
     })
   })
@@ -260,7 +260,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     const adapter1 = new MockAdapter([textResponse('a')])
     const { ctx: ctx1, root } = await persistentHarness(adapter1)
     const sources1: string[] = []
-    ctx1.on('agent/session-start', (_agent, source) => void sources1.push(source))
+    ctx1.on('agent/session-start', ({ source }) => void sources1.push(source))
     const a1 = (await ctx1.agents.create({ sessionId: SessionId('start-sess') })).agent
     expect(sources1).toEqual(['startup'])
     a1.followup(createUserMessage({ content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }))
@@ -279,7 +279,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
     await ctx2.plugin(SessionPersistenceJsonl, { root })
     ctx2.llm.registerAdapter(['mock'], adapter2)
     const sources2: string[] = []
-    ctx2.on('agent/session-start', (_agent, source) => void sources2.push(source))
+    ctx2.on('agent/session-start', ({ source }) => void sources2.push(source))
     await ctx2.agents.resume({ resumeSessionId: SessionId('start-sess') })
     expect(sources2).toEqual(['resume'])
     await ctx2.fiber.dispose()
@@ -298,11 +298,11 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
       expect(ctx.agents.get(sessionId)?.session).toBe(session)
       order.push('session/created')
     })
-    ctx.on('agent/created', (agent) => {
+    ctx.on('agent/created', ({ agent }) => {
       expect(agent.status).toBe('idle')
       order.push('agent/created')
     })
-    ctx.on('agent/session-start', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => {
       expect(() => { agent.cancel({ kind: 'user' }) }).not.toThrow()
       order.push('agent/session-start')
     })
@@ -882,7 +882,7 @@ describe('configured-start failure edges', () => {
     configured.llm.registerAdapter(['mock'], new MockAdapter([]))
     configured.sessionPersistence.prepare = (id, signal) => ctx.sessionPersistence.prepare(id, signal)
     const configFailures: unknown[] = []
-    configured.on('agent-loop/config-start-failed', (_id, error) => { configFailures.push(error) })
+    configured.on('agent-loop/config-start-failed', ({ error }) => { configFailures.push(error) })
     const configWarnings: string[] = []
     const configWarn = configured.logger.warn.bind(configured.logger)
     configured.logger.warn = ((...args: unknown[]) => {
@@ -915,7 +915,7 @@ describe('configured-start failure edges', () => {
       return gate.promise
     }
     const failures: unknown[] = []
-    ctx.on('agent-loop/config-start-failed', (_id, error) => { failures.push(error) })
+    ctx.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
 
     const configured = new Context()
     await configured.plugin(LlmService)
@@ -926,7 +926,7 @@ describe('configured-start failure edges', () => {
     await configured.plugin(SessionPersistenceJsonl, { root })
     configured.llm.registerAdapter(['mock'], new MockAdapter([]))
     configured.sessionPersistence.prepare = (id, signal) => ctx.sessionPersistence.prepare(id, signal)
-    configured.on('agent-loop/config-start-failed', (_id, error) => { failures.push(error) })
+    configured.on('agent-loop/config-start-failed', ({ error }) => { failures.push(error) })
     const loop = await configured.plugin(AgentLoop, {
       agents: [{ id: 'main', resumeSessionId: sessionId, provider: 'mock', model: 'mock' }],
     })

packages/core/agent-loop/tests/scope-lifecycle.spec.ts

@@ -31,7 +31,7 @@ async function harness(adapter: MockAdapter = new MockAdapter([textResponse('ok'
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') {
         dispose()
         resolve()
@@ -199,7 +199,7 @@ describe('agent scope lifecycle', () => {
     const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
 
     const heard: string[] = []
-    a.ctx.on('agent/status', (subject, status) => void heard.push(`a-sees:${subject.id}:${status}`))
+    a.ctx.on('agent/status', ({ agent: subject, status }) => void heard.push(`a-sees:${subject.id}:${status}`))
     a.ctx.on('session/event', (_s, event) => {
       if (event.type === 'user/message') heard.push('a-sees:user-message')
     })
@@ -217,7 +217,7 @@ describe('agent scope lifecycle', () => {
   it('runs setup in the guaranteed slot: scoped world complete before session-start and the first assembly', async () => {
     const ctx = await harness()
     const order: string[] = []
-    ctx.on('agent/session-start', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => {
       order.push('session-start')
       // The scoped section is already registered by the time session-start fires.
       void ctx.systemPrompt.assemble(assembleContextFor(agent)).then((assembly) => {
@@ -673,19 +673,19 @@ describe('agent scope lifecycle', () => {
     ctx.on('session/created', (session) => {
       if (session.id === SessionId('agent-created-barrier-s')) lifecycle.push('session-created')
     })
-    ctx.on('agent/created', (agent) => {
+    ctx.on('agent/created', ({ agent }) => {
       if (agent.id !== SessionId('agent-created-barrier-s')) return
       lifecycle.push('agent-created:dispose')
       disposeCurrentLifecycle(ownerCtx)
     })
-    ctx.on('agent/created', (agent) => {
+    ctx.on('agent/created', ({ agent }) => {
       if (agent.id !== SessionId('agent-created-barrier-s')) return
       expect(ctx.agents.get(agent.id)).toBe(agent)
       expect(ctx.sessions.get(agent.session.id)).toBe(agent.session)
       agent.ctx.effect(() => () => { lifecycle.push('scope-disposed') })
       lifecycle.push('agent-created:observer')
     })
-    ctx.on('agent/disposed', (agent) => {
+    ctx.on('agent/disposed', ({ agent }) => {
       if (agent.id === SessionId('agent-created-barrier-s')) lifecycle.push('agent-disposed')
     })
     ctx.on('session/disposed', (session) => {
@@ -720,8 +720,8 @@ describe('agent scope lifecycle', () => {
     const starts: string[] = []
     let ownerCtx!: Context
     let creating!: ReturnType<typeof ctx.agents.create>
-    ctx.on('agent/session-start', agent => void starts.push(agent.id))
-    ctx.on('agent/created', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => void starts.push(agent.id))
+    ctx.on('agent/created', ({ agent }) => {
       if (agent.id === SessionId('listener-dispose-s')) disposeCurrentLifecycle(ownerCtx)
     })
 
@@ -749,15 +749,15 @@ describe('agent scope lifecycle', () => {
     const statuses: string[] = []
     let scopeDisposed = false
     let observerSawLive = false
-    ctx.on('agent/status', (agent, status) => {
+    ctx.on('agent/status', ({ agent, status }) => {
       if (agent.id === SessionId('session-start-dispose-s')) statuses.push(status)
     })
-    ctx.on('agent/session-start', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => {
       if (agent.id !== SessionId('session-start-dispose-s')) return
       announced = agent
       disposeCurrentLifecycle(ownerCtx)
     })
-    ctx.on('agent/session-start', (agent) => {
+    ctx.on('agent/session-start', ({ agent }) => {
       if (agent.id !== SessionId('session-start-dispose-s')) return
       expect(ctx.agents.get(agent.id)).toBe(agent)
       expect(ctx.sessions.get(agent.session.id)).toBe(agent.session)
@@ -840,7 +840,7 @@ describe('agent scope lifecycle', () => {
     const ctx = await harness()
     let boom = true
     const disposed: string[] = []
-    ctx.on('agent/disposed', agent => void disposed.push(agent.id))
+    ctx.on('agent/disposed', ({ agent }) => void disposed.push(agent.id))
     ctx.on('session/created', () => {
       if (boom) { boom = false; throw new Error('boom created') }
     })
@@ -861,11 +861,11 @@ describe('agent scope lifecycle', () => {
     const lifecycle: string[] = []
     ctx.on('session/created', (session) => { lifecycle.push(`session-created:${session.id}`) })
     ctx.on('session/disposed', (session) => { lifecycle.push(`session-disposed:${session.id}`) })
-    ctx.on('agent/created', (agent) => {
+    ctx.on('agent/created', ({ agent }) => {
       lifecycle.push(`agent-created:${agent.id}`)
       throw new Error('agent observer failed')
     })
-    ctx.on('agent/disposed', (agent) => { lifecycle.push(`agent-disposed:${agent.id}`) })
+    ctx.on('agent/disposed', ({ agent }) => { lifecycle.push(`agent-disposed:${agent.id}`) })
 
     await expect(ctx.agents.create({
       sessionId: SessionId('partial-session'),
@@ -911,10 +911,10 @@ describe('agent scope lifecycle', () => {
     const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
     const other = ctx.agentLoop.create(SessionId('a2'), { provider: 'mock', model: 'mock' })
     const heard: string[] = []
-    agent.ctx.on('agent/error', (subject: Agent, turn: number) => void heard.push(`${subject.id}:${turn}`))
+    agent.ctx.on('agent/error', ({ agent: subject, turn }) => void heard.push(`${subject.id}:${turn}`))
 
-    agentEvents(ctx, other).emit('agent/error', 1, 0, new Error('not for a1'))
-    agentEvents(ctx, agent).emit('agent/error', 2, 0, new Error('for a1'))
+    agentEvents(ctx, other).emit('agent/error', { turn: 1, step: 0, error: new Error('not for a1') })
+    agentEvents(ctx, agent).emit('agent/error', { turn: 2, step: 0, error: new Error('for a1') })
     expect(heard).toEqual(['a1:2'])
   })
 
@@ -1064,7 +1064,7 @@ describe('agent scope lifecycle', () => {
     })
     const agent = handle.agent
     let reentered = false
-    ctx.on('agent/status', (subject, status) => {
+    ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject !== agent || status !== 'idle' || reentered) return
       reentered = true
       agent.followup(createUserMessage({ content: [{ type: 'text', text: 'reentrant' }], source: { kind: 'user' } }))

packages/core/agent-loop/tests/tool-calls.spec.ts

@@ -31,7 +31,7 @@ async function harness(adapter: MockAdapter, maxParallelToolCalls?: number) {
 
 function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
   return new Promise((resolve) => {
-    const dispose = ctx.on('agent/status', (subject, status) => {
+    const dispose = ctx.on('agent/status', ({ agent: subject, status }) => {
       if (subject === agent && status === 'idle') { dispose(); resolve() }
     })
   })