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

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

.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.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 .agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md
-2026-07-16-explicit-turn-cancellation.md: cce649976c9f4f596d5306b9fe8c3fd49a0e1adc
-2026-07-16-explicit-turn-cancellation.zh.md: 6f8b83fdb42af03c97dc2e8a9345a01acc6019fc
+2026-07-16-explicit-turn-cancellation.md: ca56c77a097e3008a50c2aec24040a4f4b6f0ba3
+2026-07-16-explicit-turn-cancellation.zh.md: bf410e5c7284a9c9914edbd14445074e71dd6943

.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md

@@ -20,7 +20,7 @@ AgentLoop privately owns one `TurnCancellation` per prospective turn. It install
 
 The driver keeps only a cause-less pre-run marker for queued work cancelled before a turn is claimed. An effective `cancel()` emits the observe-only `agent/cancel-requested` notification with its resolved typed cause before clearing queued and steering work or aborting the holder; notification failures cannot veto the stop, and an idle call emits nothing. Work synchronously queued by a notification observer is included in that clear, while work queued by a later signal abort observer belongs to the next turn. If a `running` listener synchronously cancels old work and sends a replacement, the driver discards the aborted holder and creates a fresh one for the replacement. Repeated cancellation is first-wins for the active holder, while later calls may still clear newly queued pending work.
 
-The explicit event signatures keep their positional form and place `signal` inside `PreStepContext` or immediately before a waterfall's final `next`. Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
+The explicit event signatures pass a single payload object: agent-scoped events carry `agent` and `signal` in the payload with `next` last, and the remaining seams keep `signal` immediately before a waterfall's final `next`. `PreStepContext` and `RequestFailureContext` are retired, with their fields folded into the `agent/pre-step` and `agent/request-error` payloads ([payload-object events](2026-08-06-agent-event-payload-objects.md)). Pre-step entry, request configuration, request-error recovery, model generation, tool execution, approval, turn stopping, and subagent or workflow requests all receive the current signal. Hook bridges must also supply `RunHookOptions.signal`, so a turn cancellation reaches the bash executor's process-group kill and join boundary. `SystemPrompt.assemble()` carries `signal?: AbortSignal` in `AssembleContext` because that object is an explicit request value that can also represent signal-less assembly outside a turn. Listeners may cooperate with the signal but must not retain it to control another turn.
 
 `ctx.agents` continues to carry only the initiating Agent. Ambient Agent presence does not imply liveness, a current turn, or cancellation authority. The cause reader is private to the loop and states the machine-private slot invariant (only `cancel()` aborts a turn controller, always with a canonical frozen cause) instead of re-validating the reason structurally; no public helper reads a cause off an arbitrary signal. Concurrent Agents isolate both their initiator identities and their turn signals; a child driver shadows the parent initiator while its parent request signal still travels through the subagent seam.
 
@@ -44,7 +44,7 @@ Initiator-scope tests assert that every hook still observes the exact Agent and
 
 **Define speculative `superseded`, `timeout`, and `shutdown` variants now.** No current Agent cancellation producer implements those semantics. `shutdown` is already lifecycle disposal, and timeout or supersession should enter the union only with an owning policy and unique terminal meaning.
 
-**Expose public turn or step context wrappers.** Existing positional seams already identify Agent, turn, and step. A wrapper would widen every API, duplicate ownership, and tempt callers to treat a captured object as durable authority.
+**Expose public turn or step context wrappers.** Existing seams already identify Agent, turn, and step. A wrapper would widen every API, duplicate ownership, and tempt callers to treat a captured object as durable authority.
 
 **Abandon uncooperative work after a grace period.** Returning idle while same-process work still runs breaks teardown and resource-ownership guarantees. Hard termination requires a worker or process isolation boundary and is outside this control seam.
 

.agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.zh.md

@@ -20,7 +20,7 @@ AgentLoop 为每个待启动轮次私有地持有一个 `TurnCancellation`。它
 
 对于轮次被认领前已取消的排队工作，驱动器只保留一个不携带取消原因的运行前标记。实际生效的 `cancel()` 会先发出仅供观察的 `agent/cancel-requested` 通知并携带最终确定的类型化取消原因，然后才清除排队工作和 steering（中途引导）工作或中止持有者；通知失败不能阻止此次停止，空闲状态下调用则不发出任何通知。通知观察者同步加入队列的工作也会被这次清除，而稍后由 signal 中止观察者加入队列的工作属于下一个轮次。若 `running` 监听器同步取消旧工作并发送替代提示词，驱动器会丢弃已中止的持有者，并为替代提示词创建全新的持有者。同一活跃持有者上的重复取消遵循首次请求优先，后续调用仍可清除新入队的待处理工作。
 
-显式事件签名保留位置参数形式，并把 `signal` 放入 `PreStepContext`，或放在 waterfall（瀑布式事件）的最后一个参数 `next` 之前。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
+显式事件签名传递单个 payload 对象：agent 作用域事件在 payload 中携带 `agent` 和 `signal`，`next` 位于最后；其余 seam 保持 `signal` 紧邻 waterfall（瀑布式事件）的最终 `next` 之前。`PreStepContext` 与 `RequestFailureContext` 已退役，其字段并入 `agent/pre-step` 与 `agent/request-error` 的 payload（[payload-object 事件](2026-08-06-agent-event-payload-objects.md)）。pre-step 进入决策、请求配置、请求错误恢复、模型生成、工具执行、审批、轮次停止以及 subagent 或工作流请求都会收到当前 signal。钩子桥接器也必须提供 `RunHookOptions.signal`，使轮次取消能够到达 Bash 执行器终止进程组并等待其退出的边界。`SystemPrompt.assemble()` 在 `AssembleContext` 中携带 `signal?: AbortSignal`，因为该对象是显式请求值，也可表示轮次之外不携带 signal 的组装。监听器可以配合该 signal 取消，但不得保留它来控制其他轮次。
 
 `ctx.agents` 仍只携带发起 Agent。环境中的 Agent 并不代表存活、当前轮次或取消权限。cause 读取器是 loop 私有的，它直接陈述机器私有的 slot 不变量（只有 `cancel()` 会中止轮次控制器，且总是携带规范的冻结 cause），而不是对 reason 做结构化再校验；不存在从任意 signal 读取 cause 的公开辅助函数。并发 Agent 会同时隔离各自的发起方身份和轮次 signal；子驱动会遮蔽父发起方，而父请求 signal 仍通过 subagent seam 传递。
 
@@ -44,7 +44,7 @@ Agent dispose（资源释放）会在活跃持有者上请求仅用于运行时
 
 **现在就定义推测性的 `superseded`、`timeout` 和 `shutdown` 变体。** 当前没有 Agent 取消生产方实现这些语义。`shutdown` 已经属于生命周期 dispose；超时或替代只有在拥有明确归属策略和唯一终态含义时才应进入联合类型。
 
-**公开轮次或步骤上下文包装类型。** 现有位置参数 seam 已经标识 Agent、轮次和步骤。包装类型会加宽所有 API、重复归属，并诱导调用方把捕获的对象当成持久权限。
+**公开轮次或步骤上下文包装类型。** 现有 seam 已经标识 Agent、轮次和步骤。包装类型会加宽所有 API、重复归属，并诱导调用方把捕获的对象当成持久权限。
 
 **在宽限期后放弃不协作的工作。** 同进程工作仍在运行时就报告空闲状态，会破坏资源清理与资源归属保证。硬终止需要 worker 或进程隔离边界，不属于该控制 seam。
 

.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.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 .agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md
-2026-07-25-web-client-session-scope-and-provide-channel.md: aeefbe22a397e3d7ffb9f6427a3c70c8c8e8b940
-2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 056d50d45cef891e0e635d8bb4f2e73064ccdb87
+2026-07-25-web-client-session-scope-and-provide-channel.md: 3c51f06fca23a495f0fbc0cc4f1c289edea07b3b
+2026-07-25-web-client-session-scope-and-provide-channel.zh.md: 06fc1005785d9d11b52839f91c3bb4b99cad7d63

.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.md

@@ -93,7 +93,7 @@ Slot scope is the closed set `root | session-maybe | session`:
 - `session-maybe` follows the current session with ADOPTION identity (the only behavior — there is no hold-identity-forever mode): an incarnation born session-less keeps its React instance across the arrival of the FIRST session (the blank shell adopts it — no remount, the DOM survives), and from then on behaves exactly like a strict session entry — switching to a different session remounts, and dropping back to no-session remounts into a fresh blank incarnation that will adopt again. Component-local per-session state therefore clears by construction; state that must survive a switch belongs in session-bound sources (machine, store, hooks). With no session, `sessionId`, the results of `useSession`/`useInput`, and `inputActions` may all be absent. The unkeyed root `SessionMaybeProvider` drives these updates by subscribing to the runtime's atomic `currentProvide` projection — selection moves and provider-roster changes publish through the same source, so a roster change under a stable current id republishes the mounted bundle instead of stranding entries on an obsolete hook/prop schema — while `SessionMaybeProvideInfo` uses the static key map to retain the complete hook/prop shape even with no session; the per-entry adoption bookkeeping (incarnation-counter key) lives in the renderer's `SessionMaybeEntry`.
 - `session` guarantees that `sessionId`, every hook source, and every prop exist; each strict entry's error boundary is keyed by `sessionId`, so switching sessions recreates that entry and its session store.
 
-`conversation` is the resident `session-maybe` shell: `ConversationRoot`, HeroShell, the Workspace picker, the composer stack, and the overlay chain's fallback frame retain their React instances across the no-session → blank-session switch; `conversation.session` carries only the strict-session header/view. The composer bar (`conversation.composer.bar`) is itself `session-maybe`: with no session it renders inert (machine faces absent, `disabled` owner prop), and the same instance — textarea included — goes live when a session appears; the remaining input slots stay strict `session` and dispatch nothing until then. The blank → engaging/active transition never rebuilds the InputBar on a phase flip.
+`conversation` is the resident `session-maybe` shell: `ConversationRoot`, HeroShell, the Workspace picker, the root-owned scrollport and composer stack, and the overlay chain's fallback frame retain their React instances across the no-session → blank-session switch. Two strict entries fill fixed regions without reparenting that tree: `conversation.session.header` carries breadcrumb/tabs/actions above the scrollport, while `conversation.session` carries the view ring and draft mirror inside it; both share the same session-scoped chat store. The composer bar (`conversation.composer.bar`) is itself `session-maybe`: with no session it renders inert (machine faces absent, `disabled` owner prop), and the same instance — textarea included — goes live when a session appears; the remaining input slots stay strict `session` and dispatch nothing until then. The blank → engaging/active transition never rebuilds the InputBar on a phase flip.
 
 - The runtime's first built-in entry: the `'session'` hook — `useSession` itself rides the same mechanism, no special-casing.
 - Concurrent discipline: the render plane reads only from the hooks compartment (uSES consistency guarantee); props-compartment callbacks are used only in event-handler space; descriptor resolution is render-safe (idempotent caching, with prune reaping residue from abandoned renders).

.agents/notes/implemented/architecture/2026-07-25-web-client-session-scope-and-provide-channel.zh.md

@@ -93,7 +93,7 @@ slot scope 是闭集 `root | session-maybe | session`：
 - `session-maybe` 以**收养（adoption）身份语义**跟随 current session（唯一行为——不存在「永久保持实例」模式）：空态出生的化身在**第一个** session 到来时保持 React 实例（空壳收养它——不重挂，DOM 存活）；此后行为与严格 session entry 完全一致——切到不同 session 重挂，跌回无 session 也重挂为崭新的空态化身（之后再次收养）。因此组件本地的 per-session 状态**由构造保证**随切换清零；需要活过切换的状态必须住 session 绑定的源（machine、store、hooks）。无 session 时 `sessionId`、`useSession`/`useInput` 的选择结果及 `inputActions` 均可缺省。根部无 key 的 `SessionMaybeProvider` 通过订阅 runtime 的原子 `currentProvide` 投影驱动这条更新——选择移动和提供方名册变化经同一 source 发布，current id 不变时的名册变化也会重发已挂载 bundle，而不是把 entry 困在过期的钩子/prop 形状上——`SessionMaybeProvideInfo` 靠静态键表在无 session 时仍保留完整钩子/prop 形状；逐 entry 的收养记账（化身计数 key）住在 renderer 的 `SessionMaybeEntry`。
 - `session` 保证 `sessionId`、所有钩子 source 与 props 均存在；每个严格 entry 的错误边界以 `sessionId` 为 key，切换 session 会重建该 entry 及其 session store。
 
-`conversation` 是 `session-maybe` 的常驻外壳：`ConversationRoot`、HeroShell、Workspace picker、composer stack 与 overlay chain 的 fallback 外框在无 session → blank session 的切换中保持 React 实例；`conversation.session` 只承载严格 session 的 header/view。composer bar（`conversation.composer.bar`）本身即为 `session-maybe`：无 session 时以惰性态渲染（machine face 缺席、`disabled` owner prop），session 出现后同一实例（含 textarea）转为 live；其余输入 slot 保持严格 `session`，在此之前不分发任何条目。blank → engaging/active 的 InputBar 不因 phase 翻转而重建。
+`conversation` 是 `session-maybe` 的常驻外壳：`ConversationRoot`、HeroShell、Workspace picker、root 持有的 scrollport 与 composer stack，以及 overlay chain 的 fallback 外框，在无 session → blank session 的切换中保持 React 实例。两个严格 session entry 只填入固定区域，不改变该树的父级：`conversation.session.header` 在 scrollport 上方承载 breadcrumb／tab／action，`conversation.session` 在其内部承载 view ring 与 draft mirror；二者共享同一个 session scope chat store。composer bar（`conversation.composer.bar`）本身即为 `session-maybe`：无 session 时以惰性态渲染（machine face 缺席、`disabled` owner prop），session 出现后同一实例（含 textarea）转为 live；其余输入 slot 保持严格 `session`，在此之前不分发任何条目。blank → engaging/active 的 InputBar 不因 phase 翻转而重建。
 
 - 运行时内建第一条：`'session'` 钩子——`useSession` 本身走同一机制，无特判。
 - Concurrent 纪律：渲染平面只从 hooks 格读（uSES 一致性保证）；props 格回调只在事件 handler 空间用；描述符解析 render-safe（幂等缓存、废弃渲染残留由 prune 收尸）。

.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.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 .agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md
-2026-07-25-web-input-machine-and-slash-pipeline.md: 977df6508e1a1cd54cf1ddb469a6bfb835f60071
-2026-07-25-web-input-machine-and-slash-pipeline.zh.md: f70065c8b356b2ed5ca6ab317fbdeb5177f058fa
+2026-07-25-web-input-machine-and-slash-pipeline.md: 39ef214a94fcd019f535fb60136d5dcc09b54e60
+2026-07-25-web-input-machine-and-slash-pipeline.zh.md: 9b0ca0cadbc5e0212048b165f0d60d567a5639ad

.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.md

@@ -69,9 +69,9 @@ A trigger/menu/pick pipeline with zero knowledge of "commands":
 ### hub / facade: the resident shell and the strict-session input body
 
 - The hub (trigger/decoration registries + send orchestration) takes the slash/command services as optional `ctx.get()` dependencies: without ui-slash or the command surfaces, input still sends and receives normally — graceful degradation.
-- Each materialized Session has exactly one `SessionInputShell` (the facade), created and torn down with the session scope; with no session, no input machine is built. `ConversationRoot` is itself the `session-maybe` resident shell, holding HeroShell, the Workspace picker, the composer stack, and the chain-fallback frame.
+- Each materialized Session has exactly one `SessionInputShell` (the facade), created and torn down with the session scope; with no session, no input machine is built. `ConversationRoot` is itself the `session-maybe` resident shell, holding HeroShell, the Workspace picker, the composer stack, and the chain-fallback frame. It always owns the same scrollport and composer seat; separate strict-session header and body outlets fill those fixed regions after a Session appears.
 - The composer bar is one `session-maybe` slot entry rendered unconditionally: with no session the same InputBar renders inert (machine faces absent, `disabled` owner prop), and once `connectWorkspace` returns a blank session the same instance goes live — the textarea DOM survives the no-session → blank transition and every later phase flip; `ConversationRoot`, the Hero, and the layout skeleton hold throughout.
-- ConversationRoot's Hero criterion is `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`. The first submit enters engaging synchronously, and a failure keeps the composer and the error context rather than falling back to the blank Hero; the sidebar's blank bit flips false only after a prompt is successfully accepted.
+- ConversationRoot's Hero criterion is `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`: a summary-proven blank Session remains Hero in every open state, while an unproven Session settles during loading. The first submit enters engaging synchronously, and a failure keeps the composer and the error context rather than falling back to the blank Hero; the sidebar's blank bit flips false only after a prompt is successfully accepted.
 - Sending unifies in the hub defaultSink: after an optimistic draft clear it goes only through `session.prompt` with `mode:'queue'` (the Web UI has no steer entry; host-wire `mode:'steer'` remains outside this machine); backfill happens only when it fails and the live draft is still empty — a user who has kept typing is never overwritten. No Draft materialize or attach transaction exists.
 - When the blank Hero re-picks the Workspace, the shell calls `connectWorkspace`; if the target session differs, the non-empty draft moves from the current shell to the target shell before the new id is opened, and the old blank session survives but is no longer current.
 - The Notifier's two-bit contract: `dirty` (snapshot freshness, clearable by an `ensureFresh` pull) and `notifyPending` (notification debt, cleared only by a flush) are mutually independent — a pull must not swallow a push, and object-layer push subscribers (watchTransaction) depend on this guarantee.
@@ -93,9 +93,10 @@ skill/@subagent references skip the placeholder + occurrence identity chain —
 
 ### The slot system
 
-`conversation` is itself session-maybe; its session content and the composer input slots are strict session, while the Hero Workspace picker stays root. The child slots are all declared by ui-conversation's conversation registration:
+`conversation` is itself session-maybe; its session content and the composer input slots are strict session, while the Hero Workspace picker stays root. The root registration renders the header outlet above its resident scrollport and the body outlet inside it, before the resident composer seat. The child slots are all declared by ui-conversation's conversation registration:
 
-- `conversation.session` (single) — the strict-session header, view ring, and chat store; rebuilt when the session id switches.
+- `conversation.session.header` (single) — strict-session breadcrumb, view tabs, and header actions above the resident scrollport.
+- `conversation.session` (single) — the strict-session view ring and draft mirror inside the resident scrollport. Header and body share the same session-scoped chat store; each is rebuilt when the session id switches.
 - `conversation.composer.bar` (single) — the slot for the InputBar itself: the InputBar is a true slot entry (self-registered into its own slot) and the content of the composer chain's fallback; it is not a chain entry — the chain's single election would unmount it on a takeover, breaking textarea DOM survival.
 - `conversation.input.overlay` — the floating-overlay anchor inside the input card; registrants' inject resolves each one's own per-session controller by the slot sessionId.
 - `conversation.input.dock` — the stacked strip above the input (QueueDock's read-only queue list lands here), ordered by `order`.
@@ -128,7 +129,7 @@ The state machine's entire behavior is covered by pure-JS unit tests (event sequ
 
 ## Consequences
 
-- One resident conversation shell carries no-session/blank/active: no session → blank guarantees only the outer frame's React identity, allowing the disabled textarea to be replaced by the strict InputBar; the same blank session → engaging/active keeps the InputBar and the textarea. EmptyState and the controlled intent chain (`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`) are deleted along with their last consumer.
+- One resident conversation shell carries no-session/blank/active: no session → blank preserves ConversationRoot, Hero, the root-scoped Workspace picker, scrollport, composer seat, InputBar, and textarea; only the strict header and body outlets gain content. The same blank session → engaging/active also keeps the InputBar and textarea. EmptyState and the controlled intent chain (`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`) are deleted along with their last consumer.
 - The input surface's zero knowledge of commands plus optional dependencies: pure input works without the command packages; `@` references and skill references get free reuse of the same menu/pick pipeline. The cost is that space/enter adjudication is a per-source polling protocol whose answer semantics (sync/async, the meaning of undefined) are a frozen contract.
 - Transactionalized submission (attempt seq + the drift guard) makes the three defect classes — stale-result backwash, session switching, concurrent replay — structurally impossible, pinned by the matrix tests.
 - Known gaps: chip fidelity across refresh (paste matching is reusable for it) has no workstream yet; the subagent reference's model representation awaits its business workstream.

.agents/notes/implemented/architecture/2026-07-25-web-input-machine-and-slash-pipeline.zh.md

@@ -69,9 +69,9 @@ occurrence 表与 chip 三投影：
 ### hub / facade：常驻外壳与严格 session 输入体
 
 - hub（trigger/decoration 注册表 + 发送编排）对 slash/command 服务是可选 `ctx.get()` 依赖：无 ui-slash/命令面时输入正常收发，优雅降级。
-- 每个实体 Session 只有一个 `SessionInputShell`（facade），随 session scope 创建和拆除；无 session 时不造 input machine。`ConversationRoot` 自身是 `session-maybe` 常驻外壳，持有 HeroShell、Workspace picker、composer stack 与 chain fallback 外框。
+- 每个实体 Session 只有一个 `SessionInputShell`（facade），随 session scope 创建和拆除；无 session 时不造 input machine。`ConversationRoot` 自身是 `session-maybe` 常驻外壳，持有 HeroShell、Workspace picker、composer stack 与 chain fallback 外框。它始终拥有同一个 scrollport 与 composer seat；Session 出现后，彼此独立的严格 session header 和 body outlet 只填入这些固定区域。
 - composer bar 是一个无条件渲染的 `session-maybe` slot entry：无 session 时同一个 InputBar 以惰性态渲染（machine face 缺席、`disabled` owner prop），`connectWorkspace` 返回 blank session 后同一实例转为 live——textarea DOM 在无 session → blank 切换及其后每次 phase 翻转中都不重建；`ConversationRoot`、Hero 与布局骨架全程保持。
-- ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || openState === 'loading'))`。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。
+- ConversationRoot 的 Hero 判据是 `sessionId === undefined || (composerPhase === 'blank' && (openState === 'open' || summaryBlank === true))`：summary 已证实为空的 Session 在任何 open state 下都保持 Hero，未经证实的 Session 则在 loading 期间进入 settling。首次 submit 同步进入 engaging，失败也保留 composer 与错误上下文，不退回 blank Hero；sidebar 的 blank 位只在 prompt 成功受理后翻 false。
 - 发送统一在 hub defaultSink：乐观清稿后只走 `session.prompt` 且固定 `mode:'queue'`（Web UI 无 steer 入口；host 线缆上的 `mode:'steer'` 不经此 machine）；失败且 live draft 仍为空才回填，用户已经继续输入则不覆盖。不存在 Draft materialize 或 attach 事务。
 - blank Hero 改选 Workspace 时，外壳调用 `connectWorkspace`；目标 session 不同时把非空 draft 从当前 shell 搬到目标 shell，再 open 新 id，旧 blank session 留存但不再 current。
 - Notifier 双位契约：`dirty`（快照新鲜度，`ensureFresh` 拉取可清）与 `notifyPending`（通知欠账，只有 flush 清）各自独立——拉取不得吞推送，对象层推订阅者（watchTransaction）依赖这一保证。
@@ -93,9 +93,10 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 
 ### slot 体系
 
-`conversation` 本身是 session-maybe；其会话内容与 composer 输入 slot 严格限定为 session，Hero Workspace picker 保持 root。子 slot 均由 ui-conversation 的 conversation 注册声明：
+`conversation` 本身是 session-maybe；其会话内容与 composer 输入 slot 严格限定为 session，Hero Workspace picker 保持 root。root 注册把 header outlet 渲染在常驻 scrollport 上方，把 body outlet 渲染在其内部、常驻 composer seat 之前。子 slot 均由 ui-conversation 的 conversation 注册声明：
 
-- `conversation.session`（single）——严格 session 的 header、view ring 与 chat store；session id 切换时重建。
+- `conversation.session.header`（single）——常驻 scrollport 上方严格 session 的 breadcrumb、view tab 与 header action。
+- `conversation.session`（single）——常驻 scrollport 内严格 session 的 view ring 与 draft mirror。header 和 body 共享同一个 session scope chat store；session id 切换时各自重建。
 - `conversation.composer.bar`（single）——InputBar 本体的 slot：InputBar 是真 slot entry（自有 slot 自注册），composer chain fallback 的内容；不做 chain entry——chain 单选举会在 takeover 时卸载它，破坏 textarea DOM 存活。
 - `conversation.input.overlay`——输入卡内浮层锚点；注册者 inject 按 slot sessionId 解析各自 per-session controller。
 - `conversation.input.dock`——输入上方堆叠条（QueueDock 的队列只读列表落此），order 定序。
@@ -128,7 +129,7 @@ skill/@subagent 引用不走占位符 + occurrence 身份链——pick 直接把
 
 ## 后果
 
-- 一个常驻 conversation 外壳承接 no-session/blank/active：无 session → blank 只保证大框架 React identity，允许 disabled textarea 替换为严格 InputBar；同一 blank session → engaging/active 保持 InputBar 与 textarea。EmptyState 与受控 intent 链（`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`）随最后消费者一并删除。
+- 一个常驻 conversation 外壳承接 no-session/blank/active：无 session → blank 保持 ConversationRoot、Hero、root scope Workspace picker、scrollport、composer seat、InputBar 与 textarea；只有严格 session header 和 body outlet 开始承载内容。同一 blank session → engaging/active 也保持 InputBar 与 textarea。EmptyState 与受控 intent 链（`sessions.updateIntent`/`updatePendingPrompt`/`workspaces.sendSession`）随最后消费者一并删除。
 - 输入面对命令零知识 + 可选依赖：无命令包时纯输入可用；`@` 引用与 skill 引用免费复用同一菜单/pick 管线。代价是空格/回车裁决是逐 source 轮询协议，其应答语义（同步/异步、undefined 含义）为冻结契约。
 - 提交事务化（attempt seq + 漂移守卫）使晚到结果回灌、会话切换、concurrent 重放三类缺陷结构性不可能，由矩阵测试钉住。
 - 已知欠账：chip 跨刷新保真（可复用粘贴匹配）未立项；subagent 引用的模型表示待业务立项。

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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 .agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md
+2026-08-05-profile-plugin-bundles.md: 11a8ac3d4005371ca9596ba237aaf42a8e770dee
+2026-08-05-profile-plugin-bundles.zh.md: 0e9ebf657ccb9d05967d90a935b356acf287a24c

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md

@@ -0,0 +1,33 @@
+# Agent Note: Profile plugin bundles replace the fixed surface overlays
+
+Status: implemented
+
+English | [中文](2026-08-05-profile-plugin-bundles.zh.md)
+
+## Problem
+
+The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.yml` shipped inside `apps/cli`, three bespoke entry modes (`--config`, `web`, `-p`) each with its own layer stack, and a single global personal overlay (`$DSH_HOME/config.yaml`). There was no way to install an out-of-tree plugin (a TUI, a provider pack) into a shipped surface without editing the repository, and no place where a third-party package could contribute a default composition.
+
+## Decision
+
+Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer, then `--patch` overlays, then flag patches — one `applyEntryPatches` call, identical for boot, flag derivation, and `--dump-config`.
+
+The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh --profile headless "task"` replaces `-p`; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
+
+Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
+
+Two supporting refactors: the webserver's built-in static dist serving became the single-owner **fallback seat** (`registerFallback`/`applyIndexTaps`), with the SPA server extracted to `@deepseek-ai/dsh-frontend-static` so the web bundle owns its dist as composition, not launcher code; and the personal-overlay machinery of the [dsh CLI personal-config decision](../feature/2026-07-20-dsh-cli-personal-config.md) (`loadPersonalPatches`, `$DSH_HOME/config.yaml`) was retargeted to the per-profile and home-level `cordis.patch.yml` layers (`loadOptionalPatches`, `watchUserPatches` taking a filename), superseding that note's entry modes and file location while keeping its Harness-home root, patch semantics, and fail-loud parsing.
+
+## Alternatives considered
+
+- **Dependency-scan plus partial `patchOrder`** (the original sketch): scanning `dependencies` for bundles and ordering unlisted ones alphabetically has two sources of truth and an implicit tie-break; one explicit ordered `dsh.profile.bundles` list is smaller and fully deterministic. A raw `pnpm add` inside the profile installs a library without activating any patch — explicit, no spooky scan.
+- **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
+- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` seam is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
+- **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
+
+## Consequences
+
+- New composition surfaces (a TUI, provider packs) ship as ordinary npm packages installable per profile; the repository no longer needs a row for every deployment shape.
+- `apps/cli` shrank to argv parsing, profile machinery consumption, and the pnpm forwarder; `AppCLIEntry` and the per-surface boot paths are gone.
+- The keyless web e2e scaffold boots the same bundle layers over the same empty-root shape as production, including the profiles module fallback, so composition drift between test and product fails loudly.
+- Backends reject nothing old on disk (pre-release stance): `$DSH_HOME/config.yaml` is simply no longer read.

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md

@@ -0,0 +1,33 @@
+# Agent Note: profile 插件组合包取代固定的表层 overlay
+
+Status: implemented
+
+[English](2026-08-05-profile-plugin-bundles.md) | 中文
+
+## Problem
+
+`dsh` 启动器硬编码了自己的组合：`base.cordis.yml` + `web.cordis.yml` 随 `apps/cli` 一起交付，三种各自定制的入口模式（`--config`、`web`、`-p`）各带一套层栈，外加一个全局的个人 overlay（`$DSH_HOME/config.yaml`）。想把树外插件（一个 TUI、一个提供方扩展包）装进已交付的表层，只能修改仓库；第三方包也没有任何位置可以贡献默认组合。
+
+## Decision
+
+一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
+
+已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh --profile headless "task"` 取代 `-p`；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
+
+解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
+
+两项配套重构：webserver 内置的静态 dist 服务改为单一所有者的**回退席位**（`registerFallback`／`applyIndexTaps`），SPA 服务器提取到 `@deepseek-ai/dsh-frontend-static`，使 web 组合包以组合的方式持有自己的 dist，而不是靠启动器代码；[dsh CLI 个人配置决策](../feature/2026-07-20-dsh-cli-personal-config.md)的个人 overlay 机制（`loadPersonalPatches`、`$DSH_HOME/config.yaml`）改为面向逐 profile 与 home 级的 `cordis.patch.yml` 层（`loadOptionalPatches`、接受文件名的 `watchUserPatches`），取代该笔记的各入口模式与文件位置，同时保留其 Harness home 根目录、patch 语义与大声失败的解析。
+
+## Alternatives considered
+
+- **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
+- **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
+- **在组合包 manifest（元数据清单）中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` seam 是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
+
+## Consequences
+
+- 新的组合表层（TUI、提供方扩展包）以普通 npm 包形式交付，可按 profile 安装；仓库不再需要为每种部署形态各留一行。
+- `apps/cli` 收缩为 argv 解析、profile 机制的消费方和 pnpm 转发器；`AppCLIEntry` 与各表层专属的启动路径全部移除。
+- 无密钥 web e2e 脚手架以与生产相同的空根形态启动相同的组合包层，包括 profiles 模块回退，因此测试与产品之间的组合漂移会大声失败。
+- 后端不拒绝磁盘上的任何旧格式（发布前姿态）：`$DSH_HOME/config.yaml` 只是不再被读取。

.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.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 .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md
+2026-08-06-agent-event-payload-objects.md: 470c8fb3f9282005829846307778d3d1088c3888
+2026-08-06-agent-event-payload-objects.zh.md: ff201a7c3134c0ef809c9a798d65412541f9f1e7

.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.md

@@ -0,0 +1,27 @@
+# Agent Note: Agent-scoped events dispatch a single payload object
+
+Status: implemented
+
+English | [中文](2026-08-06-agent-event-payload-objects.zh.md)
+
+## Problem
+
+Agent-scoped events historically took positional arguments: a leading `agent` subject, event-specific fields, and a trailing `next` for waterfall/serial events. Adding a field or retiring a context type (as with `PreStepContext` and `RequestFailureContext`) rewrote every listener and emitter across packages, and the contract stayed spread across the parameter list instead of one named payload.
+
+## Decision
+
+Every agent-scoped event takes exactly one payload object as its first argument. The payload always carries the subject (`agent`), the event's fields, and the cancellation `signal` when the event has one; `next` remains the last argument of waterfall/serial events. The affected events are the twelve `agent/*` events, `agent-loop/config-start-failed` (the only one without a subject), and `goal/changed`.
+
+`PreStepContext` and `RequestFailureContext` are retired; their fields live directly in the `agent/pre-step` and `agent/request-error` payloads.
+
+Dispatch is fused: `agentEvents(ctx, agent)` (and the one-shot `emitAgentEvent`) injects the subject so the scope carrier key and the payload's `agent` cannot diverge, and the injected subject wins even over a structurally acceptable payload that happens to carry an `agent` field. `ReactLoopAgent` builds its dispatcher once in the constructor and routes every emit, serial, and waterfall through it, so hot-path dispatches allocate nothing.
+
+## Alternatives considered
+
+**Keep positional signatures.** Adding a field or retiring a context type would keep rewriting every listener and emitter, and the contract would stay spread across the parameter list instead of one named payload.
+
+**Hand-build the subject at each dispatch site.** The loop's intermediate design called `ctx.waterfall(this.carrier, …)` with a manually constructed `{ agent: this, … }` payload; it avoided per-dispatch allocation but duplicated the subject injection and let the scope key and the payload subject diverge. The fused dispatcher is the single injection point for every dispatch mode.
+
+## Consequences
+
+Listener signatures name the full payload once, so extending a payload or retiring a context type is a one-shape change across all listeners and emitters. The subject/scope coupling is enforced by the dispatcher for every dispatch mode, and the loop's hot paths stay allocation-free.

.agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: Agent 作用域事件 dispatch 单个 payload 对象
+
+Status: implemented
+
+[English](2026-08-06-agent-event-payload-objects.md) | 中文
+
+## 问题
+
+Agent 作用域事件历来采用位置参数：开头的 `agent` 主体、事件专属字段，以及末尾用于 waterfall（瀑布式事件）/serial 事件的 `next`。新增字段或退役上下文类型（如 `PreStepContext` 与 `RequestFailureContext`）都会迫使跨包重写每个监听器和 emitter，契约也一直分散在参数列表中，而不是集中在一个具名 payload 中。
+
+## 决策
+
+每个 agent 作用域事件都将恰好一个 payload 对象作为其第一个参数。payload 始终携带主体（`agent`）、事件的字段，以及事件有取消信号时的取消 `signal`；`next` 仍然是 waterfall/serial 事件的最后一个参数。受影响的事件是十二个 `agent/*` 事件、`agent-loop/config-start-failed`（唯一没有主体的事件）以及 `goal/changed`。
+
+`PreStepContext` 与 `RequestFailureContext` 已退役；它们的字段直接存在于 `agent/pre-step` 与 `agent/request-error` 的 payload 中。
+
+dispatch 是融合的：`agentEvents(ctx, agent)`（以及一次性 `emitAgentEvent`）注入主体，使作用域载体键与 payload 的 `agent` 不可能分叉；即使某个结构上可接受的 payload 恰好携带 `agent` 字段，注入的主体仍然优先。`ReactLoopAgent` 在构造函数中构建一次 dispatcher，并将每个 emit、serial 和 waterfall 都经由它路由，因此热路径上的 dispatch 不产生任何分配。
+
+## 考虑过的替代方案
+
+**保留位置签名。** 新增字段或退役上下文类型依旧会重写每个监听器和 emitter，契约也会继续分散在参数列表中，而不是集中在一个具名 payload 中。
+
+**在每个 dispatch 位置手工构造主体。** loop 的中间设计调用 `ctx.waterfall(this.carrier, …)`，传入手工构造的 `{ agent: this, … }` payload；它避免了每次 dispatch 的分配，却重复了主体注入，并让作用域键与 payload 主体分叉。融合的 dispatcher 是每种 dispatch 模式的唯一注入点。
+
+## 后果
+
+监听器签名一次性命名完整 payload，因此扩展 payload 或退役上下文类型，对所有监听器和 emitter 都是一次形状变更。主体/作用域耦合由 dispatcher 在每种 dispatch 模式下强制执行，且 loop 的热路径保持零分配。

.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.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 .agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md
+2026-08-06-web-shell-dist-chunk-layout.md: 1c7b4273dc243685317b149e2fd7fddf2a6c18d1
+2026-08-06-web-shell-dist-chunk-layout.zh.md: 6f4b94e0bd7412e480458e34922273b389aa8892

.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.md

@@ -0,0 +1,50 @@
+# Agent Note: Web shell dist chunk split and directory layout
+
+Status: implemented
+
+English | [中文](2026-08-06-web-shell-dist-chunk-layout.zh.md)
+
+## Problem
+
+The apps/web shell previously built into a single ~1.2 MB (minified) index chunk, roughly 80% of it vendor bytes — KaTeX, the boot grammars and the shiki engine, react-dom, the markdown pipeline — fused with all the workspace shell code (about one fifth). Any one-line shell change rehashed the whole chunk, forcing returning clients to redownload everything; `dist/assets/` was a flat single-level spread of 100-plus files (the main chunk, 23 lazy-loaded grammar chunks, 59 KaTeX font faces, and sourcemaps intermixed), impossible to navigate.
+
+## Decision
+
+`apps/web/vite.config.ts` splits the shell into two initial chunks via `manualChunks` and sorts the output into directories via naming functions; the entire configuration contains zero regexes — an exact-package-name Set, a filename list, an extension list.
+
+**Membership** (`VENDOR_PACKAGES`, by exact npm package name):
+
+- `vendor` = the three heavy rendering families: math (katex), highlight (shiki), markdown (the micromark/mdast parse pipeline — the incremental React renderer above it is workspace code and not part of this). The live membership is `VENDOR_PACKAGES`; the list is the packages workspace code **imports directly**: the remaining private transitive dependencies (the oniguruma family, @shikijs/core, character tables, dozens more) are referenced only by listed members, so rollup's chunk coloring pulls them into vendor automatically; dependencies shared with the index side fall back to index, diluting it by a few KB — not a correctness issue.
+- **Every vendor member must be react-free (the boundary invariant)**: rollup folds a module shared between the entry and a manual chunk into the manual chunk — one listed package importing react/jsx-runtime would drag the single shared react copy into vendor, away from index. The React side of markdown/math rendering is workspace code and naturally lives in index, so the whole react family stays pinned to index.
+- `index` (the default chunk) = the react family (react, react-dom, scheduler, use-sync-external-store), vendored cordis, all workspace code, and the unlisted small pieces (anser, clsx).
+- `@shikijs/langs` is special-cased: the boot grammars (`BOOT_GRAMMAR_FILES`: typescript, shellscript, json — the three that highlight.ts statically imports, all self-contained data modules with zero internal imports) go into vendor; the remaining 23 lazy-loaded grammars get no assignment and each keeps its own on-demand chunk.
+- `index.html` is wired up automatically by vite: index loads via `<script>` and vendor via `<link rel="modulepreload">`, so the two chunks fetch in parallel with no waterfall.
+
+**Directory layout** (`chunkFileNames` + `assetFileNames`):
+
+- The `assets/` root keeps only the index and vendor js (with their adjacent sourcemaps) and css.
+- Grammar chunks go under `assets/langs/`. The criterion is whether a chunk's `moduleIds` include an `@shikijs/langs` member, not the facade: the shared chunks of embedded grammars (php/ruby/mdx embed html+javascript, which rollup splits out for sharing) **have no facade**, so a facade criterion would miss them; index and vendor are excluded by name, because vendor legitimately carries the three boot grammars.
+- Fonts go under `assets/fonts/` (`FONT_EXTENSIONS`: woff2/woff/ttf; today all of them are KaTeX faces referenced by vendor.css — katex.min.css is imported by an index-side component, but CSS modules go through manualChunks like any module and follow `katex` into vendor.css; the browser fetches only woff2, on demand and only when a formula renders).
+- Sourcemaps need no arrangement: rollup writes each `.map` next to its js and references it by bare relative filename, so when a chunk moves directories its map follows automatically.
+
+All cross-directory references (index's dynamic imports into `langs/`, same-directory relative references among grammar chunks, vendor.css's relative references into `fonts/`) are emitted by the bundler, so the runtime needs zero accompanying changes; the host-side webserver serves the nested paths verbatim under its static prefix.
+
+## Alternatives considered
+
+- **Serving react and the other vendors from a CDN**: dsh web targets local/intranet hosts (often without internet access), so a CDN is simply unavailable; react is the platform seed external of every plugin bundle (the shell is its sole supplier), and switching to the CDN global-variable form would touch three places — the platform manifest, the seed, and the module table; the caching benefit is already delivered by the vendor split.
+- **An inverse catch-all rule (everything in node_modules except the react family goes to vendor)**: membership cannot be read off the configuration, and small pieces like anser/clsx get misassigned to vendor; superseded by the positive exact-package-name list.
+- **Regex family matching**: hard to read; exact package names plus rollup's automatic coloring of transitive dependencies make pattern matching unnecessary.
+- **Identifying grammar chunks by facadeModuleId**: the facade-less shared chunks of embedded grammars would go undetected and fall back to the root directory; the `moduleIds` membership criterion covers both shapes.
+- **Sheltering a react-edged rendering facade in vendor** (the historical react-markdown was one): rollup's shared-module folding would drag the single react copy into vendor, breaking the "react belongs to index" boundary; the constraint is codified as the list's boundary invariant.
+- **Lazy-loading KaTeX wholesale, or turning the boot TypeScript grammar lazy**: either would change first-frame rendering behavior (the fallback for formulas / the first code block); that trade-off is independent of the dist layout and is decided separately.
+
+## Verification
+
+The audit tool ships with the repository: `node scripts/attribute-chunk-bytes.mjs <chunk.js>` (zero-dependency sourcemap VLQ byte attribution, aggregated by npm package / workspace directory). It verifies that vendor contains no workspace bytes, that the react family (including react/jsx-runtime) sits entirely in index, and that the npm side of index retains only the react family plus anser/clsx; the lazy grammar chunk count matches the `LAZY_GRAMMARS` table one to one; the browser keyless replay case is verbatim-identical to the pre-change baseline (apart from environment-specific local reds), so the two-chunk shell loads and renders with no regression.
+
+## Consequences
+
+- A shell code change rehashes only index (about one third of the dist output); vendor (about two thirds) stays cache-stable across shell releases and is invalidated only by dependency upgrades.
+- `dist/assets/` is navigable: two js/css pairs at the root, on-demand grammars in `langs/`, fonts in `fonts/`.
+- Maintenance cost: when workspace code adds a direct import of a rendering family's facade package, `VENDOR_PACKAGES` must be updated alongside (an omission merely dilutes index, nothing breaks); when the boot grammar set grows in highlight.ts without `BOOT_GRAMMAR_FILES` following, that grammar silently lands in index, visible only to a dist audit.
+- The webserver's static surface has no compression yet, so the gzip size win is still on the table; transport-layer compression is a separate, independent decision.

.agents/notes/implemented/architecture/2026-08-06-web-shell-dist-chunk-layout.zh.md

@@ -0,0 +1,50 @@
+# Agent Note: Web 壳产物的 chunk 切分与目录布局
+
+Status: implemented
+
+[English](2026-08-06-web-shell-dist-chunk-layout.md) | 中文
+
+## Problem
+
+apps/web 的壳此前打成单一约 1.2 MB（minified）的 index chunk，其中约八成是 vendor 字节——KaTeX、boot 语法与 shiki 引擎、react-dom、markdown 管线——与全部 workspace 壳代码（约五分之一）熔在一起。任何一行壳代码改动都让整个 chunk 换哈希，回头客户端全量重新下载；`dist/assets/` 是 100 多个文件的单层平铺（主 chunk、23 个懒加载语法 chunk、59 个 KaTeX 字体面、sourcemap 混居），无从导航。
+
+## Decision
+
+`apps/web/vite.config.ts` 以 `manualChunks` 把壳切成两个初始 chunk，并以输出命名函数归类目录；整套配置零正则——精确包名 Set、文件名清单、扩展名清单。
+
+**成员归属**（`VENDOR_PACKAGES`，按精确 npm 包名）：
+
+- `vendor` = 三个重渲染家族：math（katex）、highlight（shiki）、markdown（micromark/mdast 解析管线——其上的增量 React 渲染器是 workspace 代码，不在此列）。成员以 `VENDOR_PACKAGES` 为活口径，清单 = workspace 代码**直接 import** 的包：其余私有传递依赖（oniguruma 系、@shikijs/core、字符表等数十个）只被清单成员引用，rollup 的 chunk 着色自动将其并入 vendor；与 index 侧共享的依赖回落 index，只稀释几 KB，不构成正确性问题。
+- **vendor 全员必须 react-free（边界不变量）**：rollup 会把入口与 manual chunk 共享的模块并入 manual chunk——清单里出现任何 import react/jsx-runtime 的包，唯一一份 react 副本就会被拽进 vendor、脱离 index。markdown/math 的 React 渲染侧是 workspace 代码天然住 index，react 族因此全部钉在 index。
+- `index`（默认 chunk）= react 族（react、react-dom、scheduler、use-sync-external-store）、vendored cordis、全部 workspace 代码及未列入的小件（anser、clsx）。
+- `@shikijs/langs` 特判：boot 语法（`BOOT_GRAMMAR_FILES`：typescript、shellscript、json——highlight.ts 静态 import 的三件，均为零内部 import 的自含数据模块）进 vendor；其余 23 个懒加载语法不做指派，各自保持按需 chunk。
+- `index.html` 由 vite 自动接线：index 走 `<script>`、vendor 走 `<link rel="modulepreload">`，两 chunk 并行拉取，无瀑布。
+
+**目录布局**（`chunkFileNames` + `assetFileNames`）：
+
+- `assets/` 根只留 index 与 vendor 的 js（含随行 sourcemap）与 css。
+- 语法 chunk 归 `assets/langs/`。判据是 chunk 的 `moduleIds` 含 `@shikijs/langs` 成员，而非 facade：内嵌语法共享 chunk（php/ruby/mdx 内嵌 html+javascript，被 rollup 拆出共享）**没有 facade**，facade 判据会漏；index/vendor 按名排除，因 vendor 合法携带 boot 三语法。
+- 字体归 `assets/fonts/`（`FONT_EXTENSIONS`：woff2/woff/ttf；今日全部为 vendor.css 引用的 KaTeX 字面——katex.min.css 虽由 index 侧组件 import，css 模块同样经 manualChunks 归属、随 `katex` 落入 vendor.css；浏览器按需只拉 woff2，且仅在公式渲染时）。
+- sourcemap 无需安排：rollup 把 `.map` 写在各自 js 旁并以裸相对文件名引用，chunk 挪目录 map 自动跟随。
+
+跨目录引用（index 的动态 import 指向 `langs/`、语法 chunk 间同目录相对引用、vendor.css 相对引用 `fonts/`）均由构建器生成，运行时零配套改动；host 侧 webserver 按静态前缀原样服务嵌套路径。
+
+## Alternatives considered
+
+- **react 等 vendor 走 CDN**：dsh web 面向本机/内网主机（常无外网），CDN 直接不可用；react 是全部插件 bundle 的 platform seed external（壳是唯一供给方），改 CDN 全局变量形态需牵动 platform 清单/seed/模块表三处；缓存收益由 vendor 切分即可取得。
+- **反向兜底规则（node_modules 除 react 族全归 vendor）**：成员从配置上读不出来，且把 anser/clsx 类小件错归 vendor；被正向精确包名清单取代。
+- **正则家族匹配**：可读性差；精确包名 + rollup 对传递依赖的自动着色使模式匹配没有必要。
+- **以 facadeModuleId 识别语法 chunk**：无 facade 的内嵌语法共享 chunk 会漏检落回根目录；`moduleIds` 成员判据覆盖两种形态。
+- **在 vendor 里收留带 react 边的渲染门面**（历史上的 react-markdown 属此类）：会经 rollup 的共享模块归并把唯一 react 副本拽进 vendor，破坏「react 归 index」的边界；该约束已成文为清单的边界不变量。
+- **KaTeX 整体懒加载、boot TypeScript 语法转懒**：会改变首帧渲染行为（公式/首个代码块的回退），是独立于产物布局的取舍，另行决策。
+
+## Verification
+
+审计工具随库：`node scripts/attribute-chunk-bytes.mjs <chunk.js>`（零依赖 sourcemap VLQ 字节归属，按 npm 包/workspace 目录聚合）。以其复核：vendor 不含任何 workspace 字节、react 族（含 react/jsx-runtime）全量位于 index、index 的 npm 侧仅剩 react 族与 anser/clsx；懒语法 chunk 数量与 `LAZY_GRAMMARS` 表一一对应；浏览器 keyless replay 用例与改动前基线逐字一致（本机环境性红除外），两 chunk 壳装载渲染无回归。
+
+## Consequences
+
+- 壳代码改动只重哈希 index（约为产物三分之一）；vendor（约三分之二）跨壳版本缓存稳定，仅依赖升级时失效。
+- `dist/assets/` 可导航：根两对 js/css，`langs/` 按需语法，`fonts/` 字体。
+- 维护成本：workspace 代码新增对某渲染家族门面包的直接 import 时需同步 `VENDOR_PACKAGES`（漏列仅稀释 index，不致坏）；在 highlight.ts 扩 boot 语法集而未同步 `BOOT_GRAMMAR_FILES` 时，该语法静默落入 index，仅产物审计可见。
+- webserver 静态面尚无压缩，gzip 体量是潜在值；传输层压缩是另一项独立决策。

.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.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 .agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md
-2026-07-29-sticky-composer-conversation-scroll.md: 69d46894a53b0113f3e4f0fe871bbf3f9697969b
-2026-07-29-sticky-composer-conversation-scroll.zh.md: c0d5a0640468207282316ecd2fa1f209708df7b5
+2026-07-29-sticky-composer-conversation-scroll.md: d3fed7a9d0b1f39f9551fbd85e0f83515b1a2690
+2026-07-29-sticky-composer-conversation-scroll.zh.md: 2beee34d3bb68832d14b7607b43aa11e1425d53d

.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.md

@@ -10,7 +10,7 @@ The active conversation column split scrolling: the chat (and trajectory) view o
 
 ## Decision
 
-While a session exists, `ConversationRoot` always supplies a `wrapActiveBody` owner callback that wraps the view ring in a `data-conversation-scroll` body and places a `data-composer-seat` around the whole `'conversation.composer'` chain output (fallback + elected overlay siblings from `overlay: true`). Active CSS sticks that seat with `position: sticky; bottom: 0` so Question/Approval takeovers stay visible when the user is not pinned to the floor; hero CSS centers the fallback stack inside the scroll body. `ConversationSession` keeps a chrome-hidden header + body shell while blank so that tree seat does not change on the first send. The session header remains `flex: none` column chrome above the scrollport when visible. ChatView and Trajectory/Waterfall keep a local scroller only when mounted outside that host (unit tests); under the host they set `overflow: visible` and resolve bottom-follow / prepend anchoring through `closest('[data-conversation-scroll]')`.
+`ConversationRoot` always owns one `data-conversation-scroll` body, with the strict `conversation.session` view outlet before a `data-composer-seat` around the whole `'conversation.composer'` chain output (fallback + elected overlay siblings from `overlay: true`). The separate strict `conversation.session.header` outlet remains `flex: none` column chrome above that scrollport and hides while the Session is blank. This fixed parent tree keeps the scroll body and composer seat mounted from no session through the blank Hero and active conversation. Active CSS sticks that seat with `position: sticky; bottom: 0` so Question/Approval takeovers stay visible when the user is not pinned to the floor; Hero CSS centers the fallback stack inside the scroll body. ChatView and Trajectory/Waterfall keep a local scroller only when mounted outside that host (unit tests); under the host they set `overflow: visible` and resolve bottom-follow / prepend anchoring through `closest('[data-conversation-scroll]')`.
 
 Session stats live on `'conversation.composer.dock'` (above `'conversation.input.dock'`). The InputBar textarea, when inside the host, chains `wheel` with `{ passive: false }`: while the capped textarea can still scroll in that direction it keeps the native gesture; only at its own edge does it `preventDefault` and apply `deltaY` to the host.
 
@@ -22,7 +22,7 @@ Chat history prepend follows reader intent through stable rendered node/call ide
 
 **Fixed flex-none composer below the scrollport with wheel forwarding.** Rejected: the product requires the composer to stick inside the transcript scrollport so the footer is part of that scroll hit-testing surface, not a sibling that only forwards deltas.
 
-**Portal the composer into ChatView's scroller.** Rejected: the composer is shared across view tabs; the wrap target is the Session body owned by the resident shell.
+**Portal the composer into ChatView's scroller.** Rejected: the composer is shared across view tabs; its target is the root-owned scrollport in the resident shell.
 
 **Keep StatsLine inside ChatView below the message column.** Rejected: outside the sticky composer it would scroll away while the input stayed pinned.
 
@@ -30,4 +30,4 @@ Chat history prepend follows reader intent through stable rendered node/call ide
 
 ## Consequences
 
-Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Concurrent history, streaming, tool expansion, and composer reflow preserve wheel/trackpad scroll decisions, including Chromium's compositor-first delivery and stream-finalization clamp/regrow. Other browser scroll inputs do not change follow ownership under this narrow provenance rule. Hero → active keeps the same textarea DOM node (assembled slash-flow snapshot) and the InputHub draft.
+Wheel over the footer scrolls the transcript; the visible layout is a fixed header, scrolling transcript, and sticky bottom composer. Stats appear on every active view tab. Nested view scrollers under the host are suppressed so sticky Turn headers in Trajectory stick to the column host. Concurrent history, streaming, tool expansion, and composer reflow preserve wheel/trackpad scroll decisions, including Chromium's compositor-first delivery and stream-finalization clamp/regrow. Other browser scroll inputs do not change follow ownership under this narrow provenance rule. No session → blank Hero and Hero → active both keep the same textarea DOM node and InputHub draft.

.agents/notes/implemented/bug-fix/2026-07-29-sticky-composer-conversation-scroll.zh.md

@@ -10,7 +10,7 @@ Status: implemented
 
 ## Decision
 
-只要存在会话，`ConversationRoot` 就会始终提供 `wrapActiveBody` owner 回调，将视图环包进 `data-conversation-scroll` 主体，并用 `data-composer-seat` 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；hero CSS 在滚动主体内居中 fallback 栈。`ConversationSession` 在 blank 时保留隐藏 chrome 的 header + body 壳，使首次发送时树座位不变。可见时会话标题栏仍是滚动容器之上的 `flex: none` 列 chrome。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
+`ConversationRoot` 始终拥有同一个 `data-conversation-scroll` 主体，其中严格 `conversation.session` view outlet 位于 `data-composer-seat` 之前；该 seat 包住整条 `'conversation.composer'` chain 输出（`overlay: true` 下的 fallback 与选举出的 overlay 兄弟节点）。独立的严格 `conversation.session.header` outlet 作为 `flex: none` 列 chrome 位于滚动容器上方，并在 Session 仍为 blank 时隐藏。固定的父级树让滚动主体与 composer seat 从无 session、blank Hero 到活跃对话始终保持挂载。活跃阶段 CSS 以 `position: sticky; bottom: 0` 钉住该 seat，使用户未贴底时 Question／Approval 接管仍可见；Hero CSS 在滚动主体内居中 fallback 栈。ChatView 与 Trajectory/Waterfall 仅在宿主之外挂载时（单元测试）保留本地 scroller；位于宿主下时设为 `overflow: visible`，并通过 `closest('[data-conversation-scroll]')` 解析贴底跟随与前置锚定。
 
 会话统计挂在 `'conversation.composer.dock'`（位于 `'conversation.input.dock'` 之上）。InputBar 的 textarea 在宿主内以 `{ passive: false }` 链式处理 `wheel`：在限高 textarea 仍能沿该方向滚动时保留原生手势；仅在自身边缘才 `preventDefault` 并将 `deltaY` 施加到宿主。
 
@@ -22,7 +22,7 @@ Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图
 
 **滚动容器下方 flex-none 固定编辑器并转发滚轮。** 否决：产品要求编辑器 sticky 在 transcript 滚动容器内，使页脚成为该滚动命中面的一部分，而不是仅转发增量的兄弟节点。
 
-**把编辑器 portal 进 ChatView 的 scroller。** 否决：编辑器跨视图标签共享；包装目标是常驻壳拥有的 Session 主体。
+**把编辑器 portal 进 ChatView 的 scroller。** 否决：编辑器跨视图标签共享；其目标是常驻壳中由 root 持有的滚动容器。
 
 **把 StatsLine 留在 ChatView 消息列下方。** 否决：落在 sticky 编辑器之外会随内容滚走，而输入区仍钉在底部。
 
@@ -30,4 +30,4 @@ Chat 历史前插通过稳定的已渲染 node／call 身份跟随读者意图
 
 ## Consequences
 
-在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留滚轮／触控板的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段滚动位置受钳制后滚动容器重新增长的情况。在这条窄范围的输入来源规则下，其他浏览器滚动输入不会改变贴底跟随所有权。hero → active 保持同一 textarea DOM 节点（assembled slash-flow 快照）以及 InputHub 草稿。
+在页脚上滚轮会滚动 transcript；可见布局是固定标题栏、可滚动 transcript 与 sticky 底部编辑器。统计出现在每一个活跃视图标签上。宿主下的嵌套视图 scroller 被抑制，因而 Trajectory 的 sticky Turn 标题贴在列宿主上。并发历史加载、流式输出、工具展开与编辑器重排会保留滚轮／触控板的滚动决定，包括 Chromium 先推进合成器几何状态再交付事件，以及流收尾阶段滚动位置受钳制后滚动容器重新增长的情况。在这条窄范围的输入来源规则下，其他浏览器滚动输入不会改变贴底跟随所有权。无 session → blank Hero 与 Hero → active 都保持同一 textarea DOM 节点以及 InputHub 草稿。

.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.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 .agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md
-2026-07-31-hero-visible-while-blank-session-opens.md: b39963beffa403ef6fa44735aa88395a99139751
-2026-07-31-hero-visible-while-blank-session-opens.zh.md: b451d7c00ec7eb8d736134e738d72e5e07fd1b04
+2026-07-31-hero-visible-while-blank-session-opens.md: 6afa5d0ee2b695d6805d20f54e82073db8028df7
+2026-07-31-hero-visible-while-blank-session-opens.zh.md: f21e549b5811d81094374b1363186a1d18fbadaf

.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.md

@@ -24,12 +24,10 @@ The summary flag and the snapshot's own `blank` are distinct sources: the snapsh
 
 ## Deferred
 
-The no-session→session tree relocation in `ConversationRoot` (the hero/composer subtree moves into the `conversation.session` outlet) still rebuilds the composer DOM on the same transition; removing it means moving `conversation.session` to `session-maybe` scope, a slot-contract change that needs its own proposal.
-
 Object-layer reference churn found while diagnosing this — no-op projections minting fresh snapshots, the create path projecting twice, `select()` using `notifyNow` from async continuations — is real but independent of the visible flash.
 
 ## Consequences
 
 Startup auto-selection renders the hero immediately and keeps the composer seat and header visible through the history round-trip, so launching into a recent workspace no longer looks like a page reload. Sessions whose summary does not prove them blank keep the previous settling behavior, so the guard still covers the case it was written for. Skeleton tests pin all three summary shapes: a row reporting `blank: false` settles, an absent row settles, and a summary-proven blank session opening under `loading` renders hero chrome with a live textarea.
 
-The assembled coverage is `apps/web/tests/startup-auto-selection.e2e.ts` (keyless web browser lane): it registers a workspace, holds the `session.history` response open at the browser's network boundary, and asserts the visible frame while the auto-selected open is in flight — hero phase, hero title, painted composer — plus a recorded phase timeline of exactly `['hero']` for the whole load. Holding the round-trip is what makes it a regression test rather than a race: against a loopback host the open settles too fast to sample, and with the exemption reverted the held window is precisely when the root reports `settling`.
+The assembled coverage is `apps/web/tests/startup-auto-selection.e2e.ts` (keyless web browser lane). Its first Workspace connection asserts that the Hero root, Workspace chip, scroll body, composer seat, and textarea remain the same DOM nodes when the blank Session appears. It then holds the `session.history` response open at the browser's network boundary and asserts the visible frame while the auto-selected open is in flight — hero phase, hero title, painted composer — plus a recorded phase timeline of exactly `['hero']` for the whole load. Holding the round-trip is what makes the second case a regression test rather than a race: against a loopback host the open settles too fast to sample, and with the exemption reverted the held window is precisely when the root reports `settling`.

.agents/notes/implemented/bug-fix/2026-07-31-hero-visible-while-blank-session-opens.zh.md

@@ -24,12 +24,10 @@ Status: implemented
 
 ## 推迟事项
 
-`ConversationRoot` 中"无会话→有会话"的树位置迁移（hero/composer 子树移入 `conversation.session` 出口）仍会在同一次转换中重建 composer 的 DOM；消除它意味着把 `conversation.session` 移到 `session-maybe` 作用域，这是一次插槽契约变更，需要单独立项。
-
 诊断期间发现的对象层引用抖动——空操作投影铸造出新的快照、创建路径重复投影一次、`select()` 在异步续体中使用 `notifyNow`——确实存在，但与这次可见闪烁相互独立。
 
 ## 影响
 
 启动自动选择会立即渲染 hero，并在整个历史往返期间保持 composer 座位与 header 可见，因此启动进入最近工作区不再像页面重载。摘要未证明为空白的会话保持原有的 settling 行为，这道防护仍覆盖它当初针对的场景。骨架测试固定了摘要的三种形态：报告 `blank: false` 的行进入 settling；根本没有该行同样进入 settling；摘要已证明为空白的会话在 `loading` 期间渲染 hero 外壳与可用的文本框。
 
-组装级覆盖是 `apps/web/tests/startup-auto-selection.e2e.ts`（无密钥的 Web 浏览器泳道）：它注册一个工作区，在浏览器网络边界上扣住 `session.history` 的响应，并在自动选择的打开仍在飞行途中断言可见画面——hero 阶段、hero 标题、已绘制的 composer——外加整次加载记录到的阶段时间线恰好为 `['hero']`。扣住这次往返正是它成为回归测试而非竞态的原因：对着回环主机，打开会快到无从采样；而一旦回退这条豁免，被扣住的这段窗口恰恰就是根节点报告 `settling` 的时刻。
+组装级覆盖是 `apps/web/tests/startup-auto-selection.e2e.ts`（无密钥的 Web 浏览器泳道）。首次连接 Workspace 时，它断言 blank Session 出现前后 Hero root、Workspace chip、滚动主体、composer seat 与 textarea 都是同一 DOM 节点。随后它在浏览器网络边界上扣住 `session.history` 的响应，并在自动选择的打开仍在飞行途中断言可见画面——hero 阶段、hero 标题、已绘制的 composer——外加整次加载记录到的阶段时间线恰好为 `['hero']`。扣住这次往返正是第二个用例成为回归测试而非竞态的原因：对着回环主机，打开会快到无从采样；而一旦回退这条豁免，被扣住的这段窗口恰恰就是根节点报告 `settling` 的时刻。

.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.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 .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md
+2026-08-06-token-surface-unpriced-replace-compatibility.md: 77b778fba695f560eb68af6da2f416e61ccff181
+2026-08-06-token-surface-unpriced-replace-compatibility.zh.md: dd4c5883c4c6d37809c2f8100f266655d8ba600c

.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.md

@@ -0,0 +1,35 @@
+# Agent Note: unpriced surface replacements fold neutrally
+
+Status: implemented
+
+English | [中文](2026-08-06-token-surface-unpriced-replace-compatibility.zh.md)
+
+## Problem
+
+The `contextPressure` and `contextBreakdown` projections keep a running surface-token total plus at most one pending shadow-price claim, so their persisted checkpoints stay O(1) over a session's life. Current replace producers append a `compact/summary` or `compact/prune` metering event immediately before the replacement; its `shadowedTokenCount` prices the exact replaced range, and `foldSurfaceProjection` turns that into the signed delta.
+
+Sessions recorded before the shadow-price protocol log replacements with no adjacent metering event. The O(1) state cannot reconstruct the replaced range's price, and the fold treated every unpriced replacement as a contract violation and threw — so replaying such a session died at its first replacement (`token surface: replace at seq … has no adjacent shadow price`), leaving the session permanently unopenable.
+
+## Decision
+
+A replace that arrives with no armed claim folds price-neutrally: `foldSurfaceProjection` returns `deltaTokens: 0`, pricing the replaced range as if it had cost exactly what its replacement costs, and replay continues. A claim expired by an intervening event reaches the same neutral path, since the fold cannot distinguish it from a log that never metered.
+
+An armed claim naming a **different** range still throws. There the metering event was adjacent, so the producer wrote contradictory adjacent events — a live shadow-price contract violation, not historical data, and it must fail loud rather than let the total drift silently.
+
+Both projections share the one fold, so neither gains state fields nor bumps its `stateVersion`. `surface-fold.ts` and `ctx.tokenMeter.measure()` are unaffected: they hold the per-node priced surface and never needed the claim protocol.
+
+## Alternatives considered
+
+**Keep throwing.** Preserves the strict producer contract, but every pre-protocol session stays permanently unreplayable, and the projections exist to serve replay.
+
+**Persist the full priced surface in the projection state.** Could price any replaced range exactly, but grows the checkpoint by one node per model-visible message without bound — defeating the O(1) constraint the shadow-price protocol exists to preserve (see [the context-meter note](2026-08-05-context-meter-blind-to-compaction.md)).
+
+## Consequences
+
+An unpriced replacement holds the total still instead of shrinking it, so the compacted-away span stays counted: `contextBreakdown.messageTokens` retains the overcount, and `contextPressure.projectedTokens` overestimates occupancy only until the next usage sample re-anchors it, because that figure tracks movement since the sample rather than the absolute level. The error direction is safe — overestimating occupancy at worst invites an earlier compaction.
+
+The loud failure survives where it still means something: a range-mismatched adjacent claim is a current producer bug and still throws.
+
+## Testing
+
+`packages/llm/token-meter/tests/context-breakdown-projection.spec.ts` pins the neutral fold for the no-claim and expired-claim replacements, the throw for a mismatched claim, and the exact pricing for a matched one. `packages/llm/token-meter/tests/token-usage-projection.spec.ts` pins `contextPressure` holding still across an unpriced replacement.

.agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md

@@ -0,0 +1,35 @@
+# Agent Note: 未计价的表层替换以中性方式折叠
+
+Status: implemented
+
+[English](2026-08-06-token-surface-unpriced-replace-compatibility.md) | 中文
+
+## 问题
+
+`contextPressure` 与 `contextBreakdown` 两个投影只维护一份滚动累计的表层 token 总量，外加至多一条待结算的影子价格（shadow price）声明，因此其持久化检查点在会话整个生命周期内保持 O(1)。当前的替换生产方会紧贴在替换之前追加一条 `compact/summary` 或 `compact/prune` 计量事件；其 `shadowedTokenCount` 对被替换区间精确计价，`foldSurfaceProjection` 再把它换算成有符号增量。
+
+影子价格协议引入之前录制的会话，其日志中的替换没有相邻的计量事件。O(1) 状态无法重建被替换区间的价格，而折叠此前把每一次未计价替换都当作契约违规并抛出异常，于是回放这类会话会在第一处替换就中断（`token surface: replace at seq … has no adjacent shadow price`），会话从此永远无法打开。
+
+## 决策
+
+到达时没有已就位声明的替换以价格中性的方式折叠：`foldSurfaceProjection` 返回 `deltaTokens: 0`，相当于把被替换区间计价为恰好等于其替换内容的成本，回放随即继续。因中间插入的事件而过期的声明也走同一条中性路径，因为折叠无法把它与从未计量过的日志区分开。
+
+已就位但指向**另一个**区间的声明仍会抛出异常。此时计量事件确实相邻，说明生产方写入了互相矛盾的相邻事件：这是现行影子价格契约的违规，不是历史数据，必须响亮失败，而不能任由总量悄然漂移。
+
+两个投影共用同一个折叠，因此二者都不新增状态字段，也不提升 `stateVersion`。`surface-fold.ts` 与 `ctx.tokenMeter.measure()` 不受影响：它们持有逐节点的已计价表层，本来就不需要声明协议。
+
+## 备选方案
+
+**维持抛出异常。**保住了严格的生产方契约，但协议之前的每个会话都将永远无法回放，而投影本就是为服务回放而存在的。
+
+**在投影状态中持久化完整的已计价表层。**可以对任意被替换区间精确计价，但检查点会随每条模型可见消息各增加一个节点、无上限地增长，恰恰破坏了影子价格协议所要守住的 O(1) 约束（见[上下文仪表的 Agent Note](2026-08-05-context-meter-blind-to-compaction.md)）。
+
+## 影响
+
+未计价的替换让总量保持不动而不是缩小，因此被压缩（compaction）掉的区段仍被计入：`contextBreakdown.messageTokens` 保留这部分多计的量；`contextPressure.projectedTokens` 会高估占用率，但只持续到下一个用量样本重新锚定为止，因为该数字追踪的是自样本以来的增减，而非绝对水平。误差方向是安全的：高估占用率最坏不过是招致一次更早的压缩。
+
+响亮失败保留在它仍有意义的地方：区间不匹配的相邻声明是现行生产方的缺陷，仍会抛出异常。
+
+## 测试
+
+`packages/llm/token-meter/tests/context-breakdown-projection.spec.ts` 钉住了无声明与声明过期两种替换的中性折叠、声明区间不匹配时的抛出异常，以及声明匹配时的精确计价。`packages/llm/token-meter/tests/token-usage-projection.spec.ts` 钉住了 `contextPressure` 在一次未计价替换前后保持不动。

.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.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 .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
-2026-06-18-compaction-capability-seam.md: 27dbde9f2349681cf47c4d25b16399b26ed9e1ca
-2026-06-18-compaction-capability-seam.zh.md: 1fe9ece2861bd6d75633a866a4a11eaadbf7ef26
+2026-06-18-compaction-capability-seam.md: 26e6e2468c7bea661d85c8fb994adf8b109105ee
+2026-06-18-compaction-capability-seam.zh.md: 8f9cd1f6bc31e648a5b923e816cad75ebc1a0bd8

.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md

@@ -119,7 +119,7 @@ The lifecycle boundary makes crash state unambiguous:
 ## Consequences
 
 - **Packages**: `packages/compact/compact` supplies the interface, `compact-basic` supplies the backend, `compact-tool-result-prune` supplies optional deterministic rewriting, and `command-compact` supplies human `/compact`. `packages/llm/token-meter` owns replay-aware measurement independently.
-- **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. Pre-step receives the claimed batch and `PreStepContext`, with no compaction-only prompt/prefix payload.
+- **Automatic seams**: `agent/pre-step` (`@mode waterfall`) handles pressure before request derivation and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. The pre-step payload carries the claimed batch, turn, step, and signal (see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)), with no compaction-only prompt/prefix payload.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `COMPACT_CHECKPOINT_SOURCE`, `isCompactCheckpointSource(source)`, `toolPairingBalancedBefore(session, seq)`, and `toolPairingBalancedAfter(session, seq)`. The marker identifies replacement summaries across backend implementations. The cached surface-edge checks prevent `compactRegion` and `compactIfNeeded` from splitting a tool-call/result pair, validate current membership by seq, answer both edges from one per-cut balance sequence, and reject stale or missing seqs and orphan results.
 - **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call, while the compaction companion owns numeric-turn versus standalone-null bracket relations.

.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md

@@ -119,7 +119,7 @@ compact/end      → log-only. Releases the lock (carries `error` on a recoverab
 ## 后果
 
 - **包**：`packages/compact/compact` 提供接口，`compact-basic` 提供后端，`compact-tool-result-prune` 提供可选的确定性重写，`command-compact` 提供面向用户的 `/compact`。`packages/llm/token-meter` 独立拥有回放感知的测量。
-- **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 接收已领取批次与 `PreStepContext`，不携带压缩专属的提示词/前缀 payload。
+- **自动 seam**：`agent/pre-step`（`@mode waterfall`）在请求派生前处理压力，`agent/request-error`（`@mode waterfall`）处理失败步骤关闭后的最终请求失败。pre-step 的 payload 携带已领取批次、轮次、步骤与 signal（参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)），不携带压缩专属的提示词/前缀 payload。
 - **`SessionEventMap`** 通过可合并扩展的声明合并获得 `compact/start` / `compact/summary` / `compact/end`；`SurfaceEventType` **未被**触及。这些是会话事件，不是 cordis `Events`，因此事件分类门禁无需新增条目。
 - **`dsh-compact`** 拥有 `COMPACT_CHECKPOINT_SOURCE`、`isCompactCheckpointSource(source)`、`toolPairingBalancedBefore(session, seq)` 与 `toolPairingBalancedAfter(session, seq)`。该标记用于跨后端实现识别替换摘要。带缓存的 surface 边缘检查会防止 `compactRegion` 和 `compactIfNeeded` 拆分工具调用/结果对，按 seq 校验当前成员关系，从每个切割点的一条平衡序列回答两侧边缘，并拒绝陈旧或缺失的 seq 与孤立结果。
 - **`dsh-session`** 通过唯一的 surface 管理器校验位置替换、完整溯源信息和仅内容的单节点 `tool/result` 重写。其不变式配套插件将新追加的工具结果视为执行，要求存在已打开的步骤与待处理调用，而压缩配套组件拥有数字轮次归属与独立 `null` 归属标记对之间的关系。

.agents/notes/implemented/feature/2026-06-30-interception-seams.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 .agents/notes/implemented/feature/2026-06-30-interception-seams.md
-2026-06-30-interception-seams.md: 629a1aed509bd9bce9a2da89ce84b17a1db8e6b6
-2026-06-30-interception-seams.zh.md: d6958c9d1e7a8af8fa06d859d1905719a19cd43d
+2026-06-30-interception-seams.md: c318e41cfb1d64230b6151f1febad85d75b1451d
+2026-06-30-interception-seams.zh.md: 1b274fae4bc7fde326dbb0eeec54d57f73987803

.agents/notes/implemented/feature/2026-06-30-interception-seams.md

@@ -15,8 +15,8 @@ The surface needs distinct contracts for per-prompt policy (CC's `UserPromptSubm
 The canonical surface separates transformable policy, around-dispatch control, and observe-only notification. Policy waterfalls return small seam-specific **typed Decision unions**; wrappers return normalized results; notifications receive immutable snapshots and cannot affect the outcome. The set covers the hook points in scope (`session-start`, `prompt-submit`, `pre-tool`, `post-tool`, `stop`-via-continuation) while leaving non-hook execution policy independently composable.
 
 **Agent events** (`dsh-agent`):
-- `agent/session-start(agent, source)` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`.
-- `agent/pre-step(agent, messages, context, next) → PreStepDecision` — waterfall, fired before every proposed step after the loop has atomically removed its exclusive inbox batch. `PreStepContext` carries that request's `turn`, `step`, and cancellation `signal`; `messages` is empty for a tool continuation with no intervening input. `enter` returns the complete message batch, including any current-request context a listener contributes; `reject` opens no step and leaves the claimed messages removed.
+- `agent/session-start({ agent, source })` — emit, once before turn 1, carrying a `SessionStartSource` (`startup` for a fresh/forked create, `resume` for a reloaded persisted session; `clear`/`compact` reserved). A pure notification — it CANNOT block startup (a deliberate gap: a bridge logs/injects, it does not gate startup). A listener seeds context via `agent.inject()`.
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` — waterfall, fired before every proposed step after the loop has atomically removed its exclusive inbox batch. The payload carries the request's `turn`, `step`, and cancellation `signal` (the retired `PreStepContext` fields live in the payload; see the [payload-object events decision](../architecture/2026-08-06-agent-event-payload-objects.md)); `messages` is empty for a tool continuation with no intervening input. `enter` returns the complete message batch, including any current-request context a listener contributes; `reject` opens no step and leaves the claimed messages removed.
 
 **`agent/turn-stopping`** is an awaited notification at the natural stop boundary. A listener that needs another step calls `agent.steer()` with explicitly sourced model-facing content; the loop then re-reads the outbox and either continues or closes the turn.
 

.agents/notes/implemented/feature/2026-06-30-interception-seams.zh.md

@@ -15,8 +15,8 @@ harness 需要一套钩子子系统：用户像 Claude Code（CC）和 Codex 那
 规范表面将可变换策略、环绕调度控制与仅观测通知分离。策略 waterfall（瀑布式事件）返回小型的、seam 专属的**类型化 Decision 联合类型**；包装层返回规范化结果；通知接收不可变快照，无法影响结果。覆盖的钩子点包括 `session-start`、`prompt-submit`、`pre-tool`、`post-tool`、通过 continuation 实现的 `stop`，同时将非钩子的执行策略留作独立可组合。
 
 **Agent 事件**（`dsh-agent`）：
-- `agent/session-start(agent, source)` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
-- `agent/pre-step(agent, messages, context, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。`PreStepContext` 携带该请求的 `turn`、`step` 与取消 `signal`；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
+- `agent/session-start({ agent, source })` ——emit，在第 1 轮次之前触发一次，携带 `SessionStartSource`（`startup` 表示全新/fork 创建，`resume` 表示重新加载的持久化会话；`clear`/`compact` 保留）。纯通知，不能阻塞启动（这是有意的空白：桥接可以记录/注入，但不管控启动）。监听器通过 `agent.inject()` 注入上下文。
+- `agent/pre-step({ agent, messages, turn, step, signal }, next) → PreStepDecision` ——waterfall，在每个拟议步骤之前、循环原子移除其独占 inbox 批次后触发。payload 携带该请求的 `turn`、`step` 与取消 `signal`（已退役的 `PreStepContext` 字段位于 payload 中；参见 [payload-object 事件决策](../architecture/2026-08-06-agent-event-payload-objects.md)）；没有中途输入的工具续步会收到空批次。`enter` 返回完整消息批次，其中包括监听器为当前请求贡献的上下文；`reject` 不打开步骤，并让已领取消息保持已删除。
 
 **`agent/turn-stopping`** 是自然停止边界上的一次 awaited 通知。需要再执行一步的监听器调用 `agent.steer()`，传入来源显式的 steering（中途引导）内容供模型使用；循环随后重新读取 outbox，继续执行或关闭轮次。
 

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.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 .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 1fa8cda2b34b58cc7a28b722872520b68a9b7009
-2026-07-20-dsh-cli-personal-config.zh.md: e70b8914cf005e0a2e54ba2b29d3b7def84b00db
+2026-07-20-dsh-cli-personal-config.md: 10f16a1cbabdd8cd383c59ad8e09787c02d0109a
+2026-07-20-dsh-cli-personal-config.zh.md: 22435efbec8ea661c546ffd0c1aa9bb0ff2ebbb2

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.md

@@ -10,6 +10,8 @@ A developer's own preferences — which provider and model the TUI uses, persona
 
 ## Decision
 
+The entry modes and the personal file's name and location below are superseded by the [profile plugin bundles decision](../architecture/2026-08-05-profile-plugin-bundles.md): `dsh` boots profiles, and the personal layer became the per-profile and home-level `cordis.patch.yml`. What survives unchanged is this note's substance — the Harness home as the machine-level layer's root, patch semantics over a shipped composition, and fail-loud parsing.
+
 Two coupled pieces, aligned with the `apps/` assembly tier proposed by the `dsh web` PR (#443):
 
 **The `dsh` CLI (`apps/cli`, npm name `@deepseek-ai/dsh`).** `apps/*` is the product-assembly tier over `packages/*` libraries. One bin dispatches the default interactive TUI, `-p`/`--prompt` headless turns, and the `web` surface. The TUI boots `examples/tui-agent/cordis.yml` (or `--config`) with the invoking directory as the workspace. The committed `bin/dsh` launcher resolves the checkout through its own real path and runs the app with tsx's ESM hook; the [source-launch decision](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md) owns that contract. `pnpm run demo:tui` runs the same entry.
@@ -46,4 +48,4 @@ The TUI and Web register the exact personal path through Cordis HMR after boot.
 
 ## Testing
 
-`packages/ui/app-boot/tests/personal-config.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` boots the real dsh bin with no overlay, a personal environment and UI patch, a config-only cached repository skill, and invalid personal YAML. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.
+`packages/ui/app-boot/tests/user-patches.spec.ts` pins parsing, startup application, exact-path add/failure/recovery/removal, last-good rollback, failure broadcast, and preservation of app-owned patches. `apps/cli/tests/built-bin.e2e.ts` boots the real dsh bin over a profile and exercises the live patch layer end to end. Test launchers isolate `$DSH_HOME`, so a developer's real overlay cannot leak into fixtures.

.agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md

@@ -10,6 +10,8 @@ Status: implemented
 
 ## Decision
 
+下文的各入口模式，以及个人文件的名称与位置，已被 [profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)取代：`dsh` 启动 profile，个人层变成逐 profile 与 home 级的 `cordis.patch.yml`。保留不变的是本笔记的实质：以 Harness home 作为机器级层的根目录、在随附组合之上使用 patch 语义，以及解析时的大声失败。
+
 两个耦合的部分，与 `dsh web` PR（#443）提出的 `apps/` 装配层对齐：
 
 **`dsh` CLI（`apps/cli`，npm 名 `@deepseek-ai/dsh`）。** `apps/*` 是位于 `packages/*` 库之上的产品组装层。一个 bin 负责分发默认交互式 TUI、`-p`/`--prompt` 无头轮次和 `web` 界面。TUI 以调用目录为 workspace，启动 `examples/tui-agent/cordis.yml`（或 `--config` 指定的配置）。已提交的 `bin/dsh` 启动器通过自身真实路径解析 checkout，并使用 tsx 的 ESM hook 运行应用；该契约由[源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)维护。`pnpm run demo:tui` 运行同一入口。
@@ -46,4 +48,4 @@ TUI 和 Web 启动后通过 Cordis HMR（热模块替换）注册确切的个人
 
 ## Testing
 
-`packages/ui/app-boot/tests/personal-config.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`examples/tui-agent/tests/tui-keyless-smoke.e2e.ts` 启动真实 dsh bin，覆盖无 overlay、个人环境与 UI patch、纯配置的缓存 repository skill，以及无效个人 YAML。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。
+`packages/ui/app-boot/tests/user-patches.spec.ts` 固定解析、启动时应用、确切路径的新增／失败／恢复／移除、最后可用状态回滚、失败广播以及应用自有 patch 的保留。`apps/cli/tests/built-bin.e2e.ts` 启动真实 dsh bin 并基于 profile 端到端验证实时 patch 层。测试启动器会隔离 `$DSH_HOME`，因此开发者的真实 overlay 不会泄漏进 fixture。

.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.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 .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
-2026-07-31-even-out-shipped-tool-rosters.md: 312e61d017abad1a6ac57f2ba491a715f8fd92d0
-2026-07-31-even-out-shipped-tool-rosters.zh.md: c77370c312004052bc4f8ee9545ed287a6d92554
+2026-07-31-even-out-shipped-tool-rosters.md: d12db993654d9f2b41a16a4663dc64aefe8e3a2f
+2026-07-31-even-out-shipped-tool-rosters.zh.md: 8381a457def1a909b300de52dc011e2437c7e9f3

.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md

@@ -12,7 +12,7 @@ The result was a user-visible difference nobody had decided: the same model, ask
 
 ## Decision
 
-The rows that are not surface-specific move into [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster: twenty-two tools on every host — the twenty shared rows plus `glob` and `grep`, which are fixed members because `dsh-tool-fs-search` spawns the [packaged ripgrep binary](../architecture/2026-08-01-packaged-ripgrep-search.md). `tool-session-query` joined and then left again — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) keeps the model-facing consumer opt-in — while the rest of this roster stands.
+The rows that are not surface-specific move into [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster: twenty-two tools on every host — the twenty shared rows plus `glob` and `grep`, which are fixed members because `dsh-tool-fs-search` spawns the [packaged ripgrep binary](../architecture/2026-08-01-packaged-ripgrep-search.md). `tool-session-query` joined and then left again — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) keeps the model-facing consumer opt-in — while the rest of this roster stands.
 
 Two rows stay surface-specific. `tmux-context` is TUI-only because a browser surface has no terminal multiplexer to describe. `session-reference` is TUI-only because it drives the shared session-query index from the launcher's process-local path, and the browser sidebar reconciles that index on its own first search.
 

.agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.zh.md

@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
+那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml),另有三行加入:`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
 
 有两行仍是 surface 专属。`tmux-context` 只在 TUI,因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI,因为它以 launcher 的进程本地路径驱动共享的 session-query 索引,而浏览器侧边栏会在自己的首次搜索里重建该索引。
 

.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.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 .agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.md
-2026-07-31-workspace-write-surface-default.md: a0b216122e301b5332ed761155d743dc78fa3bab
-2026-07-31-workspace-write-surface-default.zh.md: 4391daa32b142ea976e3b04833163936913c17bc
+2026-07-31-workspace-write-surface-default.md: e6a36ad4ee7179cabf958114681728c3ac7340b4
+2026-07-31-workspace-write-surface-default.zh.md: 5ced928b167892d9abe1f4423da72a0243590735

.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.md

@@ -10,7 +10,7 @@ The shipped terminal and browser surfaces exposed the same coding tools under di
 
 ## Decision
 
-[`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml) owns one sandbox and permission stack for every shipped TUI, Web, and browser-backed headless session: `dsh-sandbox-local`, `dsh-sandbox-policy`, `dsh-bash-sandbox`, `dsh-fs-sandbox`, `dsh-user-approval`, and `dsh-permission`. The composition fallback is the `workspace-write` preset, which bundles `workspace-write` file effects with the `ask` approval policy. `DSH_PERMISSION_MODE` remains an explicit process override; a stored `permission.defaultPreset` remains the user preference for later sessions and outranks the fallback through the Settings seam.
+[`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml) owns one sandbox and permission stack for every shipped TUI, Web, and browser-backed headless session: `dsh-sandbox-local`, `dsh-sandbox-policy`, `dsh-bash-sandbox`, `dsh-fs-sandbox`, `dsh-user-approval`, and `dsh-permission`. The composition fallback is the `workspace-write` preset, which bundles `workspace-write` file effects with the `ask` approval policy. `DSH_PERMISSION_MODE` remains an explicit process override; a stored `permission.defaultPreset` remains the user preference for later sessions and outranks the fallback through the Settings seam.
 
 A genuinely fresh session pins `permission/preset: workspace-write`, `sandbox/mode: workspace-write`, and `approval/policy: ask` before execution. Existing and resumed sessions retain their logged permission, and changing the General-settings default affects only sessions created afterward. The browser keeps its Access picker, answerable approval cards, and risk confirmation for Full access. The TUI gains the existing `/permission` command because the shared Permission service activates its command child there.
 

.agents/notes/implemented/feature/2026-07-31-workspace-write-surface-default.zh.md

@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-[`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml) 为所有已交付的 TUI、Web 以及由浏览器支撑的无头会话统一持有一套沙箱与权限栈：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 和 `dsh-permission`。组合回退值为 `workspace-write` preset，其中包含 `workspace-write` 文件效果模式与 `ask` 审批策略。`DSH_PERMISSION_MODE` 仍是显式的进程级覆盖；已存储的 `permission.defaultPreset` 仍是面向后续会话的用户偏好，并通过 Settings seam 优先于该回退值。
+[`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml) 为所有已交付的 TUI、Web 以及由浏览器支撑的无头会话统一持有一套沙箱与权限栈：`dsh-sandbox-local`、`dsh-sandbox-policy`、`dsh-bash-sandbox`、`dsh-fs-sandbox`、`dsh-user-approval` 和 `dsh-permission`。组合回退值为 `workspace-write` preset，其中包含 `workspace-write` 文件效果模式与 `ask` 审批策略。`DSH_PERMISSION_MODE` 仍是显式的进程级覆盖；已存储的 `permission.defaultPreset` 仍是面向后续会话的用户偏好，并通过 Settings seam 优先于该回退值。
 
 真正的新会话会在执行前固定 `permission/preset: workspace-write`、`sandbox/mode: workspace-write` 和 `approval/policy: ask`。现有会话和恢复的会话保留日志中记录的权限，更改「通用」设置中的默认值只影响之后创建的会话。浏览器保留 Access 选择器、可应答的审批卡片，以及选择 Full access 时的风险确认。共享 Permission 服务在 TUI 中激活其命令子件，因此 TUI 会获得现有的 `/permission` 命令。
 

.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.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 .agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.md
-2026-08-02-session-search-not-shipped-default.md: ba7299712c0ba3db5e807e928f6f5d98ac917187
-2026-08-02-session-search-not-shipped-default.zh.md: 1678ebfb5514003eabe0221e460c619bab1aa444
+2026-08-02-session-search-not-shipped-default.md: 65bd72fff76210b726e7562fb8e88e5f8802434a
+2026-08-02-session-search-not-shipped-default.zh.md: 5e42a2c2323904117f9322b5c4a53c43c6ed3f2a

.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.md

@@ -6,11 +6,11 @@ English | [中文](2026-08-02-session-search-not-shipped-default.zh.md)
 
 ## Problem
 
-The [shipped-roster decision](2026-07-31-even-out-shipped-tool-rosters.md) made `tool-session-query` a default row of the shared [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml), so the shipped TUI and Web surfaces put the five session-search tools (`session_search`, `session_event_search`, `session_trace`, `session_event_trace`, `session_event_read`) in front of the model. That contradicted the [model-facing session-query-tools decision](2026-07-24-model-facing-session-query-tools.md), whose opt-in stance the package README recorded as "shipped host compositions do not mount it by default". The default also shipped a prompt section teaching a prior-work search workflow that no user had asked for.
+The [shipped-roster decision](2026-07-31-even-out-shipped-tool-rosters.md) made `tool-session-query` a default row of the shared [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml), so the shipped TUI and Web surfaces put the five session-search tools (`session_search`, `session_event_search`, `session_trace`, `session_event_trace`, `session_event_read`) in front of the model. That contradicted the [model-facing session-query-tools decision](2026-07-24-model-facing-session-query-tools.md), whose opt-in stance the package README recorded as "shipped host compositions do not mount it by default". The default also shipped a prompt section teaching a prior-work search workflow that no user had asked for.
 
 ## Decision
 
-The shipped TUI, Web, and headless surfaces no longer mount `@deepseek-ai/dsh-tool-session-query`: the row is removed from the shared `base.cordis.yml`, the now-dangling `disabled` patch in the opt-in [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile goes with it, and the workspace dependency drops from `apps/cli/package.json`. The consumer stays opt-in exactly as the model-facing-session-query-tools note describes: the ACP example's [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) and its snapshot counterpart remain the mounted reference, and a custom composition can mount the package with the timeout and spill policies.
+The shipped TUI, Web, and headless surfaces no longer mount `@deepseek-ai/dsh-tool-session-query`: the row is removed from the shared `cordis.patch.yml`, the now-dangling `disabled` patch in the opt-in [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile goes with it, and the workspace dependency drops from `apps/cli/package.json`. The consumer stays opt-in exactly as the model-facing-session-query-tools note describes: the ACP example's [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) and its snapshot counterpart remain the mounted reference, and a custom composition can mount the package with the timeout and spill policies.
 
 The `ctx.sessionQuery` service itself stays mounted. `session-query-sqlite` remains a base row — the TUI's `session-reference` consumes it for `/resume` — and the Web overlay keeps patching it to an in-memory index for the browser content search. Only the model-facing consumer is removed.
 

.agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.zh.md

@@ -6,11 +6,11 @@ Status: implemented
 
 ## 问题
 
-[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`base.cordis.yml`](../../../../apps/cli/config/base.cordis.yml) 的默认行,于是交付的 TUI 与 Web surface 把这五个会话搜索工具(`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`)呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触,该决策持需显式启用的立场,包 README 将其记录为「shipped host compositions do not mount it by default」。这份默认还交付了一个提示词段,向模型讲授一套既往工作搜索工作流,而没有任何用户要求过。
+[交付清单决策](2026-07-31-even-out-shipped-tool-rosters.md)把 `tool-session-query` 设为共享 [`cordis.patch.yml`](../../../../packages/bundle/base/cordis.patch.yml) 的默认行,于是交付的 TUI 与 Web surface 把这五个会话搜索工具(`session_search`、`session_event_search`、`session_trace`、`session_event_trace`、`session_event_read`)呈现给了模型。这与[面向模型的会话查询工具决策](2026-07-24-model-facing-session-query-tools.md)相抵触,该决策持需显式启用的立场,包 README 将其记录为「shipped host compositions do not mount it by default」。这份默认还交付了一个提示词段,向模型讲授一套既往工作搜索工作流,而没有任何用户要求过。
 
 ## 决策
 
-交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`:该行从共享的 `base.cordis.yml` 移除,opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除,workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in,与面向模型的会话查询工具决策所述完全一致:ACP 示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考,自定义组合也可以连同超时与 spill 策略一起挂载该包。
+交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`:该行从共享的 `cordis.patch.yml` 移除,opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除,workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in,与面向模型的会话查询工具决策所述完全一致:ACP 示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考,自定义组合也可以连同超时与 spill 策略一起挂载该包。
 
 `ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行,TUI 的 `session-reference` 消费它来实现 `/resume`,Web overlay 也继续把它 patch 成内存索引,供浏览器内容搜索使用。被移除的只有面向模型的消费方。
 

.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.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 .agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md
+2026-08-04-web-slash-command-fuzzy-discovery.md: 8d7fe88f8d19a6edc7b51e63578c468df085c238
+2026-08-04-web-slash-command-fuzzy-discovery.zh.md: d3efdc23351a1b50853ee76fb731aee046004750

.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.md

@@ -0,0 +1,27 @@
+# Agent Note: Web slash-command fuzzy discovery
+
+Status: implemented
+
+English | [中文](2026-08-04-web-slash-command-fuzzy-discovery.zh.md)
+
+## Problem
+
+The web command menu required a command-name prefix, so discovery failed when a user remembered the significant letters but not their exact positions. Broadening menu matching could make discovery easier, but command execution must remain exact and deterministic: an approximate line must never execute a nearby command.
+
+## Decision
+
+The `/` command source fuzzy-matches the typed query against command names as a case-insensitive ordered subsequence. Exact prefixes form the highest ranking class. Within each class, the strongest alignment score rewards separator boundaries and adjacent characters while penalizing leading characters and gaps; equal scores retain the host-directory and client-contribution order. Position filtering still removes argument-taking commands from inline menus before ranking.
+
+The scorer uses dynamic programming in `O(query length × name length)` time and `O(name length)` memory per candidate. Candidate scoring stays client-side and examines names only; descriptions do not affect matching. Menu selection still dispatches the selected exact name, while space and Enter adjudication continue to require an exact command token.
+
+## Alternatives considered
+
+**Keep prefix-only matching.** Rejected because it preserves the recall failure that motivates the feature; `/cpt` cannot discover `/compact`.
+
+**Match unordered characters or descriptions.** Rejected because unordered matches are difficult to predict, while description matches can surface commands whose visible names do not explain why they ranked.
+
+**Use a general fuzzy-search dependency.** Rejected because this surface needs one constrained subsequence rule over a small command catalog; a configurable search index would add bundle weight and ranking behavior not used by the product.
+
+## Consequences
+
+Users can discover a command from remembered in-order letters, and ranking remains stable across identical catalogs. The score is deliberately heuristic: a separator-aligned match can outrank a match with a shorter raw span. Package tests pin each ranking factor and stable ties, while the assembled Web replay snapshot pins `/cpt` resolving to `/compact`. Exact execution semantics are unchanged.

.agents/notes/implemented/feature/2026-08-04-web-slash-command-fuzzy-discovery.zh.md

@@ -0,0 +1,27 @@
+# Agent Note: Web 斜杠命令模糊发现
+
+Status: implemented
+
+[English](2026-08-04-web-slash-command-fuzzy-discovery.md) | 中文
+
+## Problem
+
+Web 命令菜单要求按命令名前缀匹配，因此用户只记得关键字母却不记得其准确位置时，就无法发现命令。扩大菜单的匹配范围可使命令更易发现，但命令执行仍必须保持精确匹配和确定性：近似输入行绝不能执行相近命令。
+
+## Decision
+
+`/` 命令 source 将键入的查询作为不区分大小写的有序子序列，与命令名进行模糊匹配。精确前缀构成排名最高的一类匹配。在每类匹配中，对齐分数越高越优先：分隔符边界和相邻字符会提高分数，前导字符和间隔会降低分数；分数相同则保持 host 目录和 client contribution 的顺序。位置过滤仍会在排名前从行内菜单中移除接收参数的命令。
+
+评分器对每个候选项使用动态规划，时间复杂度为 `O(query length × name length)`，空间复杂度为 `O(name length)`。候选项评分只在客户端进行且只检查命令名；命令描述不影响匹配。菜单选择仍派发所选的精确名称，而 space 与 Enter 裁决继续要求命令 token 精确匹配。
+
+## Alternatives considered
+
+**保留仅前缀匹配。** 否决，因为本功能要解决的用户无法准确回忆前缀的问题依然存在：`/cpt` 无法发现 `/compact`。
+
+**匹配无序字符或描述。** 否决，因为无序匹配难以预测，而描述匹配可能展示命令，但命令的可见名称无法解释其排名。
+
+**使用通用模糊搜索依赖。** 否决，因为该界面只需对小型命令目录使用一种受限的子序列规则；可配置搜索索引会增加 bundle 体积，并引入产品未使用的排名行为。
+
+## Consequences
+
+用户可以凭按顺序记得的字母发现命令；只要目录相同，排名就保持稳定。评分刻意采用启发式规则：与分隔符对齐的匹配可能排在原始跨度更短的匹配之前。包（package）测试固定各项排名因素以及同分时的稳定顺序，组装后的 Web 回放快照固定 `/cpt` 解析为 `/compact` 的行为。精确执行语义保持不变。

.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.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 .agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.md
+2026-08-06-session-completed-done-dot.md: bd6911ce137f1272090c86c029710c9f4054ee6d
+2026-08-06-session-completed-done-dot.zh.md: 9ec2199a29d1307c3ebd0238e84d5f90d36fe21c

.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.md

@@ -0,0 +1,25 @@
+# Agent Note: Session completion dot in the sidebar
+
+Status: implemented
+
+English | [中文](2026-08-06-session-completed-done-dot.zh.md)
+
+## Problem
+
+A session the operator delegated work to and then left (switched to another conversation) gives no signal when it finishes. Its running indicator stops, but the row then looks identical to any idle session, so the operator must poll the list or discover the finished work late. The pending-interaction amber dot covers sessions that need input, not sessions whose work is simply done.
+
+## Decision
+
+`SessionManager` owns a client-side completion-reminder set, a sibling of the pending-interaction bit: a running→idle edge of a session that is not the selected one arms its reminder; `select()`/`selectSubagent()` consume it; starting a new run disarms it and its completion re-arms it; removal prunes it. The bit rides `SessionListEntry` → `SessionSummary` (optional, absent = no reminder) into the workspace browser, whose session and search rows render the existing `StateDot` `done` state — running keeps the ongoing spinner, an idle session without a reminder shows nothing — and whose hover card labels the reminder 已完成 / Completed.
+
+The reminder is in-memory and per browser. It survives connection generations — a transport blip does not invalidate "you have not looked yet" — but not a page reload.
+
+## Consequences
+
+The sidebar row states become three disjoint signals: green = finished and unviewed, amber = awaiting the operator's input, blue = running. No wire, on-disk, or configuration format changes: `SessionSummary.completed` is optional, so existing consumers and test fixtures stay valid, and only the workspace browser reads it. The completion edge is detected eagerly at every list mutation and pull (a snapshot-build-time-only pass would collapse two consecutive status frames into one observation and miss the completion).
+
+## Alternatives considered
+
+- **Component-local UI state.** Rejected because the sidebar unmounts on collapse and multiple surfaces (grouped tree, flat list, search) need the same bit; the manager already owns the running transitions and the selection, so a manager-owned set is the one source all surfaces can project.
+- **Event-driven arming from status frames only.** Rejected because a list pull can also carry a running→idle transition (a session finished while the refresh was in flight); the reminder is reconciled against every mutation and pull.
+- **Persisting the reminder.** Rejected because the reminder means "you have not looked at this session yet" in this browser; reload restores the selection and the user is looking at the list again, so a durable bit would only go stale.

.agents/notes/implemented/feature/2026-08-06-session-completed-done-dot.zh.md

@@ -0,0 +1,25 @@
+# Agent Note: 侧边栏会话完成提醒点
+
+Status: implemented
+
+[English](2026-08-06-session-completed-done-dot.md) | 中文
+
+## Problem
+
+操作者派发任务后切换到其他会话，原会话完成时没有任何信号。运行指示停止后，该行与普通空闲会话看起来完全一样，操作者只能反复查看列表或很晚才发现工作已完成。等待交互的琥珀点只覆盖需要操作者输入的会话，不覆盖"只是干完了活"的会话。
+
+## Decision
+
+`SessionManager` 持有客户端侧的完成提醒集合，与待交互位并列：非当前会话发生 running→idle 边沿时点亮其提醒；`select()`/`selectSubagent()` 消费掉提醒；重新开始一轮运行会熄灭提醒并在再次完成时重新点亮；会话被移除时清理提醒。该位经 `SessionListEntry` → `SessionSummary`（可选字段，缺省 = 无提醒）进入工作区浏览区，其会话行与搜索结果行渲染现有的 `StateDot` `done` 状态——运行中仍显示转圈，无提醒的空闲会话不显示任何点——悬停卡片将该提醒标注为"已完成 / Completed"。
+
+提醒仅存在于内存中且按浏览器实例隔离。它跨连接代存活——传输抖动不会使"你还没回来看"失效——但页面刷新后重置。
+
+## Consequences
+
+侧边栏行状态成为三个互斥信号：绿 = 已完成且未查看，琥珀 = 等待操作者输入，蓝 = 运行中。无 wire、磁盘或配置格式变更：`SessionSummary.completed` 为可选字段，现有消费者与测试 fixture 保持有效，只有工作区浏览区读取它。完成边沿在每次列表变更与拉取时即时检测（仅在建快照时检测会把连续两个状态帧折叠为一次观察，从而漏掉完成事件）。
+
+## Alternatives considered
+
+- **组件本地 UI 状态。** 已拒绝：侧边栏折叠时会卸载，且多个界面（分组树、单列表、搜索）需要同一状态位；manager 本就持有运行状态迁移与选中状态，manager 持有的集合是所有界面都能投影的唯一事实源。
+- **仅从状态帧做事件驱动点亮。** 已拒绝：列表拉取本身也可能携带 running→idle 迁移（刷新在途时会话已完成）；提醒需对每次变更与拉取做对账。
+- **持久化提醒。** 已拒绝：提醒的含义是"此浏览器里你还没查看该会话"；刷新会恢复选中状态且用户正看着列表，持久化位只会过期。

AGENTS.md

@@ -24,6 +24,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
   compact/     compaction seam + basic backend
   context/     request-context plugins
   subagent/    subagent seam + spawn/fork/ACP backends + delegation tool
+  bundle/      profile plugin bundles: installable patch layers for dsh --profile
   workflow/    workflow seam + worker-thread engine + workflow tool
   todo/        todo_write tool
   plan/        plan mode as logged per-agent collaboration state

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 README.md
-README.md: b8e46044fb8857730b32d9fbbb9ed4de964d6017
-README.zh.md: e289d523bf61a577f1dd2335b3b4567736d9100d
+README.md: d8d3e767d5a9805f34f4df57a5b1f8ff7fdaa955
+README.zh.md: 89abf8d817deeed2bf4416035790c8696c8c8e33

README.md

@@ -39,22 +39,24 @@ dsh web
 
 The path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.
 
-### Configured runtime
+### Profiles
 
-Raw `dsh` requires a patch-list configuration applied over the shipped base:
+`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:
 
 ```sh
-dsh --config ./app.cordis.yml
+dsh --profile web                       # the browser UI (same as: dsh web)
+dsh plugin --profile tui add <package>  # install a plugin into a custom profile
+dsh --profile tui                       # boot it
 ```
 
-The [CLI contract](apps/cli/README.md#raw-config) describes the base, overlay semantics, and config dump commands.
+The [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.
 
 ### Headless
 
 Run one task, print the final answer, and exit:
 
 ```sh
-dsh -p "summarize this workspace"
+dsh --profile headless "summarize this workspace"
 ```
 
 ### Automation and SDKs

README.zh.md

@@ -39,22 +39,24 @@ dsh web
 
 上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。
 
-### 自定义运行时
+### Profile
 
-原始 `dsh` 要求传入一份 patch 列表配置，并将其叠加在随附 base 之上：
+`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：
 
 ```sh
-dsh --config ./app.cordis.yml
+dsh --profile web                       # the browser UI (same as: dsh web)
+dsh plugin --profile tui add <package>  # install a plugin into a custom profile
+dsh --profile tui                       # boot it
 ```
 
-base、overlay 语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#raw-config)。
+profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）契约](apps/cli/README.md#profiles)。
 
 ### Headless
 
 运行一项任务，打印最终答案后退出：
 
 ```sh
-dsh -p "summarize this workspace"
+dsh --profile headless "summarize this workspace"
 ```
 
 ### 自动化与 SDK

apps/cli/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 apps/cli/README.md
-README.md: ce7af5a299e45d6f107686aff043246914dce8ed
-README.zh.md: e97fec9d6bb726cb1e419a1ca2fa1871d4d203ca
+README.md: f50f26ec5de54e094e17221f7cd355483483754e
+README.zh.md: 242e64a0c42064b9f0b7621e665e85fe44523fe5

apps/cli/README.md

@@ -2,24 +2,25 @@
 
 English | [中文](README.zh.md)
 
-The `dsh` command is the product launcher for raw Cordis configurations, the Web UI, and one-shot headless tasks. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, configuration errors, and boot failures exit nonzero.
+The `dsh` command is the product launcher for profiles: ordered stacks of plugin-bundle patch layers under the user's own overrides. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, configuration errors, and boot failures exit nonzero.
 
 ## Entry modes
 
 | Command | Purpose |
 |---|---|
-| `dsh --config ./app.cordis.yml` | Run an explicit patch-list configuration over the shipped base. |
-| `dsh web` | Start the browser UI with the shipped Web composition and optional personal configuration. |
-| `dsh -p "task"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
+| `dsh --profile headless "task"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh web` | Alias of `--profile web` with the Web flag family (`--host`, `--port`, `--dev`, ...). |
+| `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-The invoking directory is the default workspace root. Web and headless share the shipped provider, persistence, policy, tool, repository Plugin, and telemetry composition; raw config selects its own deployment-specific front door.
+The invoking directory is the default workspace root. The `web` and `headless` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
 
-## Raw config
+## Profiles
 
-Raw `dsh` requires `--config`. The named patch list is applied directly over [`config/base.cordis.yml`](config/base.cordis.yml); it is not a complete replacement tree and does not add a surface overlay or personal `$DSH_HOME/config.yaml`. Use `--dump-default-config` and `--dump-config` to inspect the resulting tree without booting it.
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer, hot-reloaded on long-lived surfaces). The tree composes over an empty root: each bundle's patch in `dsh.profile.bundles` order, then the profile's `cordis.patch.yml`, then the home-level `$DSH_HOME/cordis.patch.yml`, then `--patch` overlays, then flag patches. Bundles named in `dsh.profile.bundles` resolve from the dsh installation first (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins. Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
 
-The [CLI behavior reference](reference/README.md) owns exact overlay precedence, flags, shutdown behavior, deployment defaults, and the source launcher.
+The [CLI behavior reference](reference/README.md) owns exact layer precedence, flags, shutdown behavior, deployment defaults, and the source launcher.
 
 ## Development
 
-Production Web and headless runs require built package and frontend artifacts. From a checkout, `pnpm run dsh` runs the TypeScript entry and forwards arguments; the [source-launcher reference](reference/README.md#source-launcher) describes the PATH symlink and module-resolution contract.
+Production runs require built package and frontend artifacts. From a checkout, `pnpm run dsh` runs the TypeScript entry and forwards arguments; the [source-launcher reference](reference/README.md#source-launcher) describes the PATH symlink and module-resolution contract.

apps/cli/README.zh.md

@@ -2,24 +2,25 @@
 
 [English](README.md) | 中文
 
-`dsh` 命令是原始 Cordis 配置、Web UI 和一次性无头任务的产品启动器。[`src/args.ts`](src/args.ts) 负责命令语法，[`src/bin.ts`](src/bin.ts) 只加载选中的运行器。无效命令、来自其他模式的选项、配置错误和启动失败都会以非零状态退出。
+`dsh` 命令是 profile 的产品启动器：profile 是按序叠放的插件组合包 patch 层，之上再叠加用户自己的覆盖层。[`src/args.ts`](src/args.ts) 负责命令语法，[`src/bin.ts`](src/bin.ts) 只加载选中的运行器。无效命令、来自其他模式的选项、配置错误和启动失败都会以非零状态退出。
 
 ## 入口模式
 
 | 命令 | 用途 |
 |---|---|
-| `dsh --config ./app.cordis.yml` | 在随附基础配置之上运行显式 patch 列表配置。 |
-| `dsh web` | 使用随附 Web 组合和可选个人配置启动浏览器 UI。 |
-| `dsh -p "task"` | 运行一个新的持久化会话，打印最终答案并退出。 |
+| `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
+| `dsh --profile headless "task"` | 运行一个新的持久化会话，打印最终答案并退出。 |
+| `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
+| `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
-调用目录是默认 workspace 根目录。Web 与无头模式共享随附的提供方、持久化、策略、工具、repository Plugin 和遥测组合；原始配置自行选择部署专用前端入口。
+调用目录是默认 workspace 根目录。`web` 和 `headless` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
 
-## 原始配置
+## Profile
 
-原始 `dsh` 必须提供 `--config`。指定的 patch 列表直接应用到 [`config/base.cordis.yml`](config/base.cordis.yml) 之上；它不是完整替代树，也不会添加 surface overlay 或个人 `$DSH_HOME/config.yaml`。使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查生成的配置树。
+profile 目录包含一个 `package.json`（树外插件依赖，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 列表）和一个 `cordis.patch.yml`（用户自己的 patch 层，在长期运行的 surface 上热重载）。配置树在空根之上组合：先按 `dsh.profile.bundles` 顺序应用各组合包的 patch，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`，然后是 `--patch` overlay，最后是 flag patch。`dsh.profile.bundles` 中列出的组合包先从 dsh 安装目录解析（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`），再从 profile 自己的 `node_modules` 解析；pnpm 把树外插件安装在后者。使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。
 
-[CLI（命令行界面）行为参考](reference/README.md)负责确切的 overlay 优先级、flag、关闭行为、部署默认值和源码启动器。
+[CLI（命令行界面）行为参考](reference/README.md)负责确切的层优先级、flag、关闭行为、部署默认值和源码启动器。
 
 ## 开发
 
-生产环境的 Web 和无头运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。

apps/cli/composition.md

@@ -3,11 +3,11 @@
 
 # DSH Base Composition
 
-The raw CLI applies one required caller-selected patch list over this shared base; Web and headless apply their own shipped overlays.
+The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user's profile layer patch over it.
 
 ```mermaid
 flowchart LR
-  cfg["apps/cli/config/base.cordis.yml<br/>cordis.yml"]
+  cfg["packages/bundle/base/cordis.patch.yml<br/>cordis.yml"]
   plugin_dsh_base_timer["timer<br/>@cordisjs/plugin-timer"]
   cfg --> plugin_dsh_base_timer
   plugin_dsh_base_hmr["hmr<br/>@cordisjs/plugin-hmr"]
@@ -220,6 +220,6 @@ flowchart LR
 | `fs-sandbox` | `@deepseek-ai/dsh-fs-sandbox` |
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 
-Source config: [`apps/cli/config/base.cordis.yml`](config/base.cordis.yml).
+Source config: [`packages/bundle/base/cordis.patch.yml`](../../packages/bundle/base/cordis.patch.yml).
 
 Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.

apps/cli/config/base.cordis.yml

@@ -1,403 +0,0 @@
-# The shared `dsh` core. Raw `dsh --config <path>` applies its required patch
-# list directly over this file. Web and headless apply their shipped overlay,
-# followed by an explicit or personal user layer. Every layer addresses these
-# rows by id at one include level, 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 overlay, keeping any single row down to one overlay layer plus the user's.
-# Mode-specific rows appear below only with shared plugin identity and neutral
-# defaults; each overlay restates its complete configuration.
-#
-# Row order carries no load semantics (activation is service-availability
-# driven); the grouping is for readers.
-
-- id: timer
-  name: '@cordisjs/plugin-timer'
-
-- id: hmr
-  name: '@cordisjs/plugin-hmr'
-  config:
-    root: ['.']
-
-# `$DSH_HOME/config.yaml` 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'

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh",
-  "description": "dsh CLI: explicit config overlays, headless tasks, and the browser UI",
+  "description": "dsh CLI: profile boot, plugin management, and the browser UI alias",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -17,126 +17,31 @@
     "@cordisjs/plugin-include": "workspace:*",
     "@cordisjs/plugin-loader": "workspace:*",
     "@cordisjs/plugin-timer": "workspace:*",
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-app-boot": "workspace:^",
-    "@deepseek-ai/dsh-bash-local": "workspace:^",
-    "@deepseek-ai/dsh-bash-env": "workspace:^",
-    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
-    "@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-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-frontend": "workspace:^",
-    "@deepseek-ai/dsh-fs-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-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-llm": "workspace:^",
-    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
-    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
-    "@deepseek-ai/dsh-llm-retry": "workspace:^",
+    "@deepseek-ai/dsh-base": "workspace:^",
+    "@deepseek-ai/dsh-headless": "workspace:^",
     "@deepseek-ai/dsh-mcp-client": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
-    "@deepseek-ai/dsh-permission": "workspace:^",
-    "@deepseek-ai/dsh-plan-mode": "workspace:^",
-    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
-    "@deepseek-ai/dsh-pwsh-local": "workspace:^",
-    "@deepseek-ai/dsh-repository-plugin": "workspace:^",
-    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
-    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
-    "@deepseek-ai/dsh-scope": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-session-projection": "workspace:^",
-    "@deepseek-ai/dsh-session-projection-cache": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "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-storage": "workspace:^",
-    "@deepseek-ai/dsh-storage-domain": "workspace:^",
-    "@deepseek-ai/dsh-storage-json": "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-session-reference": "workspace:^",
+    "@deepseek-ai/dsh-tmux-context": "workspace:^",
+    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
     "@deepseek-ai/dsh-tool-bash-persistent": "workspace:^",
     "@deepseek-ai/dsh-tool-cordis": "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-pwsh": "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": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
+    "@deepseek-ai/dsh-web-app": "workspace:^",
     "commander": "^15.0.0",
     "cordis": "^4.0.0-rc.7",
     "js-yaml": "^4.2.0",
     "node-addon-require-builtin": "^0.1.4"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-frontend-static": "workspace:^",
+    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
     "@types/js-yaml": "^4.0.9",
     "execa": "^10.0.0"
   }

apps/cli/reference/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 apps/cli/reference/README.md
-README.md: b37ec9ed61ea4e9899a51316065d4188f30997ad
-README.zh.md: ca29808a6c8e670f0d0b82c59b1a2c1fa0e13565
+README.md: 62275139809364d80296433e804ade3d447f37e6
+README.zh.md: e508caaf05622c0c177eaacd070978368ff84af3

apps/cli/reference/README.md

@@ -2,68 +2,66 @@
 
 English | [中文](README.zh.md)
 
-This reference defines the raw-config, Web, and headless command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
+This reference defines the profile, web-alias, plugin-management, and config-dump command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
 
-## Raw config
+## Profile boot
 
-Raw `dsh` requires an explicit patch-list config:
+`dsh --profile <name>` boots the profile at `$DSH_HOME/profiles/<name>`. The effective tree is composed over an empty root by applying, in order: each bundle patch named in the profile manifest's `dsh.profile.bundles` list, the profile's own `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml` (machine-local preferences shared by every profile, so it outranks the per-profile layer), each `--patch <path>` overlay in argv order, and launcher flag patches. Later layers win per row; a patch replaces the targeted row's complete `config` value rather than deep-merging keys, and may insert new rows. A parse, schema, resolution, or plugin boot failure is reported and exits nonzero. SIGINT and SIGTERM dispose the mounted root before exit.
 
-```sh
-dsh --config ./app.cordis.yml
-```
+Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. A bare plugin `name` in any patch row resolves through the profile directory's Node parent-walk, which reaches the maintained installation fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
-The named file is applied directly over [`config/base.cordis.yml`](../config/base.cordis.yml) through the Include plugin's patch algorithm. It is not a complete replacement tree, and neither the personal `$DSH_HOME/config.yaml` nor another surface overlay is added. The base deliberately contains no startup agent or interaction front door; the required overlay selects those deployment details. Relative config paths resolve from the invoking directory. A parse, schema, resolution, or plugin boot failure is reported and exits nonzero. SIGINT and SIGTERM dispose the mounted root before exit.
+The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + web-app + headless). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
-A patch targets a base row by `id` and replaces that row's complete `config` value rather than deep-merging keys. Patch lists may also insert new rows whose plugin modules the shipped Loader can resolve:
+A positional task (`dsh --profile headless "run the tests"`) requires the composition to mount the one-shot runner row (`headless-runner`); the launcher patches the task text into that row, the runner drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
 
-```yaml
-- id: agent-loop
-  config:
-    agents:
-      - id: main
-        provider: deepseek-official
-        model: deepseek-v4-flash
+Inspect the composed tree without booting it:
+
+```sh
+dsh --profile web --dump-default-config
+dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-Inspect the effective tree without booting it:
+`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print provenance comments per layer; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
+
+## Plugin management
+
+`dsh plugin --profile <name> <args...>` initializes the profile when missing (shipped template, or `@deepseek-ai/dsh-base` alone for other names), then forwards `<args...>` to `pnpm` with the profile directory as working directory — `add`, `remove`, `why`, `update`, and every other pnpm verb work unchanged; pnpm must be on PATH. Relative path specs (`.`, `../plugin`, and their `file:`/`link:` forms) are anchored to the invoking directory first, so `add .` from a plugin checkout installs that checkout, not the profile. After every successful run, `dsh.profile.bundles` is reconciled against the installed state: each dependency resolving to a package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` joins the layer stack (so an `update` that gains the declaration activates it), a bundle-less dependency stays plain with a one-time warning, and a removed dependency leaves the stack.
 
 ```sh
-dsh --dump-default-config
-dsh --config ./app.cordis.yml --dump-config
+dsh plugin --profile tui add github:deepseek-harness/turtle-ui
+dsh plugin --profile tui remove turtle-ui
+dsh --profile tui
 ```
 
-`--dump-default-config` prints only the shipped base. `--dump-config` requires `--config` and prints base plus overlay with provenance comments. Composition uses `applyEntryPatches` and `entryListSchema` from `@cordisjs/plugin-include`; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
+Git-hosted plugins that ship sources build during install through their `prepare` script, which pnpm ≥10 blocks until the consumer allows it: the first `add` fails with pnpm's `allowBuilds` hint (and a dsh pointer at the profile's `pnpm-workspace.yaml`); copy the printed key there and re-run. Installing a built tarball or a local checkout needs no allowance.
 
-## Web and headless
+## Web alias
 
-`dsh web` boots `base.cordis.yml` plus [`config/web.cordis.yml`](../config/web.cordis.yml), followed by `$DSH_HOME/config.yaml` when present. `dsh web --config <path>` replaces that personal layer with the explicit patch list. `--host`, `--port`, `--workspace-root`, and repeatable `--trusted-host` values become Web host patches; their owning plugin schemas validate them at boot. `--dev` mounts the client-plugin HMR receiver and expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
+`dsh web` is a hardcoded alias for `--profile web` that additionally accepts the Web flag family. `--host`, `--port`, `--workspace-root`, and repeatable `--trusted-host` values become patches over the composed rows; their owning plugin schemas validate them at boot. `--dev` switches the web-runtime row to development mode and inserts the client-plugin HMR receiver; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
 
 ```sh
 dsh web
-dsh web --config ./web-profile.cordis.yml
-dsh web --dump-default-config
+dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
 ```
 
 The production Web runner needs built package and frontend artifacts (`pnpm run build`). It serves `http://127.0.0.1:3080` by default. Binding all interfaces also trusts the machine's discovered LAN IP literals; `--trusted-host` adds named authorities accepted by the `/api` browser-trust fence.
 
-`dsh -p "task"` uses the same base and Web composition with the startup personal config, starts its Web host on an OS-assigned port, runs one fresh persisted session, prints the final answer, and exits. It accepts neither `--config` nor raw config-dump flags.
-
-Web and headless process shutdown gives the plugin tree up to five seconds to dispose. The first `SIGINT`/`SIGTERM` starts that graceful drain; a second signal forces immediate exit. If headless normal completion is already stuck in disposal, the first `Ctrl+C` is the escalation and exits immediately instead of being swallowed.
+Process shutdown gives the plugin tree up to five seconds to dispose. The first `SIGINT`/`SIGTERM` starts that graceful drain; a second signal forces immediate exit. If one-shot normal completion is already stuck in disposal, the first `Ctrl+C` is the escalation and exits immediately instead of being swallowed.
 
-Both modes treat the invoking directory as the default workspace root, load applicable `AGENTS.md` or `CLAUDE.md` instructions with a 65,536-byte render budget, and use an in-memory SQLite session content index. Web watches valid personal config edits; headless reads the file once at startup. The [app-boot personal-config contract](../../../packages/ui/app-boot/README.md#personal-config) owns layer precedence, credential storage, live-update failure behavior, and `$DSH_HOME` resolution.
+All modes treat the invoking directory as the default workspace root, load applicable `AGENTS.md` or `CLAUDE.md` instructions with a 65,536-byte render budget, and use an in-memory SQLite session content index. Long-lived surfaces watch valid edits of both `cordis.patch.yml` layers (profile and home) and reapply them transactionally; one-shot runs read the files once at startup.
 
 New sessions default to the `workspace-write` permission preset. Bash and filesystem mutations are restricted to the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. `DSH_PERMISSION_MODE` changes the process fallback. Stored General-settings permissions affect later Web sessions, not an already-open one.
 
-`DSH_TOOLS_MODE` selects `native`, `code`, or `both` for the Web/headless process; another value fails at boot. [`config/core-web.cordis.yml`](../config/core-web.cordis.yml) is an optional Web overlay that reduces the native model surface to persistent `bash` and `str_replace_editor` while retaining the shipped host, browser, workspace, persistence, and permission composition.
+`DSH_TOOLS_MODE` selects `native`, `code`, or `both` for the process; another value fails at boot. [`config/core-web.cordis.yml`](../config/core-web.cordis.yml) is an optional `--patch` overlay that reduces the native model surface to persistent `bash` and `str_replace_editor` while retaining the shipped host, browser, workspace, persistence, and permission composition.
 
 ## Shared deployment behavior
 
-The base mounts the native DeepSeek adapter, settings and credential providers, stable `web_search`, repository Plugin support, and session telemetry. Provider credentials live in `$DSH_HOME/.env` or the ambient environment and remain rotatable because the launcher never hoists the credential file into `process.env`. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`; `web_fetch` is disabled unless an overlay inserts a provider and enables it.
+The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search`, repository Plugin support, and session telemetry. Provider credentials live in `$DSH_HOME/.env` or the ambient environment and remain rotatable because the launcher never hoists the credential file into `process.env`. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`; `web_fetch` is disabled unless a patch layer inserts a provider and enables it.
 
 Session events stream as OTLP/HTTP logs by default. `DSH_TELEMETRY_OTLP_URL` selects another collector. Any non-empty `DSH_TELEMETRY_DISABLED` disables the telemetry row before boot. The shipped base has no telemetry redaction rule, so exported records can contain message text, tool arguments and results, and workspace paths; the [telemetry Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md) owns that deployment decision.
 
-The empty `repository-plugins` row lets Web/headless personal config and raw overlays mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for overlays, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
+The empty `repository-plugins` row lets profile patch layers mount prepared immutable repository Plugin generations. See the [repository Plugin contract](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration). The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
 
 ## Source launcher
 

apps/cli/reference/README.zh.md

@@ -2,68 +2,66 @@
 
 [English](README.md) | 中文
 
-本参考定义原始配置、Web 和无头命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
+本参考定义 profile、web 别名、插件管理和配置 dump 命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
 
-## 原始配置
+## Profile 启动
 
-原始 `dsh` 必须提供显式 patch 列表配置：
+`dsh --profile <name>` 启动位于 `$DSH_HOME/profiles/<name>` 的 profile。生效配置树在空根节点之上按以下顺序逐层组合：profile manifest（元数据清单）的 `dsh.profile.bundles` 列表所列的各个组合包 patch、profile 自身的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml`（各 profile 共享的机器本地偏好，因此优先级高于逐 profile 的层）、按 argv 顺序的各个 `--patch <path>` overlay，以及启动器 flag patch。后应用的层按行胜出；patch 替换目标行完整的 `config` 值，而不是深度合并各键，并且可以插入新行。配置解析、schema 校验、模块解析或插件启动失败会得到报告并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
 
-```sh
-dsh --config ./app.cordis.yml
-```
+组合包名称先从 dsh 安装解析，再从 profile 目录解析。因此内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`）总是来自与正在运行的 `dsh` 相同的安装；树外组合包来自 profile 由 pnpm 管理的 `node_modules`。任何 patch 行中的裸插件 `name` 通过 profile 目录的 Node 父目录逐级查找解析，该查找可达到持续维护的安装后备目录 `$DSH_HOME/profiles/node_modules`（安装的应用和组合包所依赖的每个包对应一个符号链接，每次启动时修复）。
 
-指定文件通过 Include 插件的 patch 算法直接应用到 [`config/base.cordis.yml`](../config/base.cordis.yml) 之上。它不是完整替代树，也不会添加个人 `$DSH_HOME/config.yaml` 或其他 surface overlay。基础配置刻意不包含启动 agent（智能体）或交互前端入口；必填 overlay 负责选择这些部署细节。相对配置路径从调用目录解析。配置解析、schema 校验、模块解析或插件启动失败会得到报告并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
+`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + web-app + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
-patch 通过 `id` 定位基础配置行，并替换该行完整的 `config` 值，而不是深度合并各键。patch 列表也可插入新行，只要随附 Loader 能解析其插件模块：
+位置参数任务（`dsh --profile headless "run the tests"`）要求组合挂载一次性运行器行（`headless-runner`）；启动器把任务文本 patch 进该行，运行器通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
 
-```yaml
-- id: agent-loop
-  config:
-    agents:
-      - id: main
-        provider: deepseek-official
-        model: deepseek-v4-flash
+可在不启动的情况下检查组合出的配置树：
+
+```sh
+dsh --profile web --dump-default-config
+dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-可在不启动的情况下检查生效的配置树：
+`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会按层打印来源注释；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
+
+## 插件管理
+
+`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，`dsh.profile.bundles` 都会与已安装状态对齐：每个解析到 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的包的依赖加入层栈（因此让包获得该声明的 `update` 会将其激活），没有组合包声明的依赖保持为普通依赖并给出一次性警告，已移除的依赖则退出层栈。
 
 ```sh
-dsh --dump-default-config
-dsh --config ./app.cordis.yml --dump-config
+dsh plugin --profile tui add github:deepseek-harness/turtle-ui
+dsh plugin --profile tui remove turtle-ui
+dsh --profile tui
 ```
 
-`--dump-default-config` 只打印随附基础配置。`--dump-config` 必须与 `--config` 同时使用，并打印基础配置和带来源注释的 overlay。组合使用 `@cordisjs/plugin-include` 的 `applyEntryPatches` 与 `entryListSchema`；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
+Git 托管、随附源码的插件在安装期间通过其 `prepare` 脚本构建，而 pnpm ≥10 在消费方允许之前会阻止该脚本：首次 `add` 会失败并给出 pnpm 的 `allowBuilds` 提示（以及 dsh 指向该 profile 的 `pnpm-workspace.yaml` 的指引）；把打印出的键复制到那里并重新运行即可。安装已构建的 tarball 或本地 checkout 不需要任何允许。
 
-## Web 与无头模式
+## Web 别名
 
-`dsh web` 启动 `base.cordis.yml` 加 [`config/web.cordis.yml`](../config/web.cordis.yml)，并在 `$DSH_HOME/config.yaml` 存在时继续加载它。`dsh web --config <path>` 用显式 patch 列表替代该个人层。`--host`、`--port`、`--workspace-root` 和可重复的 `--trusted-host` 值会成为 Web 宿主 patch；负责这些值的插件 schema 会在启动时验证它们。`--dev` 挂载客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
+`dsh web` 是 `--profile web` 的硬编码别名，并额外接受 Web flag 系列。`--host`、`--port`、`--workspace-root` 和可重复的 `--trusted-host` 值会成为作用在组合行之上的 patch；负责这些值的插件 schema 会在启动时验证它们。`--dev` 把 web-runtime 行切换到开发模式并插入客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
 
 ```sh
 dsh web
-dsh web --config ./web-profile.cordis.yml
-dsh web --dump-default-config
+dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
 ```
 
 生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
 
-`dsh -p "task"` 使用同一基础配置和 Web 组合，并加载启动时的个人配置；它在 OS 分配的端口上启动 Web 宿主，运行一个新的持久化会话，打印最终答案并退出。它不接受 `--config` 或原始配置 dump flag。
-
-Web 和无头进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空；第二次信号强制立即退出。如果无头模式正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
+进程关闭时会给插件树最多 5 秒完成 dispose。第一次 `SIGINT`/`SIGTERM` 启动该优雅排空；第二次信号强制立即退出。如果一次性运行正常结束时已经卡在 dispose 中，第一次 `Ctrl+C` 就会升格并立即退出，而不会被吞掉。
 
-两种模式都将调用目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 `AGENTS.md` 或 `CLAUDE.md` 指令，并使用内存 SQLite 会话内容索引。Web 监视有效的个人配置编辑；无头模式只在启动时读取该文件。[app-boot 个人配置契约](../../../packages/ui/app-boot/README.md#personal-config)负责配置层优先级、凭据存储、实时更新失败行为和 `$DSH_HOME` 解析。
+所有模式都将调用目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 `AGENTS.md` 或 `CLAUDE.md` 指令，并使用内存 SQLite 会话内容索引。常驻 surface 监视两个 `cordis.patch.yml` 层（profile 与 home）的有效编辑并以事务方式重新应用；一次性运行只在启动时读取这些文件一次。
 
 新会话默认使用 `workspace-write` 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取、网络访问和进程可见性不受限制。`DSH_PERMISSION_MODE` 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。
 
-`DSH_TOOLS_MODE` 为 Web／无头进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选 Web overlay：它在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，把原生模型 surface 缩减为持久 `bash` 和 `str_replace_editor`。
+`DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 `--patch` overlay：它在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，把原生模型 surface 缩减为持久 `bash` 和 `str_replace_editor`。
 
 ## 共享部署行为
 
-基础配置挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据存放在 `$DSH_HOME/.env` 或环境中；启动器从不把凭据文件提升到 `process.env`，因此凭据可以轮换。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 overlay 插入提供方并启用 `web_fetch` 后，该工具才可用。
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search`、repository Plugin 支持和会话遥测。提供方凭据存放在 `$DSH_HOME/.env` 或环境中；启动器从不把凭据文件提升到 `process.env`，因此凭据可以轮换。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`；只有 patch 层插入提供方并启用 `web_fetch` 后，该工具才可用。
 
 会话事件默认作为 OTLP/HTTP 日志流式发送。`DSH_TELEMETRY_OTLP_URL` 选择其他 collector。任何非空 `DSH_TELEMETRY_DISABLED` 都会在启动前禁用遥测配置行。随附基础配置没有遥测脱敏规则，因此导出的记录可能包含消息文本、工具参数与结果以及 workspace 路径；该部署决策由[遥测 Agent Note](../../../.agents/notes/implemented/feature/2026-07-31-web-telemetry-default-mount.md)负责。
 
-空 `repository-plugins` 行让 Web／无头个人配置和原始 overlay 能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为 overlay 的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent 沙箱之外的受信任可执行代码。
+空 `repository-plugins` 行让 profile 的 patch 层能够挂载已准备的不可变 repository Plugin generation。参见 [repository Plugin 契约](../../../packages/cordis/repository-plugin/README.md#standalone-app-configuration)。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent（智能体）沙箱之外的受信任可执行代码。
 
 ## 源码启动器
 

apps/cli/src/app-cli-entry.ts

@@ -1,355 +0,0 @@
-/**
- * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
- * (`dsh web` and `dsh -p`).
- * Everything here is what must exist before the Loader runs: the patch
- * composition over the shipped base and Web overlay (profile json + CLI
- * flags + the resolved frontend dist), and the fail-loud activation audit after the tree
- * settles. The environment is what the bin already loaded (ambient plus the
- * invoking directory's `.env`); `$DSH_HOME/.env` belongs to the credential
- * provider and is never hoisted here.
- */
-
-import { readFileSync } from 'node:fs'
-import { createRequire } from 'node:module'
-import { networkInterfaces } from 'node:os'
-import { join, resolve } from 'node:path'
-import { Context } from 'cordis'
-import type { PatchOptions } from '@cordisjs/plugin-include'
-import yaml from 'js-yaml'
-import {
-  boot,
-  installFailLoud,
-  loadOverlayPatches,
-  loadPersonalPatches,
-  watchPersonalPatches,
-} from '@deepseek-ai/dsh-app-boot'
-// Empty type import carries the httpServer Context merge for the port read below.
-import type {} from '@deepseek-ai/dsh-host-webserver'
-
-/** Profile file under the invoking directory (read-only this round; never created — see the design's profile ruling). */
-const PROFILE_DIR = '.dsh-tmp-profile'
-const PROFILE_FILE = 'config.json'
-
-/** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets (mounted in web.cordis.yml). */
-const TELEMETRY_ROW_ID = 'telemetry-otel'
-
-/** The webserver schema's all-interfaces bind literal: gates LAN-authority derivation here and the printed LAN URL in web.ts. */
-const ALL_INTERFACES_HOST = '0.0.0.0'
-
-/**
- * Non-internal IPv4 interface addresses of this machine — the IP-literal
- * authorities an all-interfaces bind is reachable by on the LAN.
- * @returns the addresses in interface order (possibly empty).
- */
-function lanIPv4Addresses(): string[] {
-  return Object.values(networkInterfaces()).flat()
-    .filter((iface): iface is NonNullable<typeof iface> => iface !== undefined && iface.family === 'IPv4' && !iface.internal)
-    .map(iface => iface.address)
-}
-
-/**
- * One LAN-trust resolution for one invocation, sampled exactly once: the
- * machine's LAN IP literals when the effective bind is all-interfaces, and
- * the `trustedHosts` value built from them plus the explicit extras. The
- * single sample is deliberate — display must advertise only addresses the
- * fence was configured with, so both read this snapshot. Derived entries are
- * port-less IP literals: DNS rebinding needs an attacker-controlled name, so
- * an IP-literal Host is safe on any port, and the bound port may be
- * OS-assigned, unknowable pre-boot.
- * @param bindHost - the effective webserver bind host (CLI flag, else the yml default).
- * @param extra - `--trusted-host` values, in argv order.
- * @returns the sampled LAN addresses and the connection row's `trustedHosts` value (each possibly empty).
- */
-export function resolveLanTrust(
-  bindHost: string | undefined,
-  extra: readonly string[],
-): { lanAddresses: string[]; trustedHosts: string[] } {
-  const lanAddresses = bindHost === ALL_INTERFACES_HOST ? lanIPv4Addresses() : []
-  return { lanAddresses, trustedHosts: [...lanAddresses, ...extra] }
-}
-
-/**
- * Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
- * value (including `'0'`/`'false'`) disables: a privacy switch prefers
- * off-by-mistake over on-by-mistake. Throws when the switch is set but the
- * row is absent — a silently no-op "disabled" privacy switch would keep
- * exporting while the user believes it is off.
- * @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
- * @param hasRow - whether the composition carries the {@link TELEMETRY_ROW_ID} row.
- * @returns the disable patch, or `undefined` when telemetry stays enabled.
- */
-export function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: boolean): PatchOptions | undefined {
-  if ((disabledEnv ?? '') === '') return undefined
-  if (!hasRow) {
-    throw new Error(`dsh: DSH_TELEMETRY_DISABLED is set but row "${TELEMETRY_ROW_ID}" is not in this composition`)
-  }
-  return { id: TELEMETRY_ROW_ID, disabled: true }
-}
-
-/**
- * Whether a config file carries the telemetry row, parsed under the same
- * `!!js`-tolerant dialect the boot uses — the `hasRow` input for launchers
- * that compose their patch lists outside {@link AppCLIEntry} (raw `dsh`).
- * @param file - absolute path of the config or overlay file.
- * @returns true when a top-level (or inserted) row has the telemetry id.
- */
-export function configHasTelemetryRow(file: string): boolean {
-  const doc = yaml.load(readFileSync(file, 'utf8'), { schema: includeYamlSchema })
-  if (!Array.isArray(doc)) throw new Error(`dsh: ${file} is not a top-level entry list`)
-  return (doc as { id?: string; insert?: { id?: string }[] }[]).some(row =>
-    row.id === TELEMETRY_ROW_ID || (row.insert ?? []).some(inserted => inserted.id === TELEMETRY_ROW_ID))
-}
-
-/** One profile-json key mapped onto a yml row's config field. */
-interface ProfileMapping {
-  jsonPath: string
-  entryId: string
-  configKey: string
-}
-
-/**
- * The static profile→row mapping table. json is user config and wins over the
- * yml engineering default per field; a json key absent from this table fails
- * loud (a typo silently ignored would read as "setting has no effect").
- * Developers extend deployments by adding rows here.
- */
-const PROFILE_MAPPINGS: ProfileMapping[] = [
-  { jsonPath: 'provider', entryId: 'api-gateway', configKey: 'provider' },
-  { jsonPath: 'model', entryId: 'api-gateway', configKey: 'model' },
-  { jsonPath: 'persistenceRoot', entryId: 'session-persistence-jsonl', configKey: 'root' },
-]
-
-// The include's YAML dialect: `!!js` scalars become expression nodes the
-// Loader evaluates at entry activation. The bypass parse below must accept
-// them (and passing one through a patch unchanged is legal).
-const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
-  kind: 'scalar',
-  resolve: data => typeof data === 'string',
-  construct: data => ({ __jsExpr: String(data) }),
-})
-const includeYamlSchema = yaml.JSON_SCHEMA.extend(jsExprType)
-
-/** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
-export interface AppCLIEntryOptions {
-  /** Absolute path of the shared base config the Loader includes. */
-  configPath: string
-  /**
-   * Absolute path of this surface's overlay: a patch list applied over
-   * {@link configPath} before this entry's own profile/flag patches. Its rows
-   * are also merge inputs, so a flag override preserves the overlay's other
-   * fields on the same row.
-   */
-  overlayPath: string
-  /**
-   * Optional explicit overlay applied after {@link overlayPath} and before
-   * this entry's own profile/flag patches. When absent, the personal
-   * `$DSH_HOME/config.yaml` overlay is applied instead.
-   */
-  extraOverlayPath?: string
-  /** Whether to append client-bundle HMR (the Web surface's prod/dev difference). */
-  dev: boolean
-  /** Whether `$DSH_HOME/config.yaml` remains live after the initial boot. */
-  watchPersonalConfig: boolean
-  /** --host when explicitly passed; undefined keeps the yml engineering default. */
-  host?: string
-  /**
-   * Listen port override onto the webserver row. Web passes the --port flag
-   * value; headless passes 0 (an OS-assigned port, so parallel `dsh -p` runs
-   * never collide — and the printed URL still opens the live session in a
-   * browser).
-   */
-  port?: number
-  /** Parent directory for name-created Workspaces; undefined uses the gateway's cwd fallback. */
-  workspaceRoot?: string
-  /** Extra authorities for the /api browser-trust fence (`host` or `host:port`), appended to the derived LAN IP literals. */
-  trustedHosts?: string[]
-  /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
-  prepare?: (ctx: Context) => Promise<void> | void
-}
-
-/**
- * Boot driver for the config-tree dsh surfaces (web and headless share the
- * one composition; the surfaces differ only in constructor facts): holds only
- * what exists independently of (and prior to) cordis — argv facts, the
- * composed patch set, and finally the root ctx.
- */
-export class AppCLIEntry {
-  /** The root context, set by {@link run}. */
-  ctx!: Context
-
-  /**
-   * LAN IPv4 addresses sampled once at patch composition — the exact snapshot
-   * the /api trust fence was configured with. Display reads this instead of
-   * re-sampling, so the advertised LAN URL can never name an address the
-   * fence rejects. Empty unless the effective bind is all-interfaces.
-   */
-  lanAddresses: readonly string[] = []
-
-  private patches: PatchOptions[] = []
-
-  constructor(private readonly options: AppCLIEntryOptions) {}
-
-  /**
-   * Run the boot chain: patch composition → Loader installation → surface
-   * preparation → config-tree boot (dev row before await) → fail-loud triple.
-   * @returns the settled root context and the listening port.
-   */
-  async run(): Promise<{ ctx: Context; port: number }> {
-    this.composePatches()
-    await this.bootTree()
-    this.assertBoot()
-    const port = this.ctx.get('httpServer')?.port
-    /* v8 ignore next -- the sweep above guarantees an ACTIVE webserver row */
-    if (port === undefined) throw new Error('dsh: httpServer service missing after settled boot')
-    return { ctx: this.ctx, port }
-  }
-
-  /**
-   * Compose the patch set from profile json, CLI flags, and the resolved
-   * frontend dist. Patches replace a row's config wholesale, so each patched row's yml
-   * static values are re-read here (bypass parse) and merged under the overrides.
-   */
-  private composePatches(): void {
-    const rows = this.parseYmlRows()
-    const overrides = new Map<string, Record<string, unknown>>()
-    const put = (entryId: string, key: string, value: unknown): void => {
-      const bag = overrides.get(entryId) ?? {}
-      bag[key] = value
-      overrides.set(entryId, bag)
-    }
-
-    // Source 1: profile json (missing file = empty; unmapped key = loud).
-    for (const [key, value] of Object.entries(this.readProfile())) {
-      const mapping = PROFILE_MAPPINGS.find(m => m.jsonPath === key)
-      if (mapping === undefined) {
-        throw new Error(`dsh: profile key "${key}" has no mapping (known: ${PROFILE_MAPPINGS.map(m => m.jsonPath).join(', ')})`)
-      }
-      put(mapping.entryId, mapping.configKey, value)
-    }
-
-    // Source 2: CLI flags (field set disjoint from the json mappings).
-    if (this.options.host !== undefined) put('webserver', 'host', this.options.host)
-    if (this.options.port !== undefined) put('webserver', 'port', this.options.port)
-    if (this.options.workspaceRoot !== undefined) put('api-gateway', 'workspaceRoot', this.options.workspaceRoot)
-
-    // Source 2b: authorities for the /api browser-trust fence (rationale on
-    // resolveLanTrust).
-    const ymlHost = (rows.get('webserver')?.config as { host?: string } | undefined)?.host
-    const { lanAddresses, trustedHosts } = resolveLanTrust(this.options.host ?? ymlHost, this.options.trustedHosts ?? [])
-    this.lanAddresses = lanAddresses
-    if (trustedHosts.length > 0) put('connection', 'trustedHosts', trustedHosts)
-
-    // Source 3: the frontend dist — an assembly fact of this app, never yml
-    // user config. Workspace knowledge stays here.
-    put('webserver', 'distIndex', this.resolveDistIndex())
-
-    const generated = [...overrides.entries()].map(([id, bag]) => {
-      const yml = rows.get(id)
-      if (yml === undefined) throw new Error(`dsh: patch target row "${id}" not found in ${this.options.configPath}`)
-      return { id, config: { ...(yml.config ?? {}) as Record<string, unknown>, ...bag } }
-    })
-    this.patches = generated
-
-    // Telemetry opt-out: a row can only be turned off at the patch layer
-    // (config cannot disable an entry), and the switch must hold BEFORE the
-    // plugin constructs — its exporter.url validation is load-time fail-loud.
-    const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID))
-    if (telemetryPatch !== undefined) this.patches.push(telemetryPatch)
-  }
-
-  /** Shared Loader boot; surface preparation precedes the tree, and the dev HMR row precedes the activation audit. */
-  private async bootTree(): Promise<void> {
-    // One include of the shared base with every overlay as a sibling patch
-    // list: patches never cross an include boundary, so nesting them would
-    // silently stop reaching base rows. The surface overlay applies first, then
-    // this entry's profile-json and CLI-flag patches, which therefore win.
-    const compose = (overlay: PatchOptions[]): PatchOptions[] => [
-      ...loadOverlayPatches('dsh', this.options.overlayPath),
-      ...overlay,
-      ...this.patches,
-    ]
-    // An explicit --config overlay REPLACES the personal overlay, so there is
-    // then no personal layer to keep live — the watcher is personal-only.
-    const watchPersonal = this.options.watchPersonalConfig && this.options.extraOverlayPath === undefined
-    const patches = compose(
-      this.options.extraOverlayPath === undefined
-        ? loadPersonalPatches('dsh') ?? []
-        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
-    )
-    this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
-      await this.options.prepare?.(ctx)
-      // Config-only HMR for the personal overlay: module reload stays off for
-      // this surface (web.cordis.yml disables the shared `hmr` row until its
-      // reload lifecycle is tested), so this row watches no module roots.
-      if (watchPersonal) await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
-      if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
-    })
-    if (watchPersonal) {
-      await watchPersonalPatches(this.ctx, { binName: 'dsh', compose })
-    }
-  }
-
-  /** Install the diagnostic for plugin rejections that happen after settled boot. */
-  private assertBoot(): void {
-    installFailLoud('dsh')
-  }
-
-  /**
-   * Bypass parse of the base and this surface's overlay (id → row) for
-   * patch-merge inputs; the Loader still reads both files itself. The overlay
-   * wins per row, matching the order its patches are applied in, and its
-   * `insert` rows are indexed too because a flag may target one of them.
-   */
-  private parseYmlRows(): Map<string, { config?: unknown }> {
-    const rows = new Map<string, { config?: unknown }>()
-    const files = [this.options.configPath, this.options.overlayPath]
-    if (this.options.extraOverlayPath !== undefined) files.push(this.options.extraOverlayPath)
-    for (const file of files) {
-      for (const row of this.parseRowList(file)) {
-        if (typeof row.id === 'string') rows.set(row.id, row)
-        for (const inserted of row.insert ?? []) {
-          if (typeof inserted.id === 'string') rows.set(inserted.id, inserted)
-        }
-      }
-    }
-    return rows
-  }
-
-  /**
-   * Parse one entry or patch list, rejecting anything that is not a top-level
-   * array so a malformed file fails here rather than at row lookup.
-   * @param file - absolute path of the config or overlay file.
-   * @returns the parsed top-level entries.
-   */
-  private parseRowList(file: string): { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[] {
-    const doc = yaml.load(readFileSync(file, 'utf8'), { schema: includeYamlSchema })
-    if (!Array.isArray(doc)) throw new Error(`dsh: ${file} is not a top-level entry list`)
-    return doc as { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[]
-  }
-
-  /** Profile json under cwd; read-only — never created here, absent = no user config. */
-  private readProfile(): Record<string, unknown> {
-    let raw: string
-    try {
-      raw = readFileSync(join(process.cwd(), PROFILE_DIR, PROFILE_FILE), 'utf8')
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {}
-      throw error
-    }
-    const parsed: unknown = JSON.parse(raw)
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      throw new Error(`dsh: ${PROFILE_DIR}/${PROFILE_FILE} must hold a JSON object`)
-    }
-    return parsed as Record<string, unknown>
-  }
-
-  /** Dist location is workspace knowledge of this app: resolved through the frontend package exports, not configured. */
-  private resolveDistIndex(): string {
-    const require = createRequire(import.meta.url)
-    try {
-      return require.resolve('@deepseek-ai/dsh-frontend/dist/index.html')
-    } catch {
-      throw new Error('dsh: frontend dist not built; run pnpm run build from the repository root first')
-    }
-  }
-}

apps/cli/src/args.ts

@@ -1,43 +1,42 @@
 /**
  * Commander adapter for the `dsh` command-line entry. The default command
- * boots one required `--config` overlay over the shipped base; `-p` selects
- * the one-shot headless path and `web` selects the browser application.
- * Commander owns help, version, and parse errors.
+ * boots a named profile (`--profile <name>`), optionally with extra `--patch`
+ * overlays and a positional task (one-shot mode for profiles mounting the
+ * headless runner). `web` is a hardcoded alias for `--profile web` that adds
+ * the Web flag family; `plugin` manages a profile's plugin dependencies by
+ * forwarding to pnpm. Commander owns help, version, and parse errors.
  * @module @deepseek-ai/dsh/args
  */
 
 import { Command, CommanderError } from 'commander'
 
-/** Boot a caller-selected overlay over the shipped base config. */
-interface ConfigInvocation {
-  mode: 'config'
-  config: string
+/** Boot a named profile. */
+interface ProfileInvocation {
+  mode: 'profile'
+  profile: string
+  /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
+  patches: string[]
+  /** Positional task text joined by spaces; non-empty only for one-shot runs. */
+  task?: string
 }
 
-/** Print a composed config tree and exit without booting. */
+/** Print a composed profile tree and exit without booting. */
 interface DumpConfigInvocation {
   mode: 'dump-config'
-  surface: 'config' | 'web'
-  /** Omit every caller or personal layer and print the shipped tree. */
+  profile: string
+  /** Omit the profile's user layer and --patch overlays; print bundle layers only. */
   defaultOnly: boolean
-  /** Explicit overlay to compose over the base or Web surface. */
-  config?: string
-}
-
-/** Headless one-shot: `dsh -p "task"`. */
-interface HeadlessInvocation {
-  mode: 'headless'
-  prompt: string
+  patches: string[]
 }
 
 /**
- * Browser UI: `dsh web`. Host and port remain unvalidated pass-throughs to
- * the webserver schema; absent values leave the shipped Web overlay intact.
+ * Browser UI: `dsh web` (alias of `--profile web`). Host and port remain
+ * unvalidated pass-throughs to the webserver schema; absent values leave the
+ * shipped web bundle values intact.
  */
 interface WebInvocation {
   mode: 'web'
-  /** Overlay applied over the shipped Web composition instead of the personal one. */
-  config?: string
+  patches: string[]
   host?: string
   port?: number
   dev: boolean
@@ -46,12 +45,20 @@ interface WebInvocation {
   trustedHosts?: string[]
 }
 
+/** Manage a profile's plugins: forward `args` to pnpm inside the profile directory. */
+interface PluginInvocation {
+  mode: 'plugin'
+  profile: string
+  /** Raw pnpm arguments, verbatim. */
+  args: string[]
+}
+
 /** The resolved `dsh` invocation. Help, version, and errors exit inside {@link parseDshArgs}. */
-export type DshInvocation = ConfigInvocation | DumpConfigInvocation | HeadlessInvocation | WebInvocation
+export type DshInvocation = ProfileInvocation | DumpConfigInvocation | WebInvocation | PluginInvocation
 
 /** Raw web-subcommand options straight from Commander. */
 interface WebOptions {
-  config?: string
+  patch?: string[]
   host?: string
   port?: string
   dev?: boolean
@@ -61,43 +68,11 @@ interface WebOptions {
   dumpDefaultConfig?: boolean
 }
 
-/** Resolve config-dump flags for one command shape. */
-function resolveDump(
-  surface: 'config' | 'web',
-  options: { config?: string; dumpConfig?: boolean; dumpDefaultConfig?: boolean },
-  error: (message: string) => never,
-): DumpConfigInvocation | undefined {
-  if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) return undefined
-  if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
-    error('error: --dump-config and --dump-default-config are mutually exclusive')
-  }
-  const defaultOnly = options.dumpDefaultConfig === true
-  if (defaultOnly && options.config !== undefined) {
-    error('error: --dump-default-config prints the shipped tree and takes no --config')
-  }
-  if (surface === 'config' && !defaultOnly && options.config === undefined) {
-    error('error: --dump-config requires --config <path>')
-  }
-  return {
-    mode: 'dump-config',
-    surface,
-    defaultOnly,
-    ...options.config !== undefined && { config: options.config },
-  }
-}
-
-/** Narrow raw `web` options into a {@link WebInvocation}. */
-function resolveWeb(options: WebOptions): WebInvocation {
-  return {
-    mode: 'web',
-    ...options.config !== undefined && { config: options.config },
-    ...options.host !== undefined && { host: options.host },
-    ...options.port !== undefined && { port: Number(options.port) },
-    dev: options.dev === true,
-    ...options.workspaceRoot !== undefined && { workspaceRoot: options.workspaceRoot },
-    ...options.trustedHost !== undefined && { trustedHosts: options.trustedHost },
-  }
-}
+/**
+ * Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
+ * variadic — a variadic `--patch` would swallow a following positional task.
+ */
+const collect = (value: string, previous: string[] = []): string[] => [...previous, value]
 
 /**
  * Resolve argv into one invocation, or print and exit for help, version, or an
@@ -111,77 +86,122 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
   const program = new Command()
     .name('dsh')
     .version(version, '-V, --version', 'output the version number')
-    .description('dsh: boot a DeepSeek Harness config overlay over the shipped base configuration.')
+    .description('dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle patch layers under your own overrides.')
     .addHelpText('after', `
 Examples:
-  dsh --config ./app.cordis.yml  boot an overlay over the shipped base
-  dsh -p "run the tests"         answer one task, print the result, and exit
-  dsh web                       serve the browser UI
+  dsh --profile web                          boot the web profile (same as: dsh web)
+  dsh --profile headless "run the tests"     answer one task, print the result, and exit
+  dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
+  dsh plugin --profile tui add <package>     install a plugin into the tui profile
+  dsh web --port 8080                        the web alias with its flag family
 `)
     .exitOverride()
     .enablePositionalOptions()
-    .option('-p, --prompt <task>', 'answer this task without an interactive UI, then exit')
-    .option('--config <path>', 'overlay of loader patches to apply over the shipped base')
-    .option('--dump-config', 'print the base plus --config overlay and exit')
-    .option('--dump-default-config', 'print the shipped base config and exit')
-    .action((options: {
-      config?: string
-      prompt?: string
+    .argument('[task...]', 'one-shot task text for profiles mounting the headless runner')
+    .option('--profile <name>', 'the profile under $DSH_HOME/profiles to boot')
+    .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
+    .option('--dump-config', 'print the composed profile tree and exit')
+    .option('--dump-default-config', 'print the profile tree without its user layer or --patch overlays and exit')
+    .action((task: string[], options: {
+      profile?: string
+      patch?: string[]
       dumpConfig?: boolean
       dumpDefaultConfig?: boolean
     }) => {
-      if (options.config === '') program.error('error: --config needs a path')
-      const dump = resolveDump('config', options, message => program.error(message))
-      if (dump !== undefined) {
-        if (options.prompt !== undefined) {
-          program.error('error: --dump-config/--dump-default-config take no -p/--prompt')
+      const profile = options.profile ?? program.error('error: --profile <name> is required')
+      if (profile === '') program.error('error: --profile needs a name')
+      const patches = options.patch ?? []
+      if (patches.includes('')) program.error('error: --patch needs a path')
+      if (options.dumpConfig === true || options.dumpDefaultConfig === true) {
+        if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
+          program.error('error: --dump-config and --dump-default-config are mutually exclusive')
+        }
+        if (task.length > 0) program.error('error: --dump-config/--dump-default-config take no task')
+        const defaultOnly = options.dumpDefaultConfig === true
+        if (defaultOnly && patches.length > 0) {
+          program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
         }
-        resolved = dump
+        resolved = { mode: 'dump-config', profile, defaultOnly, patches }
         return
       }
-      if (options.prompt !== undefined) {
-        if (options.prompt === '') program.error('error: --prompt needs a task')
-        if (options.config !== undefined) program.error('error: --prompt takes no --config')
-        resolved = { mode: 'headless', prompt: options.prompt }
-        return
+      resolved = {
+        mode: 'profile',
+        profile,
+        patches,
+        ...task.length > 0 ? { task: task.join(' ') } : {},
       }
-      const config = options.config ?? program.error('error: --config <path> is required')
-      resolved = { mode: 'config', config }
     })
 
   /** Reject parent options that crossed a subcommand boundary. */
   const rejectParentOptions = (command: string): void => {
     const parent = program.opts<{
-      config?: string
-      prompt?: string
+      profile?: string
+      patch?: string[]
       dumpConfig?: boolean
       dumpDefaultConfig?: boolean
     }>()
-    if (parent.config !== undefined || parent.prompt !== undefined
+    if (parent.profile !== undefined || parent.patch !== undefined
       || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
-      program.error(`error: ${command} takes none of parent --config, -p/--prompt, --dump-config, or --dump-default-config`)
+      program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`)
     }
   }
 
-  const web = program.command('web').description('serve the browser UI on the configured host and port')
+  const web = program.command('web').description('serve the browser UI (alias of --profile web) on the configured host and port')
   web
-    .option('--config <path>', 'apply this overlay of loader patches over the shipped Web configuration')
+    .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
     .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
     .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
     .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
     .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
     .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
-    .option('--dump-config', 'print the composed config tree (base + web + --config/personal overlay) and exit')
-    .option('--dump-default-config', 'print the shipped config tree (base + web overlay, no user layer) and exit')
+    .option('--dump-config', 'print the composed web-profile tree (with the user layer and any --patch) and exit')
+    .option('--dump-default-config', 'print the web profile\'s bundle layers (no user layer) and exit')
     .action((options: WebOptions) => {
       rejectParentOptions('web')
-      if (options.config === '') program.error('error: --config needs a path')
-      const dump = resolveDump('web', options, message => program.error(message))
-      if (dump !== undefined) {
-        resolved = dump
+      const patches = options.patch ?? []
+      if (patches.includes('')) program.error('error: --patch needs a path')
+      if (options.dumpConfig === true || options.dumpDefaultConfig === true) {
+        if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
+          program.error('error: --dump-config and --dump-default-config are mutually exclusive')
+        }
+        const defaultOnly = options.dumpDefaultConfig === true
+        if (defaultOnly && patches.length > 0) {
+          program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
+        }
+        // The dump is boot-free and does not derive flag patches; silently
+        // dropping them would print a tree that differs from the same
+        // invocation's boot.
+        if (options.host !== undefined || options.port !== undefined || options.dev === true
+          || options.workspaceRoot !== undefined || options.trustedHost !== undefined) {
+          program.error('error: config dumps take no web flags (--host/--port/--dev/--workspace-root/--trusted-host)')
+        }
+        resolved = { mode: 'dump-config', profile: 'web', defaultOnly, patches }
         return
       }
-      resolved = resolveWeb(options)
+      if (options.port !== undefined && !/^\d+$/.test(options.port)) {
+        program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`)
+      }
+      resolved = {
+        mode: 'web',
+        patches,
+        ...options.host !== undefined && { host: options.host },
+        ...options.port !== undefined && { port: Number(options.port) },
+        dev: options.dev === true,
+        ...options.workspaceRoot !== undefined && { workspaceRoot: options.workspaceRoot },
+        ...options.trustedHost !== undefined && { trustedHosts: options.trustedHost },
+      }
+    })
+
+  const plugin = program.command('plugin').description('manage a profile\'s plugins by forwarding the remaining arguments to pnpm in the profile directory')
+  plugin
+    .requiredOption('--profile <name>', 'the profile whose plugins to manage (initialized on first use)')
+    .allowUnknownOption()
+    .argument('[args...]', 'pnpm arguments, forwarded verbatim (add <pkg>, remove <pkg>, why <pkg>, ...)')
+    .action((args: string[], options: { profile: string }) => {
+      rejectParentOptions('plugin')
+      if (options.profile === '') program.error('error: --profile needs a name')
+      if (args.length === 0) program.error('error: plugin needs pnpm arguments to forward (e.g. add <package>)')
+      resolved = { mode: 'plugin', profile: options.profile, args }
     })
 
   try {

apps/cli/src/bin.ts

@@ -28,24 +28,28 @@ loadEnv('dsh')
 const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 
 switch (invocation.mode) {
-  case 'config': {
-    const { runConfig } = await import('./config.ts')
-    await runConfig(invocation.config)
+  case 'profile': {
+    const { runProfile } = await import('./profile-boot.ts')
+    await runProfile({
+      profile: invocation.profile,
+      patchFiles: invocation.patches,
+      ...invocation.task !== undefined && { task: invocation.task },
+    })
     break
   }
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
+    await runWeb(invocation)
     break
   }
-  case 'headless': {
-    const { runHeadless } = await import('./headless.ts')
-    await runHeadless(invocation.prompt)
+  case 'plugin': {
+    const { runPlugin } = await import('./plugin.ts')
+    process.exit(runPlugin(invocation.profile, invocation.args))
     break
   }
   case 'dump-config': {
     const { runDumpConfig } = await import('./dump-config.ts')
-    runDumpConfig(invocation.surface, invocation.defaultOnly, invocation.config)
+    runDumpConfig(invocation.profile, invocation.defaultOnly, invocation.patches)
     break
   }
   default:

apps/cli/src/config.ts

@@ -1,54 +0,0 @@
-/**
- * Raw `dsh --config <path>` boot: apply one required patch-list overlay over
- * the shipped base config, then leave process lifetime to the mounted plugins.
- * @module @deepseek-ai/dsh/config
- */
-
-import { fileURLToPath } from 'node:url'
-import type { Context } from 'cordis'
-import {
-  boot,
-  installFailLoud,
-  loadOverlayPatches,
-  resolveConfigPath,
-} from '@deepseek-ai/dsh-app-boot'
-import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
-
-const NAME = 'dsh'
-const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
-
-/* v8 ignore start -- the source-launch and built-bin acceptance paths own executable dispatch */
-/**
- * Boot the shipped base with one explicit overlay.
- * @param config - required patch-list path parsed from `--config`.
- */
-export async function runConfig(config: string): Promise<void> {
-  const app: { current?: Context } = {}
-  let exiting = false
-  const shutdown = (code: number): void => {
-    if (exiting) return
-    exiting = true
-    void Promise.resolve(app.current?.fiber.dispose()).finally(() => { process.exit(code) })
-  }
-  // An inserted front door can publish readiness before sibling rows finish
-  // mounting. Signals must own teardown throughout that startup window, not
-  // only after boot() settles.
-  process.on('SIGTERM', () => { shutdown(0) })
-  process.on('SIGINT', () => { shutdown(130) })
-  installFailLoud(NAME, process, async () => {
-    await app.current?.fiber.dispose()
-  })
-  const overlay = resolveConfigPath(config, undefined)
-  const telemetryPatch = resolveTelemetryPatch(
-    process.env.DSH_TELEMETRY_DISABLED,
-    configHasTelemetryRow(BASE_CONFIG),
-  )
-  const ctx = await boot(NAME, BASE_CONFIG, [
-    ...loadOverlayPatches(NAME, overlay),
-    ...telemetryPatch === undefined ? [] : [telemetryPatch],
-  ], (hostCtx) => {
-    app.current = hostCtx
-  })
-  app.current = ctx
-}
-/* v8 ignore stop */

apps/cli/src/dump-config.ts

@@ -1,52 +1,53 @@
 /**
- * Config-dump entry for raw `dsh --config` and `dsh web`: compose through the
- * include plugin's patch algorithm without booting or evaluating `!!js`.
+ * Config-dump entry for `dsh --profile <name> --dump-config`: compose the
+ * profile's patch layers through the include plugin's patch algorithm without
+ * booting or evaluating `!!js`, with one provenance layer per bundle, the
+ * profile's own patch file, and each `--patch` overlay.
  * @module @deepseek-ai/dsh/dump-config
  */
 
-import { basename, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
 import {
+  loadOptionalPatches,
   loadOverlayPatches,
-  loadPersonalPatches,
-  PERSONAL_CONFIG_FILENAME,
   renderConfigDump,
   type ConfigDumpLayer,
 } from '@deepseek-ai/dsh-app-boot'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { homePatchPath, prepareProfile, PROFILE_ROOT_FILENAME } from './profile-boot.ts'
 
 const NAME = 'dsh'
-const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
-const WEB_OVERLAY = fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url))
 
 /* v8 ignore start -- built-bin acceptance drives this boot-free dispatch */
 /**
- * Print a raw or Web composition with provenance comments.
- * @param surface - raw base-plus-config composition, or the Web composition.
- * @param defaultOnly - omit the explicit or personal user layer.
- * @param config - explicit overlay path; required for a non-default raw dump.
+ * Print a profile composition with provenance comments.
+ * @param profile - the profile name.
+ * @param defaultOnly - omit the profile's user layer and `--patch` overlays
+ * (the recovery diagnostic for a broken `cordis.patch.yml`, which is then
+ * never parsed).
+ * @param patches - `--patch` overlay paths, in argv order.
  */
-export function runDumpConfig(surface: 'config' | 'web', defaultOnly: boolean, config?: string): void {
-  const layers: ConfigDumpLayer[] = []
-  if (surface === 'config') {
-    if (!defaultOnly) {
-      /* v8 ignore next -- parseDshArgs requires this combination */
-      if (config === undefined) throw new Error('dsh: raw config dump requires an overlay')
-      layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
+export function runDumpConfig(profile: string, defaultOnly: boolean, patches: readonly string[]): void {
+  const loaded = prepareProfile(profile, !defaultOnly)
+  const layers: ConfigDumpLayer[] = loaded.layers.map(layer => ({
+    label: layer.packageName,
+    patches: layer.patches,
+  }))
+  if (!defaultOnly) {
+    if (existsSync(loaded.patchPath)) {
+      layers.push({ label: loaded.patchPath, patches: loaded.patches })
     }
-  } else {
-    layers.push({ label: basename(WEB_OVERLAY), patches: loadOverlayPatches(NAME, WEB_OVERLAY) })
-    if (!defaultOnly) {
-      if (config === undefined) {
-        const personal = loadPersonalPatches(NAME)
-        if (personal !== undefined) {
-          layers.push({ label: join(resolveDshHome(), PERSONAL_CONFIG_FILENAME), patches: personal })
-        }
-      } else {
-        layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
-      }
+    const homePatchFile = homePatchPath()
+    const homePatches = loadOptionalPatches(NAME, homePatchFile)
+    if (homePatches !== undefined) {
+      layers.push({ label: homePatchFile, patches: homePatches })
+    }
+    for (const file of patches) {
+      const absolute = resolve(file)
+      layers.push({ label: absolute, patches: loadOverlayPatches(NAME, absolute) })
     }
   }
-  process.stdout.write(renderConfigDump(NAME, BASE_CONFIG, layers))
+  // The dump anchors on the same empty root file the boot includes.
+  process.stdout.write(renderConfigDump(NAME, join(loaded.dir, PROFILE_ROOT_FILENAME), layers))
 }
 /* v8 ignore stop */

apps/cli/src/headless.ts

@@ -1,130 +0,0 @@
-/**
- * `dsh -p "task"` — headless over the one shared composition: AppCLIEntry
- * boots the same base plus Web overlay as `dsh web` (port 0, so parallel runs never
- * collide), then in-process isomorphic injection (InProcessApiClient over
- * toFetchHandler(ctx.apiProxy), so the full carrier chain — wire
- * serialization, zod, SSE framing — really runs). The printed URL opens the
- * live session in a browser while the task runs. Runs one task turn, prints
- * the final assistant text, exits (completed → 0, else 1).
- */
-
-import { fileURLToPath } from 'node:url'
-import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
-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'
-import { AppCLIEntry } from './app-cli-entry.ts'
-import { createProcessShutdown } from './process-shutdown.ts'
-
-/** Outcome of one headless turn: aggregated final text plus the turn-end reason kind. */
-interface TurnOutcome {
-  text: string
-  reason: string
-}
-
-/** Unwrap an RpcResponse or fail loud: business errors print and exit 1 (shutdown first). */
-async function unwrap<T>(response: RpcResponse<T>, shutdown: () => Promise<void>): Promise<T> {
-  if (response.result.ok) return response.result.value
-  const { code, message } = response.result.error
-  process.stderr.write(`dsh: ${code}: ${message}\n`)
-  await shutdown()
-  process.exit(1)
-}
-
-/**
- * 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.
- * @returns the aggregated outcome.
- */
-async function consumeUntilIdle(
-  frames: AsyncIterable<RpcRequest<MuxFrame>>,
-  sessionId: SessionId,
-  idle: Promise<void>,
-): 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) {
-      process.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
-    }
-  })()
-  await idle
-  return { text, reason }
-}
-
-/**
- * Run one headless turn for `task` and exit (completed → 0, else 1). The task
- * is the non-empty prompt the argument adapter parsed from `-p`/`--prompt`
- * (the adapter rejects an empty task, so no guard is needed here).
- * @param task - the prompt text for the single turn.
- */
-export async function runHeadless(task: string): Promise<void> {
-  // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
-  const entry = new AppCLIEntry({
-    configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
-    overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
-    dev: false,
-    watchPersonalConfig: false,
-    port: 0,
-  })
-  const { ctx, port } = await entry.run()
-  // Normal completion and signals share one bounded drain. A signal received
-  // during that drain escalates immediately instead of becoming a no-op.
-  const shutdown = createProcessShutdown(async () => { await ctx.fiber.dispose() })
-  process.on('SIGTERM', () => { shutdown.interrupt(143) })
-  process.on('SIGINT', () => { shutdown.interrupt(130) })
-  // The headless session is web-observable while it runs (same composition).
-  process.stderr.write(`dsh: observing at http://127.0.0.1:${String(port)}\n`)
-  const api = new InProcessApiClient(toFetchHandler(ctx.apiProxy))
-
-  const created = await unwrap(await api.sessions.create({}), () => shutdown.shutdown(1))
-
-  // Open the stream before prompting so no frame is lost — kept in this order
-  // even though in-process delivery has no race, so the code survives a move
-  // to a remote HTTP carrier unchanged.
-  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)
-
-  await unwrap(await api.sessions.prompt({
-    sessionId: created.sessionId,
-    mode: 'queue',
-    content: [{ type: 'text', text: task }],
-  }), () => shutdown.shutdown(1))
-
-  const outcome = await done
-  process.stdout.write(outcome.text + '\n')
-  abort.abort()
-  await shutdown.shutdown(outcome.reason === 'completed' ? 0 : 1)
-}

apps/cli/src/plugin.ts

@@ -0,0 +1,158 @@
+/**
+ * `dsh plugin --profile <name> <args...>` — profile plugin management as a
+ * thin pnpm forwarder: initialize the profile on first use, run
+ * `pnpm <args...>` in the profile directory, then reconcile the
+ * `dsh.profile.bundles` layer list against the installed state (a dependency
+ * resolving to a package that declares `dsh.bundle` joins the layer stack; a
+ * removed or bundle-less dependency leaves it). Reconciling by installed
+ * state, not by dependency diff, means `update` activates a package that
+ * gained its `dsh.bundle` declaration in a newer version.
+ * @module @deepseek-ai/dsh/plugin
+ */
+
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import {
+  DEFAULT_PROFILE_BUNDLES,
+  initProfile,
+  PROFILE_TEMPLATES,
+  readProfileManifest,
+  resolveBundleDir,
+  resolveProfileDir,
+  writeProfileManifest,
+  type ProfileManifest,
+} from '@deepseek-ai/dsh-app-boot'
+import { INSTALL_ANCHOR } from './profile-boot.ts'
+
+const NAME = 'dsh'
+
+/**
+ * Whether a resolved dependency exports a profile patch, i.e. is a bundle.
+ * @param packageName - the dependency's package name.
+ * @param profileDir - the profile directory (resolution anchor).
+ * @returns true when the package manifest declares `dsh.bundle`.
+ */
+function exportsPatch(packageName: string, profileDir: string): boolean {
+  let dir: string
+  try {
+    dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir)
+  } catch {
+    return false // pnpm reported success yet the package is unresolvable — treat as plain
+  }
+  const manifest = readProfileManifest(NAME, dir)
+  return manifest.dsh?.bundle?.patch !== undefined
+}
+
+/**
+ * Reconcile `dsh.profile.bundles` against the installed state: pnpm has
+ * already written the real installed names (so a git/path/tarball/alias spec
+ * on the command line reconciles by its true package name) and materialized
+ * the packages. A dependency that resolves to a `dsh.bundle`-declaring
+ * package joins the layer stack (appended in dependency order); a
+ * dependency-listed name that no longer does — removed, or the installed
+ * version dropped the declaration — leaves it. In-box bundles from the
+ * profile template are not dependencies and are never touched. Warns once
+ * per newly-added bundle-less dependency (a plain library is fine; the
+ * warning is orientation).
+ */
+function reconcilePlugins(before: ProfileManifest, profileDir: string): void {
+  const after = readProfileManifest(NAME, profileDir)
+  const beforeDeps = new Set(Object.keys(before.dependencies ?? {}))
+  const dependencies = Object.keys(after.dependencies ?? {})
+  const plugins = after.dsh?.profile?.bundles ?? []
+  let changed = false
+  for (const packageName of dependencies) {
+    const isBundle = exportsPatch(packageName, profileDir)
+    if (isBundle && !plugins.includes(packageName)) {
+      plugins.push(packageName)
+      changed = true
+    } else if (!isBundle && !beforeDeps.has(packageName)) {
+      process.stderr.write(
+        `${NAME}: warning: ${packageName} declares no dsh.bundle — installed as a plain dependency, not a profile layer `
+        + '(a later update that gains one activates it automatically)\n',
+      )
+    }
+  }
+  const dependencySet = new Set(dependencies)
+  for (const packageName of [...plugins]) {
+    // Only dependency-managed entries are subject to removal; template
+    // bundles (dsh-base and friends) are not dependencies.
+    const wasDependency = beforeDeps.has(packageName) || dependencySet.has(packageName)
+    const stillBundle = dependencySet.has(packageName) && exportsPatch(packageName, profileDir)
+    if (wasDependency && !stillBundle) {
+      plugins.splice(plugins.indexOf(packageName), 1)
+      changed = true
+    }
+  }
+  if (!changed) return
+  after.dsh = { ...after.dsh, profile: { ...after.dsh?.profile, bundles: plugins } }
+  writeProfileManifest(profileDir, after)
+}
+
+/**
+ * Rewrite relative filesystem specs against the user's invoking directory.
+ * pnpm runs with cwd = the profile directory, so a bare `.` or `../plugin`
+ * (or their `file:`/`link:` forms) would silently resolve inside the profile
+ * — `add .` from a plugin checkout would self-link the profile. Absolute
+ * specs, registry names, and every other pnpm argument pass through
+ * untouched.
+ * @param argument - one pnpm argument, verbatim from argv.
+ * @param cwd - the directory `dsh` was invoked from.
+ * @returns the argument with a relative path spec anchored to `cwd`.
+ */
+function anchorPathSpec(argument: string, cwd: string): string {
+  const match = /^(?<prefix>(?:file|link):)?(?<path>\.{1,2}(?:[/\\].*)?)$/.exec(argument)
+  if (match?.groups?.path === undefined) return argument
+  // A bare path stays bare and a prefixed spec keeps its prefix: pnpm's
+  // link-vs-copy semantics differ between `file:` and a plain directory
+  // path, and the anchor must not change which one the user asked for.
+  const prefix = match.groups.prefix ?? ''
+  return `${prefix}${resolve(cwd, match.groups.path)}`
+}
+
+/**
+ * Run one `dsh plugin` invocation: init if needed, forward to pnpm, reconcile.
+ * @param profile - the profile name.
+ * @param args - pnpm arguments with relative path specs anchored to the invoking directory.
+ * @returns the pnpm exit code.
+ */
+export function runPlugin(profile: string, args: readonly string[]): number {
+  const dir = resolveProfileDir(profile)
+  if (!existsSync(join(dir, 'package.json'))) {
+    initProfile(dir, PROFILE_TEMPLATES[profile] ?? DEFAULT_PROFILE_BUNDLES)
+    process.stderr.write(`${NAME}: initialized profile ${profile} at ${dir}\n`)
+  }
+  const before = readProfileManifest(NAME, dir)
+  // Windows resolves pnpm through its .cmd shim, which spawn() refuses
+  // without a shell since the CVE-2024-27980 hardening.
+  const result = spawnSync('pnpm', args.map(argument => anchorPathSpec(argument, process.cwd())), {
+    cwd: dir,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+  })
+  if (result.error !== undefined) {
+    const code = (result.error as NodeJS.ErrnoException).code
+    if (code === 'ENOENT') {
+      process.stderr.write(`${NAME}: pnpm not found on PATH — install pnpm to manage profile plugins\n`)
+      return 127
+    }
+    throw result.error
+  }
+  const exitCode = result.status ?? 1
+  if (exitCode === 0) {
+    reconcilePlugins(before, dir)
+  } else {
+    // pnpm's own diagnostics name pnpm-workspace.yaml without saying WHICH
+    // one; the profile owns it, and the commonest failure here is pnpm ≥10
+    // blocking a git dependency's prepare (build) script until allowlisted.
+    process.stderr.write(`${NAME}: pnpm failed in profile directory ${dir}\n`)
+    if (args.some(argument => /^git\+|^github:|\.git(?:#|$)/.test(argument))) {
+      process.stderr.write(
+        `${NAME}: git-hosted plugins build on install via their prepare script, which pnpm blocks until allowed — `
+        + `add the exact key pnpm printed above under allowBuilds in ${join(dir, 'pnpm-workspace.yaml')}, then re-run\n`,
+      )
+    }
+  }
+  return exitCode
+}

apps/cli/src/profile-boot.ts

@@ -0,0 +1,266 @@
+/**
+ * Shared profile boot for every `dsh` surface: resolve the profile, stack its
+ * patch layers (bundle layers in `dsh.profile.bundles` order, the profile's own
+ * `cordis.patch.yml`, `--patch` overlays, flag-derived patches, the telemetry
+ * switch), mount the tree over the profile's empty root config, keep the
+ * profile patch layer live, and wire fail-loud plus bounded shutdown.
+ * @module @deepseek-ai/dsh/profile-boot
+ */
+
+import { writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from 'cordis'
+import type { PatchOptions } from '@cordisjs/plugin-include'
+import {
+  boot,
+  composeEntries,
+  healProfilesModuleFallback,
+  installFailLoud,
+  loadOptionalPatches,
+  loadOverlayPatches,
+  loadProfile,
+  PROFILE_PATCH_FILENAME,
+  watchUserPatches,
+  type Profile,
+} from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import type { HeadlessIo } from '@deepseek-ai/dsh-headless'
+import { createProcessShutdown, type ProcessShutdown } from './process-shutdown.ts'
+
+const NAME = 'dsh'
+
+/**
+ * The home-level user patch layer (`$DSH_HOME/cordis.patch.yml`), applied
+ * over every profile's own layer. Resolved per call, not at module load:
+ * `$DSH_HOME` may be set by the test or launcher after import.
+ * @returns the absolute patch-file path.
+ */
+export function homePatchPath(): string {
+  return join(resolveDshHome(), PROFILE_PATCH_FILENAME)
+}
+
+/** Absolute path of this dsh installation's package.json (both anchors: src/ and lib/ sit one level under apps/cli). */
+export const INSTALL_ANCHOR = fileURLToPath(new URL('../package.json', import.meta.url))
+
+/** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets. */
+const TELEMETRY_ROW_ID = 'telemetry-otel'
+
+/** The one-shot runner row a positional task requires and configures. */
+const HEADLESS_ROW_ID = 'headless-runner'
+
+/** The empty root entry list every profile tree patches over. */
+const PROFILE_ROOT_CONFIG = `# dsh profile root — an empty entry list. The tree is composed as patches:
+# each bundle in package.json's dsh.profile.bundles, then cordis.patch.yml, then any
+# --patch overlays. Edit cordis.patch.yml, not this file.
+[]
+`
+
+/** Root config filename inside a profile directory. */
+export const PROFILE_ROOT_FILENAME = 'cordis.yml'
+
+/**
+ * Resolve the telemetry opt-out switch into its boot patch. ANY non-empty
+ * value (including `'0'`/`'false'`) disables: a privacy switch prefers
+ * off-by-mistake over on-by-mistake. A composition without the telemetry row
+ * exports nothing, so the switch is then trivially satisfied and no patch is
+ * generated — custom profiles need not mount telemetry to run with the
+ * switch set.
+ * @param disabledEnv - the raw `DSH_TELEMETRY_DISABLED` value (`undefined` when unset).
+ * @param hasRow - whether the composition carries the telemetry row.
+ * @returns the disable patch, or `undefined` when telemetry stays enabled or is not mounted.
+ */
+export function resolveTelemetryPatch(disabledEnv: string | undefined, hasRow: boolean): PatchOptions | undefined {
+  if ((disabledEnv ?? '') === '' || !hasRow) return undefined
+  return { id: TELEMETRY_ROW_ID, disabled: true }
+}
+
+/**
+ * Load a resolved profile for `name`: heal the shared module fallback, then
+ * (re)write the empty root config. The root is always rewritten: the whole
+ * composition is patch layers, and the vendored Loader's tree write-back (a
+ * plugin self-disposing persists the current tree) can bake composed rows
+ * into this file — which would duplicate every bundle insert on the next
+ * boot. The file exists on disk only because the Loader needs a real include
+ * root to anchor `baseUrl` at the profile directory (the config dump anchors
+ * on the same file, so both compose over the identical base).
+ * @param name - the profile name.
+ * @param userLayer - `false` skips parsing `cordis.patch.yml` (the default dump).
+ * @returns the loaded profile.
+ */
+export function prepareProfile(name: string, userLayer = true): Profile {
+  healProfilesModuleFallback(INSTALL_ANCHOR)
+  const profile = loadProfile(NAME, name, INSTALL_ANCHOR, undefined, { userLayer })
+  writeFileSync(join(profile.dir, PROFILE_ROOT_FILENAME), PROFILE_ROOT_CONFIG)
+  return profile
+}
+
+/** One profile's patch layers (application order) and the row index of its pre-flag composition. */
+interface ComposedProfile {
+  profile: Profile
+  /** Bundle layers concatenated — the part below the user layers on a live reload. */
+  bundlePatches: PatchOptions[]
+  /** The home-level user layer (`$DSH_HOME/cordis.patch.yml`), applied after the profile's own. */
+  homePatches: PatchOptions[]
+  /** Layers above the user layers on a live reload: --patch overlays, flag patches, the telemetry switch. */
+  overlayAndFlags: PatchOptions[]
+  /**
+   * id → row of the pre-flag composition (bundles + user layers + overlays),
+   * for flag merges and row checks. Flag patches must not insert rows the
+   * launcher consults here (they only override values and insert dev glue).
+   */
+  rows: Map<string, { name?: string; config?: unknown }>
+}
+
+/** The full patch stack of one composed profile, in application order. */
+function allPatches(composed: ComposedProfile): PatchOptions[] {
+  return [...composed.bundlePatches, ...composed.profile.patches, ...composed.homePatches, ...composed.overlayAndFlags]
+}
+
+/**
+ * Load `name` and compose its effective patch stack: bundle layers in
+ * `dsh.profile.bundles` order, the profile's user layer, the home-level user layer
+ * (`$DSH_HOME/cordis.patch.yml` — machine-local preferences that apply to
+ * every profile, so it outranks the per-profile layer), `--patch` overlays,
+ * then flag patches derived from the composed rows, then the telemetry
+ * switch.
+ * @param name - the profile name.
+ * @param patchFiles - `--patch` overlay paths, in argv order.
+ * @param deriveFlagPatches - launcher hook turning composed rows into flag patches.
+ * @returns the profile, its patch layers, and the composed row index.
+ */
+function composeProfile(
+  name: string,
+  patchFiles: readonly string[],
+  deriveFlagPatches: (rows: ComposedProfile['rows']) => PatchOptions[] = () => [],
+): ComposedProfile {
+  const profile = prepareProfile(name)
+  const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? []
+  const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)))
+  const bundlePatches = profile.layers.flatMap(layer => layer.patches)
+  const rows = new Map<string, { name?: string; config?: unknown }>()
+  for (const row of composeEntries([bundlePatches, profile.patches, homePatches, overlays])) {
+    if (typeof row.id === 'string') rows.set(row.id, row)
+  }
+  const overlayAndFlags = [...overlays, ...deriveFlagPatches(rows)]
+  const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID))
+  if (telemetryPatch !== undefined) overlayAndFlags.push(telemetryPatch)
+  return { profile, bundlePatches, homePatches, overlayAndFlags, rows }
+}
+
+/** Options for {@link runProfile}. */
+export interface RunProfileOptions {
+  /** The profile name to boot. */
+  profile: string
+  /** `--patch` overlay paths, in argv order. */
+  patchFiles: readonly string[]
+  /** Launcher hook turning the pre-flag composed rows into flag patches (the web alias's flag family). */
+  deriveFlagPatches?: (rows: ComposedProfile['rows']) => PatchOptions[]
+  /** One-shot task text; requires the composition to mount the headless runner row. */
+  task?: string
+  /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
+  prepare?: (ctx: Context) => Promise<void> | void
+}
+
+/**
+ * Boot one profile invocation end to end and leave process lifetime to the
+ * mounted plugins (or to the one-shot runner when `task` is present).
+ * @param options - profile name, overlays, flag patches, and the optional task.
+ * @returns the settled root context and the shutdown controller.
+ */
+export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Context; shutdown: ProcessShutdown }> {
+  const composed = composeProfile(options.profile, options.patchFiles, options.deriveFlagPatches)
+  if (options.task !== undefined) {
+    if (!composed.rows.has(HEADLESS_ROW_ID)) {
+      throw new Error(
+        `dsh: profile ${JSON.stringify(options.profile)} takes no task — its composition mounts no "${HEADLESS_ROW_ID}" row `
+        + '(the headless profile does)',
+      )
+    }
+    composed.overlayAndFlags.push({ id: HEADLESS_ROW_ID, config: { task: options.task } })
+  } else if (composed.rows.has(HEADLESS_ROW_ID)) {
+    // The inverse misuse: a one-shot composition booted without its task
+    // would otherwise die in the runner row's schema with a raw "required"
+    // error naming no fix.
+    throw new Error(
+      `dsh: profile ${JSON.stringify(options.profile)} mounts the one-shot runner and needs a task: `
+      + `dsh --profile ${options.profile} "<task>"`,
+    )
+  }
+
+  const app: { current?: Context } = {}
+  const shutdown = createProcessShutdown(async () => { await app.current?.fiber.dispose() })
+  // Signals own teardown throughout the startup window, not only after boot()
+  // settles: an inserted front door can publish readiness before sibling rows
+  // finish mounting.
+  process.on('SIGTERM', () => { shutdown.interrupt(options.task === undefined ? 0 : 143) })
+  process.on('SIGINT', () => { shutdown.interrupt(130) })
+  installFailLoud(NAME, process, async () => {
+    await app.current?.fiber.dispose()
+  })
+
+  const rootConfig = join(composed.profile.dir, PROFILE_ROOT_FILENAME)
+  // Recomposition for the live user layers: bundle layers below, overlays
+  // and flag patches above, so a user edit can never displace them. BOTH
+  // user files are re-read per generation (the HMR watcher hands us only the
+  // changed file's patches, which one of the reads duplicates — fresh reads
+  // keep the two watchers from stitching in each other's stale copy).
+  // Fresh clones per generation: the include pushes `insert` rows into the
+  // mounted tree BY REFERENCE and later id-targeted patches mutate those
+  // objects in place. Reusing one parsed patch object across applications
+  // would bake a user override into the bundle's in-memory insert row, so
+  // removing the override could never revert the row to the bundle default.
+  const composeLive = (): PatchOptions[] => structuredClone([
+    ...composed.bundlePatches,
+    ...loadOptionalPatches(NAME, composed.profile.patchPath) ?? [],
+    ...loadOptionalPatches(NAME, homePatchPath()) ?? [],
+    ...composed.overlayAndFlags,
+  ])
+  // One-shot runs exit through the runner; watching would only hold the
+  // process open after its exit request.
+  const watchProfilePatch = options.task === undefined
+  // Cloned for the same insert-aliasing reason as composeLive: the boot
+  // application must not mutate the objects later reloads recompose from.
+  const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), async (hostCtx) => {
+    app.current = hostCtx
+    if (options.task !== undefined) {
+      const io: HeadlessIo = {
+        stdout: process.stdout,
+        stderr: process.stderr,
+        exit: (code) => { void shutdown.shutdown(code) },
+      }
+      hostCtx.provide('headlessIo', io)
+    }
+    await options.prepare?.(hostCtx)
+  })
+  app.current = ctx
+  // A surface can dispose the whole tree while startup was still in flight
+  // (early SIGTERM); the Loader service goes with it and there is nothing to
+  // keep live.
+  if (watchProfilePatch && ctx.get('loader') !== undefined) {
+    // Config-only HMR for the live profile patch layer: the web bundle
+    // disables the shared module-reload `hmr` row (its reload lifecycle is
+    // untested), so when the composition leaves no HMR service, mount a
+    // watch-only instance with no module roots — cordis.patch.yml edits stay
+    // live on every long-lived surface. A silent skip would break the
+    // documented hot-reload contract. HMR injects the timer service, which a
+    // bare custom profile may not mount either.
+    if (ctx.get('hmr') === undefined) {
+      if (ctx.get('timer') === undefined) {
+        await ctx.loader.create({ name: '@cordisjs/plugin-timer' })
+      }
+      await ctx.loader.create({ name: '@cordisjs/plugin-hmr', config: { root: [] } })
+    }
+    await watchUserPatches(ctx, {
+      binName: NAME,
+      filename: composed.profile.patchPath,
+      compose: composeLive,
+    })
+    await watchUserPatches(ctx, {
+      binName: NAME,
+      filename: homePatchPath(),
+      compose: composeLive,
+    })
+  }
+  return { ctx, shutdown }
+}

apps/cli/src/web.ts

@@ -1,133 +1,127 @@
 /**
- * `dsh web` — thin bin over the config-tree boot: run AppCLIEntry with the
- * already-parsed host/port/dev, print the URL line, wire signals. All
- * composition lives in the shared base plus Web overlay; all boot glue lives in AppCLIEntry. Host and
- * port are unvalidated pass-through overrides — the `dsh-host-webserver` schema
- * gates them at boot.
+ * `dsh web` — the browser-surface alias over the profile boot: `--profile web`
+ * plus the Web flag family (`--host/--port/--dev/--workspace-root/
+ * --trusted-host`), each flag becoming a patch over the composed profile
+ * tree. All web runtime glue (dist serving, prompt section, URL line) lives
+ * in the `@deepseek-ai/dsh-web-app` bundle; this launcher only derives
+ * flag patches and the LAN-trust snapshot.
+ * @module @deepseek-ai/dsh/web
  */
 
+import { networkInterfaces } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import type { Context } from 'cordis'
-import { addHarnessSourceSection, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-import type {} from '@deepseek-ai/dsh-host-webserver'
-import type {} from '@deepseek-ai/dsh-system-prompt'
-import type {} from '@deepseek-ai/dsh-bash-env'
-import { AppCLIEntry } from './app-cli-entry.ts'
-import { createProcessShutdown } from './process-shutdown.ts'
+import type { PatchOptions } from '@cordisjs/plugin-include'
+import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot'
+import { runProfile } from './profile-boot.ts'
 
-// The shipped base plus the Web application's overlay.
-const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
-const WEB_OVERLAY = fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url))
 const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 
-const DSH_WEB_URL = 'DSH_WEB_URL' as const
-const DSH_WEB_MODE = 'DSH_WEB_MODE' as const
+/** The webserver schema's all-interfaces bind literal: gates LAN-authority derivation. */
+const ALL_INTERFACES_HOST = '0.0.0.0'
 
-type WebMode = 'production' | 'development'
-
-// 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'
+/**
+ * Non-internal IPv4 interface addresses of this machine — the IP-literal
+ * authorities an all-interfaces bind is reachable by on the LAN.
+ * @returns the addresses in interface order (possibly empty).
+ */
+function lanIPv4Addresses(): string[] {
+  return Object.values(networkInterfaces()).flat()
+    .filter((iface): iface is NonNullable<typeof iface> => iface !== undefined && iface.family === 'IPv4' && !iface.internal)
+    .map(iface => iface.address)
+}
 
-/** 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.'
+/**
+ * One LAN-trust resolution for one invocation, sampled exactly once: the
+ * machine's LAN IP literals when the effective bind is all-interfaces, and
+ * the `trustedHosts` value built from them plus the explicit extras. The
+ * single sample is deliberate — display must advertise only addresses the
+ * fence was configured with, so the web-app row receives this same snapshot.
+ * Derived entries are port-less IP literals: DNS rebinding needs an
+ * attacker-controlled name, so an IP-literal Host is safe on any port, and
+ * the bound port may be OS-assigned, unknowable pre-boot.
+ * @param bindHost - the effective webserver bind host (CLI flag, else the composed row value).
+ * @param extra - `--trusted-host` values, in argv order.
+ * @returns the sampled LAN addresses and the connection row's `trustedHosts` value (each possibly empty).
+ */
+export function resolveLanTrust(
+  bindHost: string | undefined,
+  extra: readonly string[],
+): { lanAddresses: string[]; trustedHosts: string[] } {
+  const lanAddresses = bindHost === ALL_INTERFACES_HOST ? lanIPv4Addresses() : []
+  return { lanAddresses, trustedHosts: [...lanAddresses, ...extra] }
 }
 
-/** 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('dsh web: httpServer service missing while resolving Web runtime')
-  return `http://${LOOPBACK_HOST}:${String(port)}`
+/** The `dsh web` flag family, already parsed by the argument adapter. */
+export interface WebFlags {
+  patches: string[]
+  host?: string
+  port?: number
+  dev: boolean
+  workspaceRoot?: string
+  trustedHosts?: string[]
 }
 
 /**
- * Register the launcher-owned prompt and shell runtime context before the
- * shared config tree mounts. The earlier injections install the prompt
- * sections and managed Bash contributor when their owning services activate;
- * dynamic values read the bound server only when consumed.
- * @param ctx - Web root context with Loader installed but no config tree mounted.
- * @param sourceRoot - absolute checkout root resolved from the launcher module.
- * @param mode - whether this process mounted the client-plugin HMR receiver.
+ * Derive the web alias's flag patches over an already-composed profile tree.
+ * Patches replace a row's whole config, so each patched row's composed values
+ * are re-read and merged under the overrides.
+ * @param rows - the composed row index from {@link composeProfile}.
+ * @param flags - the parsed flag family.
+ * @returns the flag patch list, in application order.
  */
-export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode: WebMode): void {
-  ctx.inject(['systemPrompt'], (promptCtx) => {
-    addHarnessSourceSection(promptCtx, sourceRoot)
-    promptCtx.systemPrompt.section({
-      name: 'app:web-surface',
-      order: -98,
-      text: () => webSurfacePrompt(localWebUrl(promptCtx), 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]: mode }),
-    })
+function deriveWebFlagPatches(
+  rows: Map<string, { name?: string; config?: unknown }>,
+  flags: WebFlags,
+): PatchOptions[] {
+  const overrides = new Map<string, Record<string, unknown>>()
+  const put = (entryId: string, key: string, value: unknown): void => {
+    const bag = overrides.get(entryId) ?? {}
+    bag[key] = value
+    overrides.set(entryId, bag)
+  }
+  if (flags.host !== undefined) put('webserver', 'host', flags.host)
+  if (flags.port !== undefined) put('webserver', 'port', flags.port)
+  if (flags.workspaceRoot !== undefined) put('api-gateway', 'workspaceRoot', flags.workspaceRoot)
+  const composedHost = (rows.get('webserver')?.config as { host?: string } | undefined)?.host
+  const { lanAddresses, trustedHosts } = resolveLanTrust(flags.host ?? composedHost, flags.trustedHosts ?? [])
+  if (trustedHosts.length > 0) {
+    // Additive over the composed value: a cordis.patch.yml-configured fence
+    // authority must survive the derived LAN literals and flag extras — a
+    // silent drop of security-relevant fence configuration.
+    const composedTrusted = (rows.get('connection')?.config as { trustedHosts?: string[] } | undefined)?.trustedHosts ?? []
+    put('connection', 'trustedHosts', [...composedTrusted, ...trustedHosts])
+  }
+  // mode and lanAddresses are launcher-derived on every boot (--dev also
+  // inserts the client-hmr row), never pass-throughs of composed values.
+  put('web-runtime', 'mode', flags.dev ? 'development' : 'production')
+  put('web-runtime', 'lanAddresses', lanAddresses)
+  const patches = [...overrides.entries()].map(([id, bag]): PatchOptions => {
+    const composed = rows.get(id)
+    if (composed === undefined) throw new Error(`dsh: patch target row "${id}" not found in the web profile composition`)
+    return { id, config: { ...(composed.config ?? {}) as Record<string, unknown>, ...bag } }
   })
+  if (flags.dev) patches.push({ insert: [{ id: 'client-hmr', name: '@deepseek-ai/dsh-client-hmr' }] })
+  return patches
 }
 
 /**
- * Serve the browser UI from the shipped config tree. `host`/`port` are passed
- * through only when the flag was given; absent, the shipped Web overlay value stands.
- * @param host - the bind host, or `undefined` to keep the config default.
- * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
- * @param dev - mount the client HMR receiver; `pnpm run dev:web` separately rebuilds watched plugin bundles.
- * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
- * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
- * @param config - an overlay of loader patches applied over the shipped web
- * composition instead of `$DSH_HOME/config.yaml`, or `undefined` to use the
- * personal overlay; already parsed from `--config`.
+ * Serve the browser UI from the web profile. Host/port/workspace-root flags
+ * are passed through only when given (absent, the composed profile values
+ * stand); `web-runtime.mode` and `lanAddresses` are launcher-derived on
+ * every boot. The URL line is printed by the web-app bundle's runtime row
+ * after Loader settlement.
+ * @param flags - the parsed `dsh web` flag family.
  */
-export async function runWeb(
-  host: string | undefined,
-  port: number | undefined,
-  dev: boolean,
-  workspaceRoot: string | undefined,
-  trustedHosts: string[] | undefined,
-  config?: string,
-): Promise<void> {
-  const mode: WebMode = dev ? 'development' : 'production'
-  const entry = new AppCLIEntry({
-    configPath: BASE_CONFIG,
-    overlayPath: WEB_OVERLAY,
-    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
-    dev,
-    prepare: (ctx) => { prepareWebRuntimeContext(ctx, SOURCE_ROOT, mode) },
-    watchPersonalConfig: true,
-    ...host !== undefined && { host },
-    ...port !== undefined && { port },
-    ...workspaceRoot !== undefined && { workspaceRoot },
-    ...trustedHosts !== undefined && { trustedHosts },
+export async function runWeb(flags: WebFlags): Promise<void> {
+  await runProfile({
+    profile: 'web',
+    patchFiles: flags.patches,
+    deriveFlagPatches: rows => deriveWebFlagPatches(rows, flags),
+    prepare: (ctx: Context) => {
+      ctx.inject(['systemPrompt'], (promptCtx) => {
+        addHarnessSourceSection(promptCtx, SOURCE_ROOT)
+      })
+    },
   })
-  const { ctx, port: boundPort } = await entry.run()
-  const resolvedLocalWebUrl = localWebUrl(ctx)
-
-  const shutdown = createProcessShutdown(async () => { await ctx.fiber.dispose() })
-
-  // Install shutdown handling before publishing readiness: supervisors may
-  // send a signal as soon as they observe the URL line.
-  process.on('SIGTERM', () => { shutdown.interrupt(0) })
-  process.on('SIGINT', () => { shutdown.interrupt(130) })
-
-  // The entry's boot-time snapshot, not a fresh sample: the printed LAN URL
-  // must name an address the /api trust fence was configured with.
-  const lanCandidate = entry.lanAddresses[0]
-  console.log(`dsh web: ${resolvedLocalWebUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
 }

apps/cli/tests/args.spec.ts

@@ -21,49 +21,71 @@ function exitCode(argv: string[]): number {
 afterEach(() => { vi.restoreAllMocks() })
 
 describe('parseDshArgs', () => {
-  it('routes the required raw config, one-shot prompt, and Web command', () => {
-    expect(parse(['--config', 'custom.yml'])).toEqual({ mode: 'config', config: 'custom.yml' })
-    expect(parse(['-p', 'do the thing'])).toEqual({ mode: 'headless', prompt: 'do the thing' })
-    expect(parse(['web'])).toEqual({ mode: 'web', dev: false })
-    expect(parse(['web', '--config', 'web.yml'])).toEqual({ mode: 'web', dev: false, config: 'web.yml' })
+  it('routes profile boots, one-shot tasks, and the web alias', () => {
+    expect(parse(['--profile', 'tui'])).toEqual({ mode: 'profile', profile: 'tui', patches: [] })
+    expect(parse(['--profile', 'headless', 'run', 'the', 'tests']))
+      .toEqual({ mode: 'profile', profile: 'headless', patches: [], task: 'run the tests' })
+    expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--patch', 'b.yml']))
+      .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml', 'b.yml'] })
+    expect(parse(['web'])).toEqual({ mode: 'web', dev: false, patches: [] })
+    expect(parse(['web', '--patch', 'web.yml'])).toEqual({ mode: 'web', dev: false, patches: ['web.yml'] })
     expect(parse(['web', '--host', '0.0.0.0', '--port', '8080', '--dev', '--workspace-root', '/w']))
-      .toEqual({ mode: 'web', host: '0.0.0.0', port: 8080, dev: true, workspaceRoot: '/w' })
+      .toEqual({ mode: 'web', host: '0.0.0.0', port: 8080, dev: true, workspaceRoot: '/w', patches: [] })
     expect(parse(['web', '--trusted-host', 'harness.internal:3080', 'lab.internal', '--trusted-host', '10.0.0.9']))
-      .toEqual({ mode: 'web', dev: false, trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] })
+      .toEqual({ mode: 'web', dev: false, patches: [], trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] })
   })
 
-  it('routes raw and Web config dumps', () => {
-    expect(parse(['--config', 'c.yml', '--dump-config']))
-      .toEqual({ mode: 'dump-config', surface: 'config', defaultOnly: false, config: 'c.yml' })
-    expect(parse(['--dump-default-config']))
-      .toEqual({ mode: 'dump-config', surface: 'config', defaultOnly: true })
+  it('routes the plugin pnpm forwarder', () => {
+    expect(parse(['plugin', '--profile', 'tui', 'add', 'turtle-ui']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['add', 'turtle-ui'] })
+    expect(parse(['plugin', '--profile', 'tui', 'remove', 'turtle-ui']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['remove', 'turtle-ui'] })
+    expect(parse(['plugin', '--profile', 'tui', 'why', 'cordis']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['why', 'cordis'] })
+    // Unknown pnpm flags forward verbatim.
+    expect(parse(['plugin', '--profile', 'tui', 'add', '--save-dev', 'x']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['add', '--save-dev', 'x'] })
+  })
+
+  it('routes profile and web config dumps', () => {
+    expect(parse(['--profile', 'web', '--dump-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: false, patches: [] })
+    expect(parse(['--profile', 'web', '--dump-default-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
+    expect(parse(['--profile', 'tui', '--dump-config', '--patch', 'x.yml']))
+      .toEqual({ mode: 'dump-config', profile: 'tui', defaultOnly: false, patches: ['x.yml'] })
     expect(parse(['web', '--dump-config']))
-      .toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: false })
-    expect(parse(['web', '--dump-config', '--config', 'w.yml']))
-      .toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: false, config: 'w.yml' })
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: false, patches: [] })
     expect(parse(['web', '--dump-default-config']))
-      .toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: true })
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
   })
 
-  it('rejects missing config, removed commands, and contradictory inputs', () => {
+  it('rejects missing profile, removed flags, and contradictory inputs', () => {
     expect(exitCode([])).toBe(1)
-    expect(exitCode(['tui'])).toBe(1)
-    expect(exitCode(['meta'])).toBe(1)
-    expect(exitCode(['upgrade'])).toBe(1)
+    expect(exitCode(['tui'])).toBe(1) // a bare word is a task without --profile
+    expect(exitCode(['--config', 'c.yml'])).toBe(1) // removed
+    expect(exitCode(['-p', 'task'])).toBe(1) // removed
+    expect(exitCode(['--profile', ''])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--patch='])).toBe(1)
     expect(exitCode(['--dump-config'])).toBe(1)
-    expect(exitCode(['--dump-config', '--dump-default-config', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['--dump-default-config', '--config', 'c.yml'])).toBe(1)
-    expect(exitCode(['--dump-config', '--config', 'c.yml', '-p', 'task'])).toBe(1)
-    expect(exitCode(['-p', ''])).toBe(1)
-    expect(exitCode(['--config='])).toBe(1)
-    expect(exitCode(['-p', 'x', '--config', 'c.yml'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-config', '--dump-default-config'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-default-config', '--patch', 'p.yml'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-config', 'task'])).toBe(1)
     expect(exitCode(['--bogus'])).toBe(1)
-    expect(exitCode(['bogus-positional'])).toBe(1)
-    expect(exitCode(['web', '-p', 'task'])).toBe(1)
-    expect(exitCode(['--config', 'c.yml', 'web'])).toBe(1)
+    expect(exitCode(['--profile', 'x', 'web'])).toBe(1)
     expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1)
-    expect(exitCode(['web', '--dump-default-config', '--config', 'w.yml'])).toBe(1)
-    expect(exitCode(['web', '--config='])).toBe(1)
+    expect(exitCode(['web', '--dump-default-config', '--patch', 'w.yml'])).toBe(1)
+    expect(exitCode(['web', '--patch='])).toBe(1)
+    // Boot-free dumps derive no flag patches; silently dropping the flags
+    // would print a tree that differs from the same invocation's boot.
+    expect(exitCode(['web', '--dump-config', '--port', '8080'])).toBe(1)
+    expect(exitCode(['web', '--dump-config', '--dev'])).toBe(1)
+    // A non-numeric port fails at the flag, not deep in the webserver schema.
+    expect(exitCode(['web', '--port', 'abc'])).toBe(1)
+    expect(exitCode(['plugin', 'add', 'x'])).toBe(1) // --profile required
+    expect(exitCode(['plugin', '--profile', 'tui'])).toBe(1) // nothing to forward
+    expect(exitCode(['plugin', '--profile', ''])).toBe(1)
+    expect(exitCode(['--profile', 'x', 'plugin', 'add', 'y'])).toBe(1)
   })
 
   it('exits 0 for help and version', () => {

apps/cli/tests/built-bin.e2e.ts

@@ -1,15 +1,14 @@
-import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { execa } from 'execa'
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 
-/** Published-entry acceptance for raw argument errors and boot-free config dumps. */
+/** Published-entry acceptance for argument errors, profile lifecycle, and boot-free config dumps. */
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
-const rawOverlay = fileURLToPath(new URL('./fixtures/raw-overlay.cordis.yml', import.meta.url))
-const rawInvalidProvider = fileURLToPath(new URL('./fixtures/raw-invalid-provider.cordis.yml', import.meta.url))
+const invalidProvider = fileURLToPath(new URL('./fixtures/invalid-provider.cordis.yml', import.meta.url))
 
 async function runBuiltBin(
   args: readonly string[] = [],
@@ -31,60 +30,95 @@ async function runBuiltBin(
 async function waitForFile(file: string): Promise<void> {
   const deadline = Date.now() + 20_000
   while (!existsSync(file)) {
-    if (Date.now() >= deadline) throw new Error(`dsh raw lifecycle marker did not appear: ${file}`)
+    if (Date.now() >= deadline) throw new Error(`dsh profile lifecycle marker did not appear: ${file}`)
     await new Promise(resolve => setTimeout(resolve, 20))
   }
 }
 
-interface RawLifecycleFixture {
+interface ProfileLifecycleFixture {
   home: string
   ready: string
   settled: string
   disposed: string
-  overlay: string
 }
 
-function createRawLifecycleFixture(): RawLifecycleFixture {
-  const home = mkdtempSync(join(tmpdir(), 'dsh-raw-lifecycle-'))
+/**
+ * A minimal custom profile: one lifecycle-marker plugin bundle listed in
+ * dsh.profile.bundles, no dsh-base — proving out-of-box composition machinery without
+ * booting the entire product tree.
+ */
+function createProfileLifecycleFixture(): ProfileLifecycleFixture {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-profile-lifecycle-'))
   const ready = join(home, 'ready')
   const settled = join(home, 'settled')
   const disposed = join(home, 'disposed')
-  const plugin = join(home, 'lifecycle.mjs')
-  const overlay = join(home, 'overlay.cordis.yml')
-  writeFileSync(plugin, [
+  const bundleDir = join(home, 'lifecycle-bundle')
+  mkdirSync(bundleDir, { recursive: true })
+  writeFileSync(join(bundleDir, 'plugin.mjs'), [
     "import { writeFileSync } from 'node:fs'",
-    "export const name = 'raw-lifecycle-fixture'",
-    "export const inject = ['sessionQuery']",
-    'export function apply(ctx) {',
+    "import { join } from 'node:path'",
+    "export const name = 'profile-lifecycle-fixture'",
+    'export function apply(ctx, config = {}) {',
     '  let active = true',
+    '  // Keep the event loop alive so process lifetime is signal-owned, like a real surface.',
+    '  const heartbeat = setInterval(() => {}, 1000)',
+    '  // Echo the mounted generation so the hot-reload e2e can assert both an',
+    '  // applied override and its removal reverting to this bundle default.',
+    "  writeFileSync(join(process.env.DSH_HOME, 'config-echo'), String(config.generation ?? 'bundle-default'))",
     "  writeFileSync(process.env.RAW_READY_FILE, 'ready')",
     '  void ctx.loader.await().then(() => {',
     "    if (active) writeFileSync(process.env.RAW_SETTLED_FILE, 'settled')",
     '  })',
     '  ctx.effect(() => () => {',
     '    active = false',
+    '    clearInterval(heartbeat)',
     "    writeFileSync(process.env.RAW_DISPOSED_FILE, 'disposed')",
     '  })',
     '}',
     '',
   ].join('\n'))
-  writeFileSync(overlay, [
+  writeFileSync(join(bundleDir, 'cordis.patch.yml'), [
     '- insert:',
-    '    - id: raw-lifecycle-fixture',
-    `      name: ${pathToFileURL(plugin).href}`,
+    '    - id: profile-lifecycle-fixture',
+    `      name: ${pathToFileURL(join(bundleDir, 'plugin.mjs')).href}`,
     '',
   ].join('\n'))
-  return { home, ready, settled, disposed, overlay }
+  writeFileSync(join(bundleDir, 'package.json'), JSON.stringify({
+    name: 'dsh-lifecycle-bundle',
+    version: '0.0.0',
+    type: 'module',
+    dsh: { bundle: { patch: './cordis.patch.yml' } },
+  }, undefined, 2))
+  const profileDir = join(home, 'profiles', 'lifecycle')
+  mkdirSync(join(profileDir, 'node_modules'), { recursive: true })
+  writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-lifecycle',
+    private: true,
+    dependencies: {},
+    dsh: { profile: { bundles: ['dsh-lifecycle-bundle'] } },
+  }, undefined, 2))
+  // Hand-place the "installed" bundle where profile resolution finds it.
+  writeFileSync(join(profileDir, 'cordis.patch.yml'), '[]\n')
+  const linkTarget = join(profileDir, 'node_modules', 'dsh-lifecycle-bundle')
+  mkdirSync(join(profileDir, 'node_modules'), { recursive: true })
+  try {
+    rmSync(linkTarget, { recursive: true, force: true })
+  } catch { /* fresh dir */ }
+  // Copy-free: a package.json redirecting via a relative main is enough for require.resolve.
+  mkdirSync(linkTarget, { recursive: true })
+  for (const file of ['package.json', 'cordis.patch.yml', 'plugin.mjs']) {
+    writeFileSync(join(linkTarget, file), readFileSync(join(bundleDir, file)))
+  }
+  return { home, ready, settled, disposed }
 }
 
-function startRawLifecycle(fixture: RawLifecycleFixture) {
-  return execa(process.execPath, [dshBin, '--config', fixture.overlay], {
+function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
+  return execa(process.execPath, [dshBin, '--profile', 'lifecycle'], {
     cwd: fixture.home,
     input: '',
     reject: false,
     env: {
       DSH_HOME: fixture.home,
-      DSH_TELEMETRY_DISABLED: '1',
       RAW_READY_FILE: fixture.ready,
       RAW_SETTLED_FILE: fixture.settled,
       RAW_DISPOSED_FILE: fixture.disposed,
@@ -93,35 +127,57 @@ function startRawLifecycle(fixture: RawLifecycleFixture) {
 }
 
 describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', () => {
-  it('requires --config for the raw command and rejects removed commands', async () => {
+  it('requires --profile and rejects removed commands', async () => {
     const bare = await runBuiltBin()
     expect(bare.code).toBe(1)
     expect(bare.stdout).toBe('')
-    expect(bare.stderr).toContain('--config <path> is required')
+    expect(bare.stderr).toContain('--profile <name> is required')
     const help = await runBuiltBin(['--help'])
     expect(help.code).toBe(0)
-    expect(help.stdout).toContain('dsh --config ./app.cordis.yml')
+    expect(help.stdout).toContain('dsh --profile web')
+    expect(help.stdout).toContain('dsh plugin --profile')
     expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
-    for (const command of ['tui', 'meta', 'upgrade']) {
-      const removed = await runBuiltBin([command])
-      expect(removed.code).toBe(1)
-      expect(removed.stderr).not.toContain('experimental')
+    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task']]) {
+      const result = await runBuiltBin(removed)
+      expect(result.code).toBe(1)
+    }
+  }, 30_000)
+
+  it('fails loud on a nonexistent profile with the plugin-command hint', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-missing-profile-'))
+    try {
+      const result = await runBuiltBin(['--profile', 'nope'], { DSH_HOME: home })
+      expect(result.code).toBe(1)
+      expect(result.stderr).toContain('profile "nope" does not exist')
+      expect(result.stderr).toContain('dsh plugin --profile nope add')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
     }
   }, 30_000)
 
-  it('reports a raw overlay boot failure without hanging', async () => {
-    const result = await runBuiltBin(['--config', rawInvalidProvider], {
-      DEEPSEEK_API_KEY: 'keyless-invalid-config',
-      DSH_TELEMETRY_DISABLED: '1',
-    })
-    expect(result.code).toBe(1)
-    expect(result.stdout).toBe('')
-    expect(result.stderr).toContain('llm-pi-ai')
+  it('reports a patch-overlay boot failure without hanging', async () => {
+    // The HMR main watcher's initial scan once refreshed the include
+    // mid-initial-apply, deadlocking the failing apply's rollback against the
+    // refresh drain: dsh exited 13 with no diagnostic instead of settling
+    // ([Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md)).
+    const home = mkdtempSync(join(tmpdir(), 'dsh-invalid-patch-'))
+    try {
+      const result = await runBuiltBin(['--profile', 'web', '--patch', invalidProvider], {
+        DSH_HOME: home,
+        DEEPSEEK_API_KEY: 'keyless-invalid-config',
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(result.code).toBe(1)
+      expect(result.stdout).toBe('')
+      expect(result.stderr).toContain('llm-pi-ai')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
   }, 30_000)
 
-  it('applies an inserted raw plugin and disposes it on a startup-time signal', async () => {
-    const fixture = createRawLifecycleFixture()
-    const child = startRawLifecycle(fixture)
+  it('applies a custom profile bundle and disposes it on a startup-time signal', async () => {
+    const fixture = createProfileLifecycleFixture()
+    const child = startProfileLifecycle(fixture)
     try {
       await waitForFile(fixture.ready)
       child.kill('SIGTERM')
@@ -135,11 +191,47 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
-  it('fully settles a valid raw overlay and disposes it on a signal', async () => {
-    const fixture = createRawLifecycleFixture()
-    const child = startRawLifecycle(fixture)
+  it('fully settles a custom profile, hot-reloads its patch layer with removal reverting, and disposes on a signal', async () => {
+    const fixture = createProfileLifecycleFixture()
+    const child = startProfileLifecycle(fixture)
+    const profilePatch = join(fixture.home, 'profiles', 'lifecycle', 'cordis.patch.yml')
+    const configFile = join(fixture.home, 'config-echo')
     try {
       await waitForFile(fixture.settled)
+      // The live profile layer: even without an hmr row in the composition,
+      // the launcher mounts a config-only watcher, so an edited
+      // cordis.patch.yml lands in the running tree (the reload disposes the
+      // patched row's old fiber — observable as the disposed marker — and
+      // mounts the new config, which echoes its generation and re-writes the
+      // ready marker).
+      rmSync(fixture.ready)
+      writeFileSync(profilePatch, [
+        '- id: profile-lifecycle-fixture',
+        '  config:',
+        '    generation: 2',
+        '',
+      ].join('\n'))
+      await waitForFile(fixture.ready)
+      expect(readFileSync(configFile, 'utf8')).toBe('2')
+      // Removal reverts: the bundle's inserted row must return to its own
+      // default config, not keep the removed override — the insert-aliasing
+      // regression (a shared patch object mutated in place by a former
+      // generation would make this impossible).
+      rmSync(fixture.ready)
+      writeFileSync(profilePatch, '[]\n')
+      await waitForFile(fixture.ready)
+      expect(readFileSync(configFile, 'utf8')).toBe('bundle-default')
+      // The home-level user layer ($DSH_HOME/cordis.patch.yml) is live too
+      // and outranks the per-profile layer.
+      rmSync(fixture.ready)
+      writeFileSync(join(fixture.home, 'cordis.patch.yml'), [
+        '- id: profile-lifecycle-fixture',
+        '  config:',
+        '    generation: home',
+        '',
+      ].join('\n'))
+      await waitForFile(fixture.ready)
+      expect(readFileSync(configFile, 'utf8')).toBe('home')
       child.kill('SIGTERM')
       const result = await child
       expect(result.exitCode).toBe(0)
@@ -151,55 +243,129 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
+  it('anchors a relative add spec to the invoking directory, not the profile', async () => {
+    // `dsh plugin --profile x add .` from a plugin checkout must install THAT
+    // checkout — pnpm's cwd is the profile directory, so an un-anchored `.`
+    // would self-link the profile.
+    const home = mkdtempSync(join(tmpdir(), 'dsh-plugin-anchor-'))
+    const checkout = mkdtempSync(join(tmpdir(), 'dsh-plugin-checkout-'))
+    try {
+      writeFileSync(join(checkout, 'package.json'), JSON.stringify({
+        name: 'anchored-bundle',
+        version: '1.0.0',
+        dsh: { bundle: { patch: './cordis.patch.yml' } },
+      }))
+      writeFileSync(join(checkout, 'cordis.patch.yml'), '[]\n')
+      const result = await execa(process.execPath, [dshBin, 'plugin', '--profile', 'anchor', 'add', '.'], {
+        cwd: checkout,
+        input: '',
+        timeout: 60_000,
+        killSignal: 'SIGKILL',
+        reject: false,
+        env: { DSH_HOME: home },
+      })
+      expect(result.exitCode).toBe(0)
+      const manifest = JSON.parse(readFileSync(join(home, 'profiles', 'anchor', 'package.json'), 'utf8')) as {
+        dependencies: Record<string, string>
+        dsh: { profile: { bundles: string[] } }
+      }
+      expect(Object.keys(manifest.dependencies)).toEqual(['anchored-bundle'])
+      expect(manifest.dsh.profile.bundles).toContain('anchored-bundle')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+      rmSync(checkout, { recursive: true, force: true })
+    }
+  }, 90_000)
+
+  it('activates a dependency that gained dsh.bundle in a later update', async () => {
+    // Reconcile runs against the INSTALLED state on every successful pnpm
+    // run, so `update` (not only `add`) activates a package whose newer
+    // version declares dsh.bundle. Simulated without a registry: hand-place
+    // the installed package, flip its manifest, and run a benign pnpm verb.
+    const home = mkdtempSync(join(tmpdir(), 'dsh-plugin-update-'))
+    try {
+      const profileDir = join(home, 'profiles', 'up')
+      const installed = join(profileDir, 'node_modules', 'late-bundle')
+      mkdirSync(installed, { recursive: true })
+      writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+        name: 'dsh-profile-up',
+        private: true,
+        dependencies: { 'late-bundle': 'file:./late-bundle' },
+        dsh: { profile: { bundles: ['@deepseek-ai/dsh-base'] } },
+      }))
+      writeFileSync(join(profileDir, 'cordis.patch.yml'), '[]\n')
+      // v1: no dsh manifest — a plain dependency.
+      writeFileSync(join(installed, 'package.json'), JSON.stringify({ name: 'late-bundle', version: '1.0.0' }))
+      const first = await runBuiltBin(['plugin', '--profile', 'up', 'root'], { DSH_HOME: home })
+      expect(first.code).toBe(0)
+      let manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as { dsh: { profile: { bundles: string[] } } }
+      expect(manifest.dsh.profile.bundles).toEqual(['@deepseek-ai/dsh-base'])
+      // v2: the installed package now declares dsh.bundle (an update landed).
+      writeFileSync(join(installed, 'package.json'), JSON.stringify({
+        name: 'late-bundle', version: '2.0.0', dsh: { bundle: { patch: './cordis.patch.yml' } },
+      }))
+      writeFileSync(join(installed, 'cordis.patch.yml'), '[]\n')
+      const second = await runBuiltBin(['plugin', '--profile', 'up', 'root'], { DSH_HOME: home })
+      expect(second.code).toBe(0)
+      manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as { dsh: { profile: { bundles: string[] } } }
+      expect(manifest.dsh.profile.bundles).toEqual(['@deepseek-ai/dsh-base', 'late-bundle'])
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
   describe('config dump', () => {
     let home: string
     beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'dsh-dump-bin-')) })
     afterEach(() => { rmSync(home, { recursive: true, force: true }) })
 
-    it('prints the shipped base without a user layer', async () => {
-      const { stdout, code, stderr } = await runBuiltBin(['--dump-default-config'], { DSH_HOME: home })
+    it('prints the web profile bundle layers without a user layer', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
       expect(code).toBe(0)
       expect(stderr).toBe('')
       expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-loop'")
       expect(stdout).toContain('agents: []')
-      expect(stdout).toContain('# == base.cordis.yml')
+      expect(stdout).toContain('# == @deepseek-ai/dsh-base')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
     }, 30_000)
 
-    it('composes the required raw overlay directly over the base', async () => {
-      writeFileSync(join(home, 'config.yaml'), [
+    it('composes the profile user layer and a --patch overlay in order', async () => {
+      // Auto-init the web profile first, then write its user layer.
+      const init = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
+      expect(init.code).toBe(0)
+      const profilePatch = join(home, 'profiles', 'web', 'cordis.patch.yml')
+      writeFileSync(profilePatch, [
         '- id: agent-loop',
         '  config:',
         '    agents:',
         '      - id: personal',
         '        provider: personal-provider',
         '        model: personal-model',
+        '- id: absent-row',
+        '  config:',
+        '    x: 1',
+        '',
+      ].join('\n'))
+      const overlay = join(home, 'overlay.cordis.yml')
+      writeFileSync(overlay, [
+        '- id: agent-loop',
+        '  config:',
+        '    agents:',
+        '      - id: configured',
+        '        provider: configured-provider',
+        '        model: configured-model',
         '',
       ].join('\n'))
       const { stdout, code, stderr } = await runBuiltBin(
-        ['--config', rawOverlay, '--dump-config'],
+        ['--profile', 'web', '--patch', overlay, '--dump-config'],
         { DSH_HOME: home },
       )
       expect(code).toBe(0)
       expect(stdout).toContain('provider: configured-provider')
       expect(stdout).not.toContain('personal-provider')
-      expect(stdout).toContain(`patched by ${rawOverlay}`)
+      // Both layers patched the row; provenance lists them in application order.
+      expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
       expect(stderr).toContain('patch: entry "absent-row" not found')
     }, 30_000)
-
-    it('keeps the Web overlay and personal layer on the Web command', async () => {
-      writeFileSync(join(home, 'config.yaml'), [
-        '- id: agent-loop',
-        '  config:',
-        '    agents:',
-        '      - id: personal',
-        '        provider: personal-provider',
-        '        model: personal-model',
-        '',
-      ].join('\n'))
-      const { stdout, code } = await runBuiltBin(['web', '--dump-config'], { DSH_HOME: home })
-      expect(code).toBe(0)
-      expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
-      expect(stdout).toContain('provider: personal-provider')
-    }, 30_000)
   })
 })

apps/cli/tests/fixtures/raw-invalid-provider.cordis.yml → apps/cli/tests/fixtures/invalid-provider.cordis.yml

@@ -1,4 +1,4 @@
-# Invalid raw overlay used to prove boot failures settle and exit.
+# Invalid `--patch` overlay used to prove boot failures settle and exit.
 
 - id: llm-pi-ai
   config:

apps/cli/tests/fixtures/raw-overlay.cordis.yml

@@ -1,12 +0,0 @@
-# Raw CLI overlay used by the built config-dump acceptance test.
-
-- id: agent-loop
-  config:
-    agents:
-      - id: configured
-        provider: configured-provider
-        model: configured-model
-
-- id: absent-row
-  config:
-    value: unmatched

apps/cli/tests/headless-shutdown.e2e.ts

@@ -65,8 +65,17 @@ async function runHeadlessPtySmoke(): Promise<string> {
   const cwd = await mkdtemp(join(tmpdir(), 'dsh-headless-shutdown-'))
   try {
     const home = join(cwd, '.dsh')
-    await mkdir(home, { recursive: true })
-    await writeFile(join(home, 'config.yaml'), [
+    // Pre-initialize the headless profile with the never-dispose row in its
+    // user patch layer (the same file `dsh --profile headless` hot-reloads).
+    const profileDir = join(home, 'profiles', 'headless')
+    await mkdir(profileDir, { recursive: true })
+    await writeFile(join(profileDir, 'package.json'), JSON.stringify({
+      name: 'dsh-profile-headless',
+      private: true,
+      dependencies: {},
+      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'] } },
+    }, undefined, 2))
+    await writeFile(join(profileDir, 'cordis.patch.yml'), [
       '- insert:',
       '    - id: never-dispose',
       `      name: '${neverDisposePlugin}'`,
@@ -74,7 +83,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
     ].join('\n'))
     const launch = resolveExampleLaunch({
       srcBin: dshBinScript,
-      configArgs: ['-p', 'never complete'],
+      configArgs: ['--profile', 'headless', 'never complete'],
       tsconfigPath,
       env: {
         DSH_HOME: home,

apps/cli/tests/lazy-search-startup.compat.spec.ts

@@ -4,8 +4,8 @@
  * Only the dedicated Node compatibility gate opts this test in after building
  * both artifacts; ordinary Vitest inventory deterministically skips it.
  * The child runs built artifacts under plain Node with the real shipped
- * config (base.cordis.yml + the web.cordis.yml overlay).
- * Its URL line follows AppCLIEntry's settled boot; SIGTERM then exercises the
+ * web profile (dsh-base + dsh-web-app bundle patches, auto-initialized).
+ * Its URL line follows the settled profile boot; SIGTERM then exercises the
  * shipped quiescent disposer.
  */
 
@@ -21,8 +21,8 @@ import { describe, expect, it } from 'vitest'
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const builtBin = join(repoRoot, 'apps/cli/lib/bin.js')
 const webDist = join(repoRoot, 'apps/web/dist/index.html')
-// The web overlay owns the session-query-sqlite lazy-open patch row.
-const configPath = join(repoRoot, 'apps/cli/config/web.cordis.yml')
+// The web bundle's patch owns the session-query-sqlite lazy-open row.
+const configPath = join(repoRoot, 'packages/bundle/web-app/cordis.patch.yml')
 const requireBuiltArtifacts = process.env.DSH_REQUIRE_BUILT_CLI_SMOKE === '1'
 
 interface ConfigRow {

apps/cli/tests/source-launch.compat.spec.ts

@@ -16,7 +16,7 @@ const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshSourceBin = 'apps/cli/src/bin.ts'
 
 describe('dsh SOURCE launcher (node --import tsx/esm)', () => {
-  it('boots the source entry and requires the raw config overlay', async () => {
+  it('boots the source entry and requires a profile', async () => {
     const result = await execa(process.execPath, ['--import', 'tsx/esm', dshSourceBin], {
       cwd: repoRoot,
       input: '',
@@ -28,7 +28,7 @@ describe('dsh SOURCE launcher (node --import tsx/esm)', () => {
       throw new Error(`dsh source launch did not exit within 25s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
     }
     expect(result.exitCode).not.toBe(0)
-    expect(result.stderr).toContain('--config <path> is required')
+    expect(result.stderr).toContain('--profile <name> is required')
     expect(result.stdout).toBe('')
   }, 30_000)
 })

apps/cli/tests/telemetry-switch.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { resolveTelemetryPatch } from '../src/app-cli-entry.ts'
+import { resolveTelemetryPatch } from '../src/profile-boot.ts'
 
 describe('resolveTelemetryPatch', () => {
   it('keeps telemetry enabled when the switch is unset or empty', () => {
@@ -13,11 +13,10 @@ describe('resolveTelemetryPatch', () => {
     }
   })
 
-  it('fails loud when the switch is set but the row is absent', () => {
-    expect(() => resolveTelemetryPatch('1', false)).toThrow('DSH_TELEMETRY_DISABLED is set but row "telemetry-otel" is not in this composition')
-  })
-
-  it('ignores a missing row while the switch is unset', () => {
+  it('is trivially satisfied by a composition without the telemetry row', () => {
+    // A custom profile need not mount telemetry: nothing exports, so the
+    // privacy switch has nothing to disable and generates no patch.
+    expect(resolveTelemetryPatch('1', false)).toBeUndefined()
     expect(resolveTelemetryPatch(undefined, false)).toBeUndefined()
   })
 })

apps/cli/tests/trusted-hosts.spec.ts

@@ -1,7 +1,7 @@
 /** Single-sample LAN-trust resolution for the /api browser-trust fence (`resolveLanTrust`). */
 
 import { describe, expect, it, vi } from 'vitest'
-import { resolveLanTrust } from '../src/app-cli-entry.ts'
+import { resolveLanTrust } from '../src/web.ts'
 
 vi.mock('node:os', () => ({
   networkInterfaces: () => ({

apps/cli/tests/web-prompt-context.spec.ts

@@ -1,32 +0,0 @@
-import { sep } from 'node:path'
-import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
-import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
-import { HARNESS_SOURCE_SECTION } from '@deepseek-ai/dsh-app-boot'
-import type {} from '@deepseek-ai/dsh-host-webserver'
-import { prepareWebRuntimeContext } from '../src/web.ts'
-
-describe('prepareWebRuntimeContext', () => {
-  it('installs both sections before a later systemPrompt consumer activates', async () => {
-    const ctx = new Context()
-    const sourceRoot = `${sep}opt${sep}harness-src`
-    let observedSections: { name: string; text: string }[] | undefined
-    try {
-      prepareWebRuntimeContext(ctx, sourceRoot, 'production')
-      ctx.provide('httpServer', { port: 3080 } as Context['httpServer'])
-      const consumer = ctx.inject(['systemPrompt'], async (promptCtx) => {
-        const assembly = await promptCtx.systemPrompt.assemble()
-        observedSections = assembly.sections
-      })
-
-      await ctx.plugin(SystemPrompt, { persona: 'You are a coding agent.' })
-      await consumer
-
-      expect(observedSections?.map(section => section.name)).toContain(HARNESS_SOURCE_SECTION)
-      expect(observedSections?.find(section => section.name === 'app:web-surface')?.text)
-        .toContain('http://127.0.0.1:3080')
-    } finally {
-      await ctx.fiber.dispose()
-    }
-  })
-})

apps/cli/tsconfig.json

@@ -11,6 +11,24 @@
     {
       "path": "../../vendor/cordis"
     },
+    {
+      "path": "../../vendor/loader"
+    },
+    {
+      "path": "../../vendor/include"
+    },
+    {
+      "path": "../../packages/ui/app-boot"
+    },
+    {
+      "path": "../../packages/bundle/base"
+    },
+    {
+      "path": "../../packages/bundle/headless"
+    },
+    {
+      "path": "../../packages/bundle/web-app"
+    },
     {
       "path": "../../packages/host/apiproxy"
     },
@@ -18,23 +36,35 @@
       "path": "../../packages/host/webserver"
     },
     {
-      "path": "../../packages/core/session"
+      "path": "../../packages/host/frontend-static"
     },
     {
-      "path": "../../packages/ui/app-boot"
+      "path": "../../packages/core/session"
     },
     {
-      "path": "../../packages/bash/bash-env"
+      "path": "../../packages/core/system-prompt"
     },
     {
-      "path": "../../packages/bash/tool-bash"
+      "path": "../../packages/core/tools"
     },
     {
       "path": "../../packages/util/paths"
     },
+    {
+      "path": "../../packages/mcp/mcp-client"
+    },
+    {
+      "path": "../../packages/support/loader-smoke"
+    },
     {
       "path": "../../packages/session-query/session-query-sqlite"
     },
+    {
+      "path": "../../packages/bash/bash-env"
+    },
+    {
+      "path": "../../packages/bash/tool-bash"
+    },
     {
       "path": "../../packages/client/connection"
     },

apps/web/tests/lifecycle-chrome.e2e.ts

@@ -26,6 +26,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/lifecycle-chrome', impor
 const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
 const HERO_EXPECTED = join(SNAPSHOT_DIR, 'hero.expected.md')
 const COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu.expected.md')
+const FUZZY_COMMAND_MENU_EXPECTED = join(SNAPSHOT_DIR, 'command-menu-fuzzy.expected.md')
 const PLAN_ACTIVE_EXPECTED = join(SNAPSHOT_DIR, 'plan-active.expected.md')
 // Post-reload golden: the same settled conversation rebuilt purely from
 // persistence + history — byte-equal rendering is exactly the recovery claim.
@@ -83,6 +84,12 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
     expect(Math.abs(
       launchedBox!.y + launchedBox!.height - typedBox!.y - typedBox!.height,
     )).toBeLessThan(1)
+    await input.fill('/cpt')
+    await expect.poll(() => menu.getByRole('option').allTextContents()).toEqual([
+      'compactCompact older conversation history',
+    ])
+    const fuzzySnapshot = await captureStableAria(page, '[role="listbox"]', scaffold.workspaceCwd)
+    await compareOrRefreshGolden(FUZZY_COMMAND_MENU_EXPECTED, fuzzySnapshot, MODE)
     await input.fill('')
     await expect.poll(() => menu.count()).toBe(0)
   })
@@ -258,7 +265,7 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
   it.skipIf(MODE === 'record')('keeps the fixture inventory closed', async () => {
     expect(tripwire.warnings).toEqual([])
     await assertFixtureInventory(SNAPSHOT_DIR, [
-      'session.jsonl', 'command-menu.expected.md', 'hero.expected.md', 'plan-active.expected.md', 'reloaded.expected.md',
+      'session.jsonl', 'command-menu.expected.md', 'command-menu-fuzzy.expected.md', 'hero.expected.md', 'plan-active.expected.md', 'reloaded.expected.md',
     ])
   })
 })

apps/web/tests/pin-browse-picker.overlay.yml

@@ -1,4 +1,4 @@
-# Loader overlay for the W5 real-host smoke (`dsh web --config`): pin the
+# Loader overlay for the W5 real-host smoke (`dsh web --patch`): pin the
 # in-browser directory picker. The shipped row is `-auto`, which resolves to
 # the native OS chooser on a loopback bind with a local display — an
 # interaction a Playwright page cannot drive, so the resolved backend would

apps/web/tests/scaffold.ts

@@ -1,7 +1,8 @@
 // Shared scaffold for the keyless browser e2e lane (Agent Note:
 // .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md).
-// Boots the REAL web composition — the shipped base plus web overlay through
-// the vendored Loader (the same include boot AppCLIEntry drives), patched the
+// Boots the REAL web composition — the dsh-base and dsh-web-app bundle
+// patches over the empty profile root through the vendored Loader (the same
+// layer stack the profile boot composes), patched the
 // snapshot way — so a real chromium exercises the real HTTP uplink/WebSocket
 // downlink, api-gateway, agent loop, tools, and persistence. Modes ride $DSH_SNAPSHOT:
 // replay (default, keyless: normally disables the llm-deepseek row and
@@ -11,7 +12,7 @@
 // masking its credential, without making a model call.
 //
 // Composition divergences from `dsh web`, all deliberate, all via include
-// patches after the shipped surface overlay, over the SAME tree (never a
+// patches after the shipped bundle layers, over the SAME tree (never a
 // second yml): temp persistenceRoot; host-level skill roots confined to the
 // temp workspace while project skill discovery remains real; workspace-context
 // disabled (recorded fixtures must not embed this repo's AGENTS.md);
@@ -22,9 +23,9 @@
 // (the plugin-row path discards the ReplayHandle; the direct install keeps
 // assertConsumed for the teardown fixture-consumption check).
 import { existsSync } from 'node:fs'
-import { mkdtemp, readFile, readdir, realpath, rm, utimes, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, readdir, realpath, rm, utimes, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
+import { join } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import type { Page } from 'playwright'
 import { expect } from 'vitest'
@@ -53,8 +54,8 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 // Empty type imports carry the httpServer/agents/sessionPersistence Context merges.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-agent'
-import { prepareWebRuntimeContext } from '../../cli/src/web.ts'
-import { DIST_INDEX, REPO_ROOT, requireDist } from './support.ts'
+import { addHarnessSourceSection, healProfilesModuleFallback } from '@deepseek-ai/dsh-app-boot'
+import { REPO_ROOT, requireDist } from './support.ts'
 
 /** Snapshot mode for the lane, from $DSH_SNAPSHOT (same vocabulary as the other snapshot suites). */
 export type WebSnapshotMode = 'replay' | 'record' | 'refresh'
@@ -70,9 +71,11 @@ export function webSnapshotMode(): WebSnapshotMode {
   throw new Error(`DSH_SNAPSHOT must be replay, record, or refresh; got ${JSON.stringify(value)}`)
 }
 
-/** The shipped composition under test: apps/cli's shared base and web overlay. */
-const CONFIG_PATH = join(REPO_ROOT, 'apps/cli/config/base.cordis.yml')
-const WEB_OVERLAY_PATH = join(REPO_ROOT, 'apps/cli/config/web.cordis.yml')
+/** The shipped composition under test: the dsh-base and dsh-web-app bundle patches over the empty profile root. */
+const BASE_PATCH_PATH = join(REPO_ROOT, 'packages/bundle/base/cordis.patch.yml')
+const WEB_PATCH_PATH = join(REPO_ROOT, 'packages/bundle/web-app/cordis.patch.yml')
+/** The installation anchor whose dependency surface the profile module fallback mirrors. */
+const INSTALL_ANCHOR = join(REPO_ROOT, 'apps/cli/package.json')
 
 // Replay publishes the provider catalog the gateway routes to (providers
 // mode, never catch-all: with llm-deepseek disabled no adapter exists, so a
@@ -117,7 +120,7 @@ export interface WebScaffold {
 export interface LaunchOptions {
   /**
    * Optional product overlay applied after the shipped Web surface and before
-   * the scaffold's hermetic test patches, matching AppCLIEntry's `--config`
+   * the scaffold's hermetic test patches, matching the launcher's `--patch`
    * ordering.
    */
   extraOverlayPath?: string
@@ -240,14 +243,17 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
   }
   if (maskDeepSeekCredential) Reflect.deleteProperty(process.env, 'DEEPSEEK_API_KEY')
 
-  // The include patch set — the same mechanism AppCLIEntry and the ACP
-  // snapshot overlay use, applied over the SAME shipped tree (a patch id that
-  // stops matching a row fails the boot sweep loudly instead of drifting).
-  const surfacePatches = loadOverlayPatches('web e2e scaffold', WEB_OVERLAY_PATH)
+  // The include patch set — the same layer stack the profile boot composes
+  // (bundle patches in dsh.profile.bundles order), applied over the SAME empty root (a
+  // patch id that stops matching a row fails the boot sweep loudly instead of
+  // drifting).
+  const basePatches = loadOverlayPatches('web e2e scaffold', BASE_PATCH_PATH)
+  const surfacePatches = loadOverlayPatches('web e2e scaffold', WEB_PATCH_PATH)
   const extraOverlayPatches = options.extraOverlayPath === undefined
     ? []
     : loadOverlayPatches('web e2e scaffold', options.extraOverlayPath)
   const patches: PatchOptions[] = [
+    ...basePatches,
     ...surfacePatches,
     ...extraOverlayPatches,
     { id: 'session-persistence-jsonl', config: { root: persistenceRoot } },
@@ -280,8 +286,11 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     { id: 'telemetry-otel', disabled: true },
     {
       id: 'webserver',
-      config: { host: '127.0.0.1', port: 0, distIndex: DIST_INDEX },
+      config: { host: '127.0.0.1', port: 0 },
     },
+    // The bundle's web-runtime row resolves the same built dist under test
+    // (apps/web IS @deepseek-ai/dsh-frontend); only the URL line is silenced.
+    { id: 'web-runtime', config: { mode: 'production', printUrl: false } },
     ...options.remoteAuthority === undefined
       ? []
       : [{ id: 'connection', config: { trustedHosts: [options.remoteAuthority] } }],
@@ -321,7 +330,15 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
   let replayHandle: ReplayHandle | undefined
   try {
     process.chdir(workspaceCwd)
-    ctx.baseUrl = pathToFileURL(join(resolve(CONFIG_PATH), '..')).href + '/'
+    // The production resolution shape: an empty profile root inside the temp
+    // harness home, with bare plugin names resolving through the flat module
+    // fallback the launcher heals under <home>/profiles.
+    healProfilesModuleFallback(INSTALL_ANCHOR, harnessHome)
+    const profileDir = join(harnessHome, 'profiles', 'scaffold')
+    await mkdir(profileDir, { recursive: true })
+    const rootConfig = join(profileDir, 'cordis.yml')
+    await writeFile(rootConfig, '[]\n')
+    ctx.baseUrl = pathToFileURL(profileDir).href + '/'
     // This direct Loader harness supplies the same root-path capability as app-boot.
     ctx.provide('dshHomePath', dshHomePath)
     await ctx.plugin(Loader)
@@ -329,10 +346,10 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // The shipped CLI deliberately has no dependency on this opt-in package.
     // Keep the Loader row real without broadening the product installation.
     if (options.cordisTools === true) ctx.loader.builtins['tool-cordis'] = ToolCordis
-    prepareWebRuntimeContext(ctx, REPO_ROOT, 'production')
+    ctx.inject(['systemPrompt'], (promptCtx) => { addHarnessSourceSection(promptCtx, REPO_ROOT) })
     await ctx.loader.create({
       name: 'cordis:include',
-      config: { path: pathToFileURL(resolve(CONFIG_PATH)).href, patches },
+      config: { path: pathToFileURL(rootConfig).href, patches },
     })
     await ctx.loader.await()
     assertEntriesLoaded(ctx, 'web e2e scaffold')

apps/web/tests/smoke-real.e2e.ts

@@ -487,7 +487,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
         '--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', String(port),
         // Pin the in-browser picker: the shipped `-auto` row would resolve to
         // the native OS chooser on this bind, and no page can drive that.
-        '--config', fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)),
+        '--patch', fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)),
       ],
       {
         cwd: sessionsDir,

apps/web/tests/snapshots/lifecycle-chrome/command-menu-fuzzy.expected.md

@@ -0,0 +1,3 @@
+- listbox "Trigger suggestions":
+  - text: Commands
+  - option "compact Compact older conversation history" [selected]

apps/web/tests/startup-auto-selection.e2e.ts

@@ -12,6 +12,9 @@
 // assembled application can show is that the path a user actually takes
 // reaches it: the real selection service, the real client session opening over
 // the real /api transport, and a real browser deciding what is painted.
+// The initial Workspace pick also records the resident Hero/composer nodes and
+// proves that opening the first blank Session fills the strict outlets without
+// replacing those nodes.
 //
 // The round-trip against a loopback host is far too fast to observe, so this
 // scenario HOLDS the `session.history` response open at the browser's network
@@ -55,9 +58,6 @@ describe('web e2e: startup auto-selection', () => {
     tripwire = watchConsole(page)
     await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
-    // A registered workspace is the precondition for auto-selection: the first
-    // load has nothing to select, so the reload below is the path under test.
-    await connectFreshWorkspace(page, scaffold.workspaceCwd, 'startup-auto-selection')
   }, 180_000)
 
   afterAll(async () => {
@@ -65,6 +65,48 @@ describe('web e2e: startup auto-selection', () => {
     await scaffold?.close()
   })
 
+  it('keeps the resident Hero and composer nodes when the first Workspace session appears', async () => {
+    onTestFailed(() => saveFailureShot(page, 'web-e2e-first-workspace-stable-tree'))
+    await page.locator(`${ROOT_PHASE}[data-phase="hero"]`).waitFor({ timeout: 15_000 })
+    await page.evaluate(() => {
+      const refs = {
+        root: document.querySelector('div[data-phase="hero"]'),
+        workspaceChip: document.querySelector('[aria-label="Choose workspace"]'),
+        scrollBody: document.querySelector('[data-conversation-scroll]'),
+        composerSeat: document.querySelector('[data-composer-seat]'),
+        textarea: document.querySelector('textarea'),
+      }
+      if (Object.values(refs).some(node => node === null)) throw new Error('incomplete initial Hero tree')
+      ;(window as unknown as { __heroTree: typeof refs }).__heroTree = refs
+    })
+
+    // A registered Workspace is the precondition for the reload case below;
+    // this first connection is also the no-Workspace → Workspace path.
+    await connectFreshWorkspace(page, scaffold.workspaceCwd, 'startup-auto-selection')
+
+    expect(await page.evaluate(() => {
+      const before = (window as unknown as { __heroTree: Record<string, Element> }).__heroTree
+      return {
+        phase: document.querySelector('div[data-phase]')?.getAttribute('data-phase'),
+        root: document.querySelector('div[data-phase="hero"]') === before.root,
+        workspaceChip: document.querySelector('[aria-label="Choose workspace"]') === before.workspaceChip,
+        scrollBody: document.querySelector('[data-conversation-scroll]') === before.scrollBody,
+        composerSeat: document.querySelector('[data-composer-seat]') === before.composerSeat,
+        textarea: document.querySelector('textarea') === before.textarea,
+        textareaEnabled: !(document.querySelector('textarea') as HTMLTextAreaElement).disabled,
+      }
+    })).toEqual({
+      phase: 'hero',
+      root: true,
+      workspaceChip: true,
+      scrollBody: true,
+      composerSeat: true,
+      textarea: true,
+      textareaEnabled: true,
+    })
+    expect(tripwire.pageErrors).toEqual([])
+  }, 120_000)
+
   it('keeps the hero and the composer on screen while the auto-selected blank session opens', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-startup-auto-selection'))
     // Runs before any page script on the reload below, so the first phase the

apps/web/vite.config.ts

@@ -18,10 +18,110 @@ function rejectStandaloneServe(): Plugin {
   }
 }
 
+/**
+ * Vendor-chunk membership, by exact npm package name — the heavy render
+ * families (math, highlight, markdown) that change only on dependency bumps.
+ * Only packages workspace code imports DIRECTLY need listing: their private
+ * transitive dependencies (oniguruma machinery, character tables, …) are
+ * imported solely by these and rollup's chunk coloring pulls them into
+ * vendor automatically. A dependency shared with index-side code falls back
+ * to index — a few kB of dilution, never a correctness problem. Anything not
+ * listed (react family, the vendored cordis workspace, tiny helpers like
+ * anser/clsx, all workspace code) stays in the default `index` chunk, so
+ * editing shell code re-hashes only index and returning clients keep the
+ * cached vendor chunk.
+ *
+ * Boundary invariant: every member must be react-free. A package that
+ * imports react/jsx-runtime must never be listed — rollup folds a module
+ * shared between the entry and a manual chunk into the manual chunk, so one
+ * react-importing member would drag the single shared react copy into
+ * vendor. The React side of markdown/math rendering is workspace code and
+ * rides index.
+ */
+const VENDOR_PACKAGES: ReadonlySet<string> = new Set([
+  // math
+  'katex',
+  // syntax highlight (@shikijs/langs is handled separately below —
+  // lazy grammars must not land here)
+  'shiki',
+  // markdown parse pipeline (micromark/mdast; the incremental React renderer
+  // over it is workspace code)
+  'mdast-util-from-markdown',
+  'mdast-util-gfm',
+  'mdast-util-math',
+  'micromark-core-commonmark',
+  'micromark-extension-gfm',
+  'micromark-extension-math',
+  'micromark-factory-space',
+  'micromark-util-character',
+  'micromark-util-classify-character',
+  'micromark-util-sanitize-uri',
+  'micromark-util-symbol',
+  'micromark-util-types',
+])
+
+/**
+ * Boot grammars statically imported by ui-primitives' highlight.ts
+ * (`@shikijs/langs/typescript` → `dist/typescript.mjs`, etc.). They live in
+ * the same package as the lazy read-card grammars, but unlike those they are
+ * part of the initial load and belong in the vendor chunk; the lazy ones must
+ * stay unassigned so each keeps its own on-demand chunk.
+ */
+const BOOT_GRAMMAR_FILES: readonly string[] = [
+  'dist/typescript.mjs',
+  'dist/shellscript.mjs',
+  'dist/json.mjs',
+]
+
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces today). */
+const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
+
+/** npm package name of a resolved module id (the segment after the LAST `node_modules/` — pnpm nests the real package under an inner node_modules). */
+function npmPackageOf(id: string): string | undefined {
+  const parts = id.split('/node_modules/')
+  if (parts.length === 1) return undefined
+  const [first, second] = parts[parts.length - 1].split('/')
+  if (first.startsWith('.')) return undefined // .pnpm store segment, not a package
+  if (first.startsWith('@')) return second === undefined ? undefined : `${first}/${second}`
+  return first
+}
+
 export default defineConfig({
   plugins: [rejectStandaloneServe(), react()],
   build: {
     sourcemap: true,
+    rollupOptions: {
+      output: {
+        // Output layout: the two main chunks stay at assets/ root; lazy
+        // @shikijs/langs grammar chunks group under assets/langs/; fonts
+        // (today all KaTeX faces referenced by vendor.css) group under
+        // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
+        // .map next to its js and references it by bare relative filename.
+        chunkFileNames(chunk): string {
+          // Grammar chunks are recognized by their member modules, not the
+          // facade: shared embedded-grammar chunks (e.g. html+javascript,
+          // split out because php/ruby/mdx embed them) have no facade at all.
+          // index and vendor are excluded by name — vendor legitimately
+          // carries the three boot grammars.
+          if (chunk.name === 'index' || chunk.name === 'vendor') return 'assets/[name]-[hash].js'
+          const isLangChunk = chunk.moduleIds.some(id => id.includes('/node_modules/@shikijs/langs/'))
+          return isLangChunk ? 'assets/langs/[name]-[hash].js' : 'assets/[name]-[hash].js'
+        },
+        assetFileNames(asset): string {
+          const fileName = asset.names[0] ?? ''
+          const isFont = FONT_EXTENSIONS.some(ext => fileName.endsWith(ext))
+          return isFont ? 'assets/fonts/[name]-[hash][extname]' : 'assets/[name]-[hash][extname]'
+        },
+        manualChunks(id: string): string | undefined {
+          const pkg = npmPackageOf(id)
+          if (pkg === undefined) return undefined // workspace + vendored cordis: index
+          if (pkg === '@shikijs/langs') {
+            return BOOT_GRAMMAR_FILES.some(file => id.endsWith(`/${file}`)) ? 'vendor' : undefined
+          }
+          return VENDOR_PACKAGES.has(pkg) ? 'vendor' : undefined
+        },
+      },
+    },
   },
   resolve: {
     // Workspace packages resolve to SOURCE: package.json exports point at lib

docs/architecture.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 docs/architecture.md
-architecture.md: 9b84c1482cb379fd796e21db45f128ba49750c54
-architecture.zh.md: 84708fcae24623e50b0157782cf459c35a55844b
+architecture.md: 40c20a1c9eeabe5ecbbc6edacde81c20071b8a04
+architecture.zh.md: 6fddaa883775cf8345aba01af52575c0f0e1aaa0

docs/architecture.md

@@ -83,7 +83,7 @@ forever:
   -> 'turn/start'
   claim next-step input plus one next-turn message
   -> emit agent/inbox/claimed({ message, turn }) for each claimed message
-  -> agent/pre-step(messages, { turn, step, signal })
+  -> agent/pre-step({ agent, messages, turn, step, signal })
     reject, empty input, cancellation, or listener failure
       -> the claimed batch stays removed; close the no-step turn; stop the driver
     enter -> step loop:
@@ -112,7 +112,7 @@ idle inject:
 
 Each step assembles ordered prompt sections, tool schemas, and variables; unknown references fail the turn. `dsh-system-prompt` owns identity and persona; the loop supplies `provider`, `model`, and `cwd` ([prompt ownership](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
 
-`inject()` queues non-waking `next-step` context; an idle driver leaves it pending until `followup()` or `steer()` wakes the driver. Post-tool `additionalContexts` use the same inbox. `agent/pre-step` receives the exclusive claimed batch and upcoming turn, step, and signal. Reject opens no step; enter supplies the complete batch appended after `step/start`. Empty tool continuations still traverse the waterfall, whose final value settles all rewrites.
+`inject()` queues non-waking `next-step` context; an idle driver leaves it pending until `followup()` or `steer()` wakes the driver. Post-tool `additionalContexts` use the same inbox. The `agent/pre-step` payload carries the exclusive claimed batch and the upcoming turn, step, and signal. Reject opens no step; enter supplies the complete batch appended after `step/start`. Empty tool continuations still traverse the waterfall, whose final value settles all rewrites.
 
 Pruning precedes summaries; overflow retries require durable progress. `agent/request-error` may authorize a same-step retry of the frozen prompt; cancellation wins. Adapter `retryPolicy` bounds normal mode, while always mode retries after specialized recovery ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry foundation](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md), [provider policy](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)). The generated [agent lifecycle](agent-lifecycle.md) owns exact event order, and the [agent-loop README](../packages/core/agent-loop/README.md) owns queue, steering, retry, and cancellation mechanics.
 

docs/architecture.zh.md

@@ -83,7 +83,7 @@ forever:
   -> 'turn/start'
   claim next-step input plus one next-turn message
   -> emit agent/inbox/claimed({ message, turn }) for each claimed message
-  -> agent/pre-step(messages, { turn, step, signal })
+  -> agent/pre-step({ agent, messages, turn, step, signal })
     reject, empty input, cancellation, or listener failure
       -> the claimed batch stays removed; close the no-step turn; stop the driver
     enter -> step loop:
@@ -112,7 +112,7 @@ idle inject:
 
 每个步骤都会组装有序的提示词片段、工具 schema 和变量；未知引用会使该轮次失败。`dsh-system-prompt` 负责身份和角色设定；循环提供 `provider`、`model` 和 `cwd`（[提示词归属](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)）。
 
-`inject()` 将不会唤醒驱动器的上下文排入 `next-step`；空闲驱动器会让它保持待处理，直至 `followup()` 或 `steer()` 唤醒。工具执行后的 `additionalContexts` 使用同一个 inbox。`agent/pre-step` 接收独占的已领取批次，以及即将使用的轮次、步骤和信号。拒绝则不进入步骤；进入则提供在 `step/start` 后追加的完整批次。空的工具续跑仍会经过 waterfall，其最终值一次性结算所有改写。
+`inject()` 将不会唤醒驱动器的上下文排入 `next-step`；空闲驱动器会让它保持待处理，直至 `followup()` 或 `steer()` 唤醒。工具执行后的 `additionalContexts` 使用同一个 inbox。`agent/pre-step` 的 payload 携带独占的已领取批次，以及即将使用的轮次、步骤和信号。拒绝则不进入步骤；进入则提供在 `step/start` 后追加的完整批次。空的工具续跑仍会经过 waterfall，其最终值一次性结算所有改写。
 
 裁剪先于摘要；溢出重试必须取得持久进展。`agent/request-error` 可以授权使用冻结提示词进行同步骤重试；取消优先。适配器的 `retryPolicy` 使 normal mode 保持有界，always mode 则在专门恢复后重试（[压缩](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md)、[重试基础](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)、[提供方策略](../.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md)）。精确事件顺序由生成的 [agent 生命周期](agent-lifecycle.md)定义；队列、steering、重试与取消机制由 [agent-loop README](../packages/core/agent-loop/README.md)定义。
 

docs/config-catalog.md

@@ -439,6 +439,20 @@ export interface Config {
 
 Source: [`packages/credentials/credentials-local/src/index.ts:26`](../packages/credentials/credentials-local/src/index.ts)
 
+## `@deepseek-ai/dsh-frontend-static`
+
+Requires: `httpServer`
+
+```ts config-catalog
+/** Plugin config: the dist anchor. */
+export interface Config {
+  /** Absolute path of index.html inside the dist root. */
+  distIndex: string
+}
+```
+
+Source: [`packages/host/frontend-static/src/index.ts:28`](../packages/host/frontend-static/src/index.ts)
+
 ## `@deepseek-ai/dsh-fs-local`
 
 ```ts config-catalog
@@ -483,6 +497,20 @@ export interface Config {
 
 Source: [`packages/goal/goal/src/index.ts:114`](../packages/goal/goal/src/index.ts)
 
+## `@deepseek-ai/dsh-headless`
+
+Requires: `apiProxy` · `httpServer`
+
+```ts config-catalog
+/** Plugin config: the task, patched in by the launcher. */
+export interface Config {
+  /** The prompt text for the single turn. */
+  task: string
+}
+```
+
+Source: [`packages/bundle/headless/src/index.ts:33`](../packages/bundle/headless/src/index.ts)
+
 ## `@deepseek-ai/dsh-hooks-claude`
 
 Requires: `bash`
@@ -577,18 +605,16 @@ Source: [`packages/host/directory-picker-browse/src/index.ts:181`](../packages/h
 ## `@deepseek-ai/dsh-host-webserver`
 
 ```ts config-catalog
-/** Gateway config: listen address plus the static dist anchor (injected by the composing app, never self-resolved). */
+/** Gateway config: the listen address. */
 export interface Config {
   /** Listen host; the two supported values are loopback and all-interfaces. */
   host: '127.0.0.1' | '0.0.0.0'
   /** Listen port; zero requests an OS-assigned port. */
   port: number
-  /** Absolute path of index.html inside the static root (dist location is workspace knowledge of the app). */
-  distIndex: string
 }
 ```
 
-Source: [`packages/host/webserver/src/index.ts:47`](../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:45`](../packages/host/webserver/src/index.ts)
 
 ## `@deepseek-ai/dsh-invariants`
 
@@ -2216,6 +2242,39 @@ export interface WebServiceConfig {
 
 Source: [`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
 
+## `@deepseek-ai/dsh-web-app`
+
+Requires: `httpServer`
+
+```ts config-catalog
+/** 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[]
+}
+
+/** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
+export type WebMode = 'production' | 'development'
+```
+
+Source: [`packages/bundle/web-app/src/index.ts:32`](../packages/bundle/web-app/src/index.ts)
+
 ## `@deepseek-ai/dsh-web-fetch-local`
 
 Requires: `web`
@@ -2445,6 +2504,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-agent-loop-testkit` ([`packages/support/agent-loop-testkit/src/index.ts`](../packages/support/agent-loop-testkit/src/index.ts))
 - `@deepseek-ai/dsh-app-boot` ([`packages/ui/app-boot/src/index.ts`](../packages/ui/app-boot/src/index.ts))
 - `@deepseek-ai/dsh-atomic-write` ([`packages/util/atomic-write/src/index.ts`](../packages/util/atomic-write/src/index.ts))
+- `@deepseek-ai/dsh-base` ([`packages/bundle/base/src/index.ts`](../packages/bundle/base/src/index.ts))
 - `@deepseek-ai/dsh-brand` ([`packages/util/brand/src/index.ts`](../packages/util/brand/src/index.ts))
 - `@deepseek-ai/dsh-client-schema-form` ([`packages/client/schema-form/src/index.ts`](../packages/client/schema-form/src/index.ts))
 - `@deepseek-ai/dsh-client-test-runtime` ([`packages/client/test-runtime/src/index.ts`](../packages/client/test-runtime/src/index.ts))

docs/cordis-catalog/events.md

@@ -24,16 +24,16 @@ A fully configured agent and live session were published. Setup is composition-o
  * Synchronous listener failure vetoes publication, while returned-promise
  * rejection is reported. Detach requested during dispatch waits until every
  * creation listener has observed the stable entry.
- * @param agent - the newly registered agent with its live session and completed setup.
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:178`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:154`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -44,16 +44,16 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
  * An agent left the registry; AgentLoop emits this after driver quiescence
  * and scoped-registration unwind, but before session detachment. Custom
  * registry users own their driver-ordering contract.
- * @param agent - the exact agent removed from the registry.
+ * @param payload.agent - the exact agent removed from the registry.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:187`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -63,19 +63,19 @@ A step or turn errored. The machine reports a failure here even when the error h
 /**
  * A step or turn errored. The machine reports a failure here even when
  * the error has no in-turn position for a durable record.
- * @param agent - the agent whose turn errored.
- * @param turn - the turn in which the failure surfaced.
- * @param step - the step at which the failure surfaced.
- * @param error - the failure, verbatim.
+ * @param payload.agent - the agent whose turn errored.
+ * @param payload.turn - the turn in which the failure surfaced.
+ * @param payload.step - the step at which the failure surfaced.
+ * @param payload.error - the failure, verbatim.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:302`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/claimed` — emit
 
@@ -86,17 +86,18 @@ One message left the inbox inside its open turn. If the proposed step is rejecte
  * One message left the inbox inside its open turn. If the proposed step
  * is rejected, the claimed message ends here: it is neither discarded nor
  * re-emitted as a user/message, and the turn closes without a step.
- * @param agent - the agent whose inbox changed.
- * @param event - the claimed message and owning turn.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the claimed message.
+ * @param payload.turn - the owning turn.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/claimed'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage; turn: number }): void
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:215`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:192`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/discarded` — emit
 
@@ -105,17 +106,17 @@ One message was discarded from the live inbox.
 ```ts cordis-catalog
 /**
  * One message was discarded from the live inbox.
- * @param agent - the agent whose inbox changed.
- * @param event - the discarded message.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the discarded message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/discarded'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage }): void
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:223`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:200`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/inserted` — emit
 
@@ -124,17 +125,17 @@ One message entered the live inbox.
 ```ts cordis-catalog
 /**
  * One message entered the live inbox.
- * @param agent - the agent whose inbox changed.
- * @param event - the inserted message.
+ * @param payload.agent - the agent whose inbox changed.
+ * @param payload.message - the inserted message.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/inbox/inserted'(this: Scoped<Agent>, agent: Agent, event: { message: UserMessage }): void
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:205`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:181`](../../packages/core/agent/src/types.ts)
 
 ### `agent/pre-step` — waterfall
 
@@ -144,18 +145,20 @@ Reject a proposed step or replace the messages that enter it. Calling `next()` p
 /**
  * Reject a proposed step or replace the messages that enter it. Calling
  * `next()` preserves the current messages.
- * @param agent - the agent proposing the step.
- * @param messages - messages removed from the inbox for this step.
- * @param context - proposed turn and step coordinates plus cancellation.
+ * @param payload.agent - the agent proposing the step.
+ * @param payload.messages - messages removed from the inbox for this step.
+ * @param payload.turn - the turn that will own the step.
+ * @param payload.step - the step proposed by the loop.
+ * @param payload.signal - the current turn's cancellation signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/pre-step'(this: Scoped<Agent>, agent: Agent, messages: UserMessage[], context: PreStepContext, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [PreStepContext](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
+Types: [Agent](../core-data-structures/core.md) · [PreStepDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:247`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -167,19 +170,19 @@ Replace the frozen call configuration. `await next()` yields the config the mach
  * the machine would use (agent options on the first request, the logged
  * header afterwards); return a replacement to switch. Model-visible
  * content must use logged channels; this seam cannot mutate messages.
- * @param agent - the agent making the model call.
- * @param turn - the open turn number.
- * @param step - the step whose request this is.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent making the model call.
+ * @param payload.turn - the open turn number.
+ * @param payload.step - the step whose request this is.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
 */
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:260`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request-error` — waterfall
 
@@ -191,18 +194,22 @@ Handle one failed model-request attempt before the loop retries or closes its st
  * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
  * when it owns recovery, or calls `next()` to delegate. The default
  * `undefined` leaves the failure terminal.
- * @param agent - the agent whose request failed.
- * @param context - request coordinates, provider, normalized failure, and serving policy.
- * @param signal - the turn abort signal.
+ * @param payload.agent - the agent whose request failed.
+ * @param payload.turn - the turn containing the failed request.
+ * @param payload.step - the step containing the failed request attempt.
+ * @param payload.provider - the provider selected for the failed request.
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
+ * @param payload.signal - the turn abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode waterfall
  */
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, context: RequestFailureContext, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
+'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>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [RequestFailureContext](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
+Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:272`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:255`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -214,17 +221,17 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
  * `agent.inject()` to seed model-facing context. This is a notification, not
  * a veto; disposal requested by a lifecycle owner is rechecked before the
  * driver starts.
- * @param agent - the agent whose session lifecycle began.
- * @param source - why the session started (fresh startup, resume, …).
+ * @param payload.agent - the agent whose session lifecycle began.
+ * @param payload.source - why the session started (fresh startup, resume, …).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:235`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:212`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -235,17 +242,17 @@ Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running`
  * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
  * `running` synchronously after reserving cancellation; `idle` means no
  * driver remains scheduled or active.
- * @param agent - the agent whose status flipped.
- * @param status - the status just entered (the transition's destination).
+ * @param payload.agent - the agent whose status flipped.
+ * @param payload.status - the status just entered (the transition's destination).
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode emit
  */
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:197`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:173`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-stopping` — serial
 
@@ -263,18 +270,18 @@ The turn is about to close: the model owes no response (no live tool calls, no f
  * never short-circuits already-submitted next-step work: same-step
  * `additionalContexts` or racing steering still runs, and the turn
  * closes only when that inbox drains.
- * @param agent - the agent whose turn is at its stop boundary.
- * @param turn - the turn about to close.
- * @param signal - the current turn's explicit abort signal.
+ * @param payload.agent - the agent whose turn is at its stop boundary.
+ * @param payload.turn - the turn about to close.
+ * @param payload.signal - the current turn's explicit abort signal.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
  * @mode serial
  */
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:290`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:273`](../../packages/core/agent/src/types.ts)
 
 ## `agent-loop/*`
 
@@ -288,11 +295,11 @@ A declarative agent entry failed before it could publish a live agent. Consumers
  * 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
 ```
 
 Types: [SessionId](../core-data-structures/core.md)
@@ -456,11 +463,11 @@ Goal mutation accepted by one live agent. The matching `goal/change` session eve
  * Goal mutation accepted by one live agent. The matching `goal/change`
  * session event has already committed. Listener failures are contained.
  * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param agent - agent whose session owns the goal.
- * @param change - fresh current projection or clear tombstone.
+ * @param payload.agent - agent whose session owns the goal.
+ * @param payload.change - fresh current projection or clear tombstone.
  * @mode emit
  */
-'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, agent: Agent, change: GoalChanged): void
+'goal/changed'(this: import('@deepseek-ai/dsh-scope').Scoped<Agent>, payload: { agent: Agent; change: GoalChanged }): void
 ```
 
 Types: [Agent](../core-data-structures/core.md) · [GoalChanged](../core-data-structures/goal.md) · [Scoped](../core-data-structures/scope.md)

docs/cordis-catalog/services.md

@@ -769,7 +769,7 @@ Source: [`packages/goal/goal/src/index.ts:181`](../../packages/goal/goal/src/ind
 
 ## `ctx.httpServer` — `HttpServerService`
 
-The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the static dist fallback answers anything not yet claimed during the boot window). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
+The web-shape HTTP carrier service. Activation listens immediately (route registration order carries no request-facing semantics: named routes are composed to be disjoint, and the fallback seat answers anything not yet claimed during the boot window — 404 until its owner registers). A listen failure throws out of init — a FAILED fiber the boot's fail-loud sweep reports.
 
 ```ts cordis-catalog
 /**
@@ -789,15 +789,33 @@ register(route: WebRoute): () => void
 registerUpgrade(route: WebUpgradeRoute): () => void
 
 /**
- * Register an index.html transform, applied to every index response in
- * registration order.
+ * Claim the fallback seat: the handler answering every request no named
+ * route matches (the SPA dist server in the shipped Web composition). One
+ * owner only — a second registration throws, because two fallbacks cannot
+ * compose.
+ * @param handler - owns the full response lifecycle of unmatched requests.
+ * @returns the disposer releasing the seat.
+ */
+registerFallback(handler: WebRoute['handler']): () => void
+
+/**
+ * Register an index.html transform, applied by the fallback owner to every
+ * index response ({@link applyIndexTaps}) in registration order.
  * @param transform - pure html-to-html function.
  * @returns the disposer removing the transform.
  */
 tapIndex(transform: (html: string) => string): () => void
+
+/**
+ * Run an index.html body through the registered taps in registration order
+ * — called by the fallback owner on every index response it renders.
+ * @param html - the raw index.html body.
+ * @returns the transformed body.
+ */
+applyIndexTaps(html: string): string
 ```
 
-Source: [`packages/host/webserver/src/index.ts:63`](../../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:60`](../../packages/host/webserver/src/index.ts)
 
 ## `ctx.invariants` — `InvariantService`
 

docs/cordis-tutorial/01-first-plugin.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 docs/cordis-tutorial/01-first-plugin.md
-01-first-plugin.md: c9f4889398222793005fce6832d0917a20d0be30
-01-first-plugin.zh.md: b9d6994fad8e26cdfc52db0fbcef5631d5d53b03
+01-first-plugin.md: c44e7f95fb11d5337ecfaf4251c8b2f2b9b14680
+01-first-plugin.zh.md: 9461884d312ad2e64af12fa42952a986e1ad5d8a

docs/cordis-tutorial/01-first-plugin.md

@@ -48,7 +48,7 @@ The process exits on its own once nothing is left running. What happened:
 2. The Loader read `cordis.yml`, resolved `./hello.ts`, and mounted it as a child plugin.
 3. Cordis called your `apply(ctx)`.
 
-There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [`dsh` base](../../apps/cli/config/base.cordis.yml), for example, is a longer plugin composition that deployment overlays patch.
+There is no framework bootstrap code in your file: a plugin describes what it contributes, and `cordis.yml` composes the application. The [`dsh` base](../../packages/bundle/base/cordis.patch.yml), for example, is a longer plugin composition that deployment overlays patch.
 
 ## The two other plugin shapes
 

docs/cordis-tutorial/01-first-plugin.zh.md

@@ -48,7 +48,7 @@ hello from my first plugin
 2. Loader 读取 `cordis.yml`，解析 `./hello.ts`，然后将其作为子插件挂载。
 3. Cordis 调用你的 `apply(ctx)`。
 
-你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[`dsh` base](../../apps/cli/config/base.cordis.yml) 就是一份更长的插件组合，由部署 overlay 对它进行修补。
+你的文件中没有框架启动代码：插件描述自己的贡献，`cordis.yml` 则组合应用。例如，[`dsh` base](../../packages/bundle/base/cordis.patch.yml) 就是一份更长的插件组合，由部署 overlay 对它进行修补。
 
 ## 其他两种插件形态