Merge branch 'feat/subagent-settlement-delivery' into feat/subagent-list-agents-vocabulary

packages/acp/acp/src/index.ts

@@ -252,6 +252,10 @@ export function apply(ctx: Context, config: AcpConfig): void {
         assertOpen()
         validateSessionParams(params)
         const sessionId = SessionId(randomUUID())
+        // No preset composition: the ACP bundle keeps the model-facing rows in
+        // the host plane, so this agent reads them from the global layer. A
+        // deployment that configures a roster has to join one here first
+        // (@deepseek-ai/dsh-agent-presets README, "Composing a child agent").
         const handle = await agents.create({
           sessionId,
           meta: { cwd: params.cwd },

packages/bundle/headless/src/index.ts

@@ -106,6 +106,10 @@ async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
   if (agents === undefined || defaultModel === undefined || sessions === undefined) return
 
   const selection = defaultModel.currentSelection()
+  // This bundle composes no preset roster, so the model-facing rows sit in the
+  // host plane and the agent reads them from the global layer. A deployment
+  // that DOES configure one has to join it here first
+  // (@deepseek-ai/dsh-agent-presets README, "Composing a child agent").
   const { agent } = await agents.create({
     sessionId: SessionId(`session-${randomUUID()}`),
     meta: { cwd: process.cwd() },

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

@@ -309,8 +309,12 @@
 - id: plan-mode
   disabled: true
 
-- id: token-meter
-  disabled: true
+# The token METER stays on the host plane; only the compaction backend that
+# reads it moves. It owns the context-meter projection units, and that table is
+# process-wide, so preset ownership would make the meter a function of which
+# presets happen to be mounted rather than a per-session fact. Same criterion as
+# `tasks` and `goals`; the reasoning has one home in
+# `.agents/notes/implemented/architecture/2026-08-10-host-plane-ownership-after-presets.md`.
 
 - id: compact-basic
   disabled: true

packages/client/ui-agent-preset/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/ui-agent-preset/README.md
-README.md: 008066114e9c49e5c74299979e24c27a4c9621c9
-README.zh.md: e07d5994ae196cd03be7818fe4ade1aafda9aa55
+README.md: 3b0db5a3eedca256a00b65a3bd2738f22c0eb62e
+README.zh.md: 6f3c350f973119c201572f2c03145338b5cc5b00

packages/client/ui-agent-preset/README.md

@@ -36,6 +36,8 @@ A fourth surface, its own settings page (`settings.section` id `agent-presets`,
 
 The browser edits no composition text. Editing YAML in a web textarea was a weak surface (no completion, no highlighting, no diff), so a new preset is a host-side copy of an existing one — the dialog collects an id (it becomes the directory name, which is why it must be named up front and cannot change later) and an optional display name, and `{ from, id, name? }` is all that crosses the wire. Everything else — description, composition, skills — is edited in the preset's own files, and the page's other job is getting the user TO those files: the copy completes by opening the new directory, and every custom row keeps a location action. Where the host has no desktop opener (`hasDocument: false` on the roster; remote and container deployments), the same actions answer the directory as text on the row instead of offering a button that would spawn into nothing.
 
+A preset publishes its own description, of any length, and the grid sizes every card row alike — so an unbounded description would set the height of the whole roster. Cards clamp it to four lines and offer the rest in a tooltip, attached only while the text is actually cut off. The clamp is CSS, so the whole description stays in the accessibility tree whatever the card shows.
+
 A shipped preset opens in the read-only viewer. It is the known-good composition a copy starts from, so reading it is the point; it offers no location and no delete — its install is overwritten by upgrades and is not the user's to manage. The intro carries the guidance a create button used to imply: duplicate an existing preset and make it yours, or let the agent draft one in Creator mode.
 
 Beside copying sits the conversational entry: when the roster carries the self-referential `cordis` preset, a dashed add-card (the Models page's affordance) stages it and starts a new session — the section closes the settings panel through the shell's owner-prop `close` and the new-session chip's own applier composes the blank session the workspace flow produces. The seat keeps a late roster load from regressing the display: staged pick first, then the composition the current session already carries, then the deployment default.
@@ -44,7 +46,7 @@ The dialog mirrors the host's own containment rule (`[a-z0-9][a-z0-9-]*`) and re
 
 Deleting removes the preset directory. Sessions already composed from it keep running — a composition is mounted once at session creation and nothing re-reads the file.
 
-A roster row carrying `broken` (the host's shape check found the composition missing or unloadable) renders as a marked card: red border, a Broken badge, the reason verbatim, the body disabled — it cannot become the default — and duplication disabled, since a copy of a broken preset is another broken preset. A broken custom row keeps its location and delete actions, because the files are where it gets fixed and deleting is how a ghost directory (composition deleted by hand, directory still blocking the id) is cleared; a broken shipped row withholds the viewer too — there is no readable composition to show. The two pickers (the General row and the new-session chip) drop broken presets entirely: they choose the NEXT session's composition, and offering one that cannot compose would only defer the failure to the session start.
+A roster row carrying `broken` (the host's shape check found the composition missing or unloadable) renders as a marked card: red border, a "Failed to load" badge (what discovery observed, not a claim that the files are damaged — the usual cause is a composition the user just edited or deleted), the reason verbatim, the body disabled — it cannot become the default — and duplication disabled, since a copy of a broken preset is another broken preset. A broken custom row keeps its location and delete actions, because the files are where it gets fixed and deleting is how a ghost directory (composition deleted by hand, directory still blocking the id) is cleared; a broken shipped row withholds the viewer too — there is no readable composition to show. The two pickers (the General row and the new-session chip) drop broken presets entirely: they choose the NEXT session's composition, and offering one that cannot compose would only defer the failure to the session start.
 
 Setting the default writes the `agent-presets` settings namespace, which the host exposes to configuration clients ([`dsh-apiproxy`](../../host/apiproxy/README.md) keeps an explicit allowlist — a namespace outside it makes a picker move and then silently forget).
 

packages/client/ui-agent-preset/README.zh.md

@@ -36,6 +36,8 @@ preset 文件提供一套未国际化的 `name` 与 `description`，Web 将其
 
 浏览器不再编辑任何组装文本。在网页文本域里编 YAML 是弱功能（无补全、无高亮、无 diff），因此新 preset 是宿主端对既有 preset 的一次复制——对话框只收集一个 id（它将成为目录名，所以必须当场取好、事后无法更改）与一个可选显示名，跨越传输层的只有 `{ from, id, name? }`。其余一切——描述、组装、skills——都在 preset 自己的文件里编辑，而本页的另一职责正是把用户送到那些文件面前：复制以打开新目录作为收尾，每张自定义卡片也保有一个位置操作。宿主没有桌面打开器时（名单上的 `hasDocument: false`；远程与容器部署），同样的操作改为把目录以文本显示在卡片上，而不是提供一个点了没反应的按钮。
 
+preset 自行发布描述，长度不限，而网格让每一行卡片等高——因此不加约束的描述会决定整份名单的高度。卡片把描述截断为四行，其余内容由 tooltip 承载，且仅在文本确实被裁切时才挂载。截断由 CSS 完成，因此无论卡片显示多少，完整描述始终留在无障碍树中。
+
 随附 preset 在只读查看器中打开。它是副本据以出发的已知良好组装，因此能读到它正是意义所在；它不提供位置也不提供删除——它的安装目录会被升级覆盖，不归用户管理。开篇引导语承担了从前创建按钮所暗示的信息：复制一份既有预设改成自己的，或用「创造模式」让 Agent 帮你创建。
 
 复制旁边是对话式入口：名单携带自指的 `cordis` preset 时，一张虚线添加卡（模型页的同款样式）会暂存它并开启新会话——分区经外壳的 owner-prop `close` 关闭设置面板，新会话 chip 自己的应用器负责组装工作区流程产出的空白会话。seat 会防止晚到的名单加载回退显示：暂存选择优先，其次是当前会话已携带的组装，最后才是部署默认值。
@@ -44,7 +46,7 @@ preset 文件提供一套未国际化的 `name` 与 `description`，Web 将其
 
 删除会移除整个 preset 目录。已据其组装的会话继续运行——组装在会话创建时挂载一次，此后没有任何东西会重新读取该文件。
 
-名单行携带 `broken`（宿主的形状检查发现组装缺失或不可加载）时渲染为标记卡片：红色边框、「已损坏」徽记、原样展示的原因、卡片主体禁用——它不能成为默认——复制也禁用，因为损坏 preset 的副本只是又一个损坏的 preset。损坏的自定义行保留位置与删除动作：文件正是修复它的地方，而删除正是清掉幽灵目录（组装文件被手动删除、目录仍占着 id）的方式；损坏的内置行连查看器也不提供——没有可读的组装可展示。两个选择器（通用设置行与新会话 chip）则完全不列出损坏的 preset：它们选的是下一个会话的组装，列出无法组装的选项只会把失败推迟到会话启动。
+名单行携带 `broken`（宿主的形状检查发现组装缺失或不可加载）时渲染为标记卡片：红色边框、「加载失败」徽记（discovery 观察到的事实，而非断言文件已损坏——常见起因是用户刚编辑或删除了组装文件）、原样展示的原因、卡片主体禁用——它不能成为默认——复制也禁用，因为损坏 preset 的副本只是又一个损坏的 preset。损坏的自定义行保留位置与删除动作：文件正是修复它的地方，而删除正是清掉幽灵目录（组装文件被手动删除、目录仍占着 id）的方式；损坏的内置行连查看器也不提供——没有可读的组装可展示。两个选择器（通用设置行与新会话 chip）则完全不列出损坏的 preset：它们选的是下一个会话的组装，列出无法组装的选项只会把失败推迟到会话启动。
 
 设置默认值写入的是 `agent-presets` settings 命名空间，宿主需将其暴露给配置客户端（[`dsh-apiproxy`](../../host/apiproxy/README.md) 维护一份显式白名单——不在其中的命名空间会让选择器动一下然后悄悄忘记）。
 

packages/client/ui-agent-preset/src/client/AgentPresetSection.module.css

@@ -161,15 +161,28 @@
   color: var(--dsw-alias-bg-layer-3);
 }
 
+/* Bounded to four lines. A preset publishes its own description, so one long
+   one would otherwise stretch every card in its grid row (`.cards` sizes rows
+   1fr). Clamping is CSS alone: the whole text stays in the DOM for assistive
+   tech, and the card offers it on hover when it is actually cut off. The
+   description does not grow to fill the card — `-webkit-line-clamp` on a
+   flex-stretched box leaves the clamp height and the box height disagreeing,
+   so `.cardId` takes the free space with an auto margin instead. */
 .cardDesc {
   font-size: 13px;
   line-height: 1.55;
   color: var(--dsw-alias-label-secondary);
-  flex: 1;
   min-height: 42px;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 4;
+  overflow: hidden;
+  /* A user-authored description may carry an unbreakable path or URL. */
+  overflow-wrap: anywhere;
 }
 
 .cardId {
+  margin-top: auto;
   font-family: var(--dsw-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
   font-size: 11px;
   color: var(--dsw-alias-label-dimmed);

packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx

@@ -10,10 +10,10 @@
  * mounted once at session creation and nothing re-reads the file.
  */
 
-import { useEffect } from 'react'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import {
-  Button, IconBrowseOutline16, IconCopyOutline16, IconFolderOpenOutline16, IconPlusOutline16, IconTrashOutline16, Modal,
+  Button, IconBrowseOutline16, IconCopyOutline16, IconFolderOpenOutline16, IconPlusOutline16, IconTrashOutline16, Modal, Tooltip,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
@@ -137,6 +137,39 @@ function CopyDialog({ state, t, actions }: CopyDialogProps): ReactNode {
   )
 }
 
+/**
+ * Render one card's description, clamped by CSS and offered in full on hover.
+ * The tooltip is attached only while the text is actually cut off, so a short
+ * description does not answer a hover with a bubble repeating the card.
+ * @param props.text - the description as rendered, already localized.
+ * @returns the description element, tooltip-anchored while it overflows.
+ */
+function CardDescription({ text }: { text: string }): ReactNode {
+  const ref = useRef<HTMLSpanElement | null>(null)
+  const [truncated, setTruncated] = useState(false)
+  useLayoutEffect(() => {
+    const el = ref.current
+    /* v8 ignore next -- the ref is attached before layout effects run. */
+    if (el === null) return
+    const measure = () => { setTruncated(el.scrollHeight > el.clientHeight) }
+    measure()
+    // Card width follows the settings pane, which resizes with the window.
+    if (typeof ResizeObserver === 'undefined') return
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => { observer.disconnect() }
+  }, [text])
+  return (
+    // Capped near the card's own width: the default half-viewport bubble would
+    // spill a description out of the settings dialog and across the app behind it.
+    <Tooltip label={text} side="bottom" delayMs={400} disabled={!truncated} maxWidth={360}>
+      {/* The empty title stops the card body's native tooltip from climbing to
+        this span: a cut-off description answers with one bubble, not two. */}
+      <span ref={ref} className={css.cardDesc} title="">{text}</span>
+    </Tooltip>
+  )
+}
+
 /**
  * Render the Agent presets section content column.
  * @param props - composed slot props.
@@ -247,7 +280,7 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
                         </span>
                         {row.isDefault ? <span className={css.inUse}>{t('inUse')}</span> : null}
                       </span>
-                      <span className={css.cardDesc}>{text.description ?? t('noDescription')}</span>
+                      <CardDescription text={text.description ?? t('noDescription')} />
                       {row.broken === undefined
                         ? null
                         : <span className={css.cardBrokenReason} role="alert">{row.broken}</span>}

packages/client/ui-agent-preset/src/client/locales.ts

@@ -57,8 +57,8 @@ export const en: Record<AgentPresetSettingsKey, string> = {
   builtInGroup: 'Built-in',
   customGroup: 'Custom',
   noDescription: 'No description.',
-  brokenBadge: 'Broken',
-  brokenNoCopy: 'Broken presets cannot be duplicated',
+  brokenBadge: 'Failed to load',
+  brokenNoCopy: 'A preset that failed to load cannot be duplicated',
   copyOf: 'Copied from',
   composition: 'Composition (agent.cordis.yml)',
   cancel: 'Cancel',
@@ -117,8 +117,8 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
   builtInGroup: '内置',
   customGroup: '自定义',
   noDescription: '暂无描述。',
-  brokenBadge: '已损坏',
-  brokenNoCopy: '预设已损坏，无法复制',
+  brokenBadge: '加载失败',
+  brokenNoCopy: '预设加载失败，不能复制',
   copyOf: '复制自',
   composition: '组装（agent.cordis.yml）',
   cancel: '取消',

packages/client/ui-agent-preset/tests/section.spec.tsx

@@ -6,8 +6,8 @@
  * action follows the host's desktop capability.
  */
 
-import { cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { AgentPresetSection } from '../src/client/AgentPresetSection.tsx'
@@ -452,3 +452,68 @@ describe('deleting a preset', () => {
     expect(actions.remove).not.toHaveBeenCalled()
   })
 })
+
+describe('a long card description', () => {
+  /** jsdom has no ResizeObserver; the description watches its own box through one. */
+  class ResizeObserverStub {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  }
+
+  const LONG = '始终用简体中文交流的友好通用助手，提供持久 bash 与文件编辑能力。'.repeat(8)
+
+  /** Force the clamp to report an overflow: jsdom lays nothing out, so both heights are 0. */
+  function clamp(overflowing: boolean): void {
+    vi.spyOn(Element.prototype, 'scrollHeight', 'get').mockReturnValue(overflowing ? 400 : 80)
+    vi.spyOn(Element.prototype, 'clientHeight', 'get').mockReturnValue(80)
+  }
+
+  beforeEach(() => { vi.stubGlobal('ResizeObserver', ResizeObserverStub) })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+    vi.restoreAllMocks()
+  })
+
+  it('offers the whole description on hover once the card cuts it off', () => {
+    clamp(true)
+    vi.useFakeTimers()
+    try {
+      renderSection({ rows: [{ id: 'zh', trust: 'user', isDefault: false, name: '中文助手', description: LONG }] })
+
+      fireEvent.mouseEnter(within(rowFor('zh')).getByText(LONG))
+      act(() => { vi.advanceTimersByTime(400) })
+
+      expect(screen.getByRole('tooltip').textContent).toBe(LONG)
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('stays quiet when the description already fits', () => {
+    clamp(false)
+    vi.useFakeTimers()
+    try {
+      renderSection({ rows: [{ id: 'zh', trust: 'user', isDefault: false, name: '中文助手', description: '短描述。' }] })
+
+      fireEvent.mouseEnter(within(rowFor('zh')).getByText('短描述。'))
+      act(() => { vi.advanceTimersByTime(400) })
+
+      // A bubble repeating what is already fully on the card is noise.
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('renders where the runtime has no ResizeObserver', () => {
+    vi.unstubAllGlobals()
+    clamp(true)
+
+    expect(() => {
+      renderSection({ rows: [{ id: 'zh', trust: 'user', isDefault: false, description: LONG }] })
+    }).not.toThrow()
+    // The first measurement does not depend on the observer.
+    expect(within(rowFor('zh')).getByText(LONG).getAttribute('title')).toBe('')
+  })
+})

packages/client/ui-primitives/src/Tooltip.tsx

@@ -1,7 +1,7 @@
 // Hover/focus label bubble (figma tooltip pill: dark plate, white text).
-// TODO: interaction is a placeholder (horizontal overflow clamps, but there
-// is no vertical flip on viewport collision and no arrow) — visuals and
-// behavior get a proper pass later.
+// TODO: interaction is a placeholder (horizontal overflow clamps and a
+// vertical collision flips the bubble to the other side, but there is no
+// arrow) — visuals and behavior get a proper pass later.
 // The anchor is the child element itself (cloneElement, no wrapper node), so
 // attaching a tooltip never changes the anchor's layout context. The bubble is
 // position:fixed and coordinates come from the anchor's rect at show time, so
@@ -33,10 +33,12 @@ type TooltipLabel = string | (() => string)
  * @param props.delayMs - hover delay in milliseconds; keyboard focus remains immediate.
  * @param props.disabled - suppress the bubble while true; the anchor renders identically so
  * toggling never remounts it (which would cut its CSS transitions).
+ * @param props.maxWidth - bubble width cap in pixels, for labels long enough that the default
+ * half-viewport cap would render a slab wider than the surface the anchor sits on.
  * @param props.children - a single anchor element; its own ref (callback or object) is forwarded alongside the tooltip's.
  * @returns the cloned anchor plus a fixed-position bubble while hovered/focused.
  */
-export function Tooltip({ label, side = 'right', delayMs = 0, disabled = false, children }: { label: TooltipLabel; side?: TooltipSide; delayMs?: number; disabled?: boolean; children: ReactElement<AnchorProps> }) {
+export function Tooltip({ label, side = 'right', delayMs = 0, disabled = false, maxWidth, children }: { label: TooltipLabel; side?: TooltipSide; delayMs?: number; disabled?: boolean; maxWidth?: number; children: ReactElement<AnchorProps> }) {
   const anchor = useRef<HTMLElement | null>(null)
   // React 18 keeps the element's ref outside props; forward it so wrapping an
   // anchor in Tooltip never silently severs the owner's ref.
@@ -46,33 +48,53 @@ export function Tooltip({ label, side = 'right', delayMs = 0, disabled = false,
     if (typeof childRef === 'function') childRef(el)
     else if (childRef != null) (childRef as MutableRefObject<HTMLElement | null>).current = el
   }, [childRef])
-  const [pos, setPos] = useState<{ x: number; y: number } | null>(null)
+  // The anchor's edges rather than final coordinates: a vertical flip has to
+  // re-derive the bubble's own top from the opposite edge.
+  const [pos, setPos] = useState<{ x: number; top: number; bottom: number } | null>(null)
+  // Where the bubble actually sits, which is the requested side until the
+  // viewport refuses it.
+  const [placement, setPlacement] = useState<TooltipSide>(side)
   const bubble = useRef<HTMLSpanElement | null>(null)
   const resolvedLabel = pos === null
     ? null
     : typeof label === 'function' ? label() : label
-  // Horizontal viewport clamp: fixed positioning knows nothing about edges, so
-  // a centered bubble near the right edge would clip. Each measurement resets
-  // the base position before applying a direct style offset, allowing a shorter
-  // label or wider viewport to release a previous clamp without another render.
+  const y = pos === null
+    ? 0
+    : placement === 'right'
+      ? pos.top + (pos.bottom - pos.top) / 2
+      : placement === 'top' ? pos.top - 8 : pos.bottom + 8
+  const EDGE_MARGIN = 12
+  // Viewport fit: fixed positioning knows nothing about edges, so a centered
+  // bubble near the right edge would clip and a long label under an anchor low
+  // on the page would run off the bottom. Horizontally the bubble slides back
+  // inside; vertically it flips to the opposite side, which is the only move
+  // that does not cover the anchor being read. Each measurement resets the base
+  // position first, so a shorter label or a larger viewport releases a previous
+  // adjustment without another render.
   useLayoutEffect(() => {
     if (pos === null) return
-    const clamp = () => {
+    const fit = () => {
       const el = bubble.current
       /* v8 ignore next -- pos is set only while the bubble is mounted. */
       if (el === null) return
-      const EDGE_MARGIN = 12
       el.style.left = `${pos.x}px`
       const r = el.getBoundingClientRect()
       let dx = 0
       if (r.right > window.innerWidth - EDGE_MARGIN) dx = window.innerWidth - EDGE_MARGIN - r.right
       if (r.left + dx < EDGE_MARGIN) dx = EDGE_MARGIN - r.left
       el.style.left = `${pos.x + dx}px`
+      if (side === 'right') return
+      // Flip only into a side that genuinely fits, so an anchor with room on
+      // neither side keeps the requested placement instead of oscillating.
+      const fitsBelow = pos.bottom + 8 + r.height <= window.innerHeight - EDGE_MARGIN
+      const fitsAbove = pos.top - 8 - r.height >= EDGE_MARGIN
+      if (placement === 'bottom' && !fitsBelow && fitsAbove) setPlacement('top')
+      if (placement === 'top' && !fitsAbove && fitsBelow) setPlacement('bottom')
     }
-    clamp()
-    window.addEventListener('resize', clamp)
-    return () => { window.removeEventListener('resize', clamp) }
-  }, [pos, resolvedLabel])
+    fit()
+    window.addEventListener('resize', fit)
+    return () => { window.removeEventListener('resize', fit) }
+  }, [placement, pos, resolvedLabel, side])
   const showTimer = useRef<ReturnType<typeof setTimeout> | null>(null)
   // Hover and focus are independent triggers: the bubble hides only after
   // BOTH clear (hovering away from a focused anchor must not drop it).
@@ -100,11 +122,10 @@ export function Tooltip({ label, side = 'right', delayMs = 0, disabled = false,
     /* v8 ignore next -- the ref is attached by event time: events fire on the cloned anchor. */
     if (el === null) return
     const r = el.getBoundingClientRect()
-    setPos(side === 'right'
-      ? { x: r.right + 10, y: r.top + r.height / 2 }
-      : side === 'top'
-        ? { x: r.left + r.width / 2, y: r.top - 8 }
-        : { x: r.left + r.width / 2, y: r.bottom + 8 })
+    // Every show starts from the requested side; the fit pass flips it only
+    // where this anchor's position demands it.
+    setPlacement(side)
+    setPos({ x: side === 'right' ? r.right + 10 : r.left + r.width / 2, top: r.top, bottom: r.bottom })
   }
   const showAfterHoverDelay = () => {
     cancelShow()
@@ -132,7 +153,13 @@ export function Tooltip({ label, side = 'right', delayMs = 0, disabled = false,
         onBlur: (e) => { children.props.onBlur?.(e); triggers.current.focus = false; hide() },
       })}
       {pos !== null && (
-        <span ref={bubble} className={css.bubble} data-side={side} style={{ left: pos.x, top: pos.y }} role="tooltip">
+        <span
+          ref={bubble}
+          className={css.bubble}
+          data-side={placement}
+          style={{ left: pos.x, top: y, ...maxWidth === undefined ? {} : { maxWidth } }}
+          role="tooltip"
+        >
           {resolvedLabel}
         </span>
       )}

packages/client/ui-primitives/tests/tooltip.spec.tsx

@@ -95,6 +95,18 @@ describe('Tooltip', () => {
   const rect = (left: number, right: number): DOMRect =>
     ({ left, right, top: 0, bottom: 20, width: right - left, height: 20, x: left, y: 0, toJSON: () => ({}) })
 
+  it('caps the bubble width where the label would otherwise slab across the surface', () => {
+    render(
+      <Tooltip label="A description long enough to need a cap" side="bottom" maxWidth={360}>
+        <button type="button">anchor</button>
+      </Tooltip>,
+    )
+    fireEvent.mouseEnter(screen.getByText('anchor'))
+
+    // The stylesheet's half-viewport cap stays the default; this one overrides it.
+    expect(screen.getByRole('tooltip').style.maxWidth).toBe('360px')
+  })
+
   it('clamps a bubble overflowing the right viewport edge back inside', () => {
     const spy = vi.spyOn(Element.prototype, 'getBoundingClientRect').mockReturnValue(rect(900, 1100))
     try {
@@ -161,19 +173,88 @@ describe('Tooltip', () => {
     }
   })
 
+  /** Anchor and bubble rects, so a placement test measures real room rather than jsdom's all-zero boxes. */
+  const placed = (anchorTop: number, anchorBottom: number, bubbleHeight: number) =>
+    vi.spyOn(Element.prototype, 'getBoundingClientRect').mockImplementation(function (this: Element) {
+      const [top, bottom] = this.getAttribute('role') === 'tooltip'
+        ? [0, bubbleHeight]
+        : [anchorTop, anchorBottom]
+      return {
+        left: 100, right: 200, top, bottom, width: 100, height: bottom - top, x: 100, y: top, toJSON: () => ({}),
+      }
+    })
+
   it('supports top placement for anchors at the viewport bottom', () => {
-    render(
-      <Tooltip label="Above" side="top">
-        <button type="button">anchor</button>
-      </Tooltip>,
-    )
-    fireEvent.mouseEnter(screen.getByText('anchor'))
-    const bubble = screen.getByRole('tooltip')
-    expect(bubble.getAttribute('data-side')).toBe('top')
-    // jsdom rects are all-zero: top placement lands at the -8 gutter and the
-    // zero-width measured rect clamps left to the 12px edge margin.
-    expect(bubble.style.left).toBe('12px')
-    expect(bubble.style.top).toBe('-8px')
+    const spy = placed(700, 720, 20)
+    try {
+      render(
+        <Tooltip label="Above" side="top">
+          <button type="button">anchor</button>
+        </Tooltip>,
+      )
+      fireEvent.mouseEnter(screen.getByText('anchor'))
+      const bubble = screen.getByRole('tooltip')
+      // There is room above, so the requested side stands: the bubble's own
+      // top sits at the anchor's top less the 8px gutter.
+      expect(bubble.getAttribute('data-side')).toBe('top')
+      expect(bubble.style.top).toBe('692px')
+      expect(bubble.style.left).toBe('150px')
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('flips a bottom bubble above an anchor with no room below', () => {
+    // jsdom's viewport is 768 tall: a 300px bubble under an anchor ending at
+    // 700 would run off, and there is room for it above.
+    const spy = placed(600, 700, 300)
+    try {
+      render(
+        <Tooltip label="Tall" side="bottom">
+          <button type="button">anchor</button>
+        </Tooltip>,
+      )
+      fireEvent.mouseEnter(screen.getByText('anchor'))
+      const bubble = screen.getByRole('tooltip')
+      expect(bubble.getAttribute('data-side')).toBe('top')
+      expect(bubble.style.top).toBe('592px')
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('flips a top bubble below an anchor with no room above', () => {
+    const spy = placed(10, 40, 100)
+    try {
+      render(
+        <Tooltip label="Tall" side="top">
+          <button type="button">anchor</button>
+        </Tooltip>,
+      )
+      fireEvent.mouseEnter(screen.getByText('anchor'))
+      const bubble = screen.getByRole('tooltip')
+      expect(bubble.getAttribute('data-side')).toBe('bottom')
+      expect(bubble.style.top).toBe('48px')
+    } finally {
+      spy.mockRestore()
+    }
+  })
+
+  it('keeps the requested side when neither side fits', () => {
+    // A bubble taller than the viewport has no home; oscillating between the
+    // two would be worse than honouring the request.
+    const spy = placed(300, 400, 900)
+    try {
+      render(
+        <Tooltip label="Huge" side="bottom">
+          <button type="button">anchor</button>
+        </Tooltip>,
+      )
+      fireEvent.mouseEnter(screen.getByText('anchor'))
+      expect(screen.getByRole('tooltip').getAttribute('data-side')).toBe('bottom')
+    } finally {
+      spy.mockRestore()
+    }
   })
 
   it('chains the anchor\'s own handlers ahead of the tooltip\'s', () => {

packages/core/agent-tool-mode/src/index.ts

@@ -5,8 +5,10 @@
  * The tool registry itself stays on the host plane — the agent loop's
  * scheduler, the API proxy's presenters, and every tool plugin are all its
  * consumers, so it cannot move into a preset. What a preset CAN own is the
- * presentation: `ctx.tools.presentAs()` declares it for the mounting agent
- * alone, so a Code Mode agent runs beside native ones in one process.
+ * presentation: `ctx.tools.presentAs()` declares it for the mounting SCOPE,
+ * which is the preset's standing mount, so the declaration covers every agent
+ * joined to that preset and a Code Mode preset runs beside native ones in one
+ * process. One row per composition, not one per session.
  *
  * A code mode needs a TypeScript code runtime, which is a host-plane service
  * ([`dsh-code-runtime-worker`](../../code-runtime/code-runtime-worker/README.md)).
@@ -50,8 +52,8 @@ export const Config: z<Config> = z.object({
 })
 
 /**
- * Declare this agent's tool presentation.
- * @param ctx - the mounting agent's scope context.
+ * Declare the tool presentation for every agent this composition covers.
+ * @param ctx - the mounting composition's scope context (a preset's standing scope).
  * @param config - the selected presentation.
  */
 export function apply(ctx: Context, config: Config): void {

packages/core/tools/src/index.ts

@@ -786,7 +786,7 @@ export class ToolRegistry extends Service {
     scope => new ToolLayer(scope),
     () => { this.ctx.emit('tools/change') },
   )
-  /** Presentation for agents that declare none; {@link presentAs} shadows it per agent. */
+  /** Presentation for scopes that declare none; {@link presentAs} shadows it per scope. */
   private readonly defaultMode: ToolPresentationMode
   private readonly maxParallelSubCalls: number
   /**
@@ -811,7 +811,7 @@ export class ToolRegistry extends Service {
 
   /**
    * The generated-SDK prompt section, registered globally by a code-mode
-   * deployment and per agent by {@link presentAs}.
+   * deployment and per scope by {@link presentAs}.
    *
    * The body regenerates from the CALLING scope, and renders empty for an
    * agent presenting natively — an agent that opted out under a code-mode
@@ -880,12 +880,14 @@ export class ToolRegistry extends Service {
   }
 
   /**
-   * Present this agent's tools in `mode` instead of the deployment default.
+   * Present the calling scope's tools in `mode` instead of the deployment
+   * default. Nearest scope on the chain wins, so a preset's standing
+   * declaration covers every agent joined under it.
    *
-   * Scoped only, and one declaration per agent: this is how an agent preset
-   * composes a Code Mode agent beside native ones in the same process, and a
+   * Scoped only, and one declaration per scope: this is how an agent preset
+   * composes Code Mode agents beside native ones in the same process, and a
    * process-global override would be the `mode` config field instead.
-   * @param mode - the presentation this agent's model sees.
+   * @param mode - the presentation the covered agents' models see.
    * @returns the exact disposer that restores the deployment default.
    */
   presentAs(mode: ToolPresentationMode): () => void {
@@ -898,14 +900,14 @@ export class ToolRegistry extends Service {
         ctx,
         (layer) => {
           if (layer.mode !== undefined) {
-            throw new Error(`tools.presentAs("${mode}") conflicts with "${layer.mode}" already declared for this agent; one composition selects one presentation`)
+            throw new Error(`tools.presentAs("${mode}") conflicts with "${layer.mode}" already declared for this scope; one composition selects one presentation`)
           }
           layer.mode = mode
           return () => { layer.mode = undefined }
         },
         { label: 'tools.presentAs()' },
       )
-      // The SDK section is per agent for the same reason the mode is. Under a
+      // The SDK section is per scope for the same reason the mode is. Under a
       // deployment that already defaults to a code mode this shadows the
       // global registration with an identical body, which costs nothing and
       // keeps one rule instead of a case analysis.

packages/host/apiproxy/src/api-proxy.ts

@@ -712,6 +712,16 @@ function historyPage(
  * registry). An absent registry means the deployment has no projection seam:
  * the whole block is absent and clients treat every key as capability-absent.
  */
+/**
+ * Which session a transcript read is served from. An attached session is the
+ * live object and keeps appending, so its events and projection baseline are
+ * read together in one synchronous step; a detached one is already a frozen
+ * inspection.
+ */
+type HistorySource =
+  | { readonly kind: 'attached'; readonly session: Session }
+  | { readonly kind: 'detached'; readonly header: SessionHeader; readonly events: SessionEvent[] }
+
 function projectionsFor(ctx: Context, session: Session): SessionProjectionsBlock | undefined {
   const registry = ctx.get('sessionProjections')
   if (registry === undefined) return undefined
@@ -1355,24 +1365,55 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
     return undefined
   }
 
-  /** Read one transcript cut and optional projection baseline without acquiring an Agent owner. */
-  async function historyStateFor(
-    sessionId: SessionId,
-    includeProjections: boolean,
-  ): Promise<{ header: SessionHeader; events: SessionEvent[]; projections?: SessionProjectionsBlock }> {
+  /**
+   * Resolve which session one transcript read is served from, without
+   * acquiring an Agent owner. This is the read's only asynchronous step
+   * besides ensuring the composition; {@link historyCutOf} takes the cut.
+   * @param sessionId - the transcript being read.
+   * @returns the attached session, or the inspected detached header and events.
+   * @throws {@link ApiRemoteSessionNotFound} when no project-backed session has that identity.
+   */
+  async function historySourceFor(sessionId: SessionId): Promise<HistorySource> {
     const attached = ctx.sessions.get(sessionId)
-    if (attached !== undefined) {
-      const events = [...attached.events]
-      const projections = includeProjections ? projectionsFor(ctx, attached) : undefined
-      return { header: attached.header, events, ...projections === undefined ? {} : { projections } }
-    }
+    if (attached !== undefined) return { kind: 'attached', session: attached }
     const inspected = await inspectServable(sessionId)
-    const projections = includeProjections ? detachedProjectionsFor(ctx, inspected.events) : undefined
-    return {
-      header: inspected.meta,
-      events: inspected.events,
-      ...projections === undefined ? {} : { projections },
+    return { kind: 'detached', header: inspected.meta, events: inspected.events }
+  }
+
+  /**
+   * The header and events {@link presenterScopeFor} reads to decide which
+   * composition a transcript ran under.
+   * @param source - the live or detached session this read is served from.
+   * @returns that session's creation header and its events.
+   */
+  function sourceSession(source: HistorySource): PresetBearingSession {
+    if (source.kind === 'detached') return { header: source.header, events: source.events }
+    return { header: source.session.header, events: source.session.events }
+  }
+
+  /**
+   * One transcript cut: the events and the projection baseline that describe
+   * the SAME log position.
+   *
+   * Synchronous, and the two reads sit next to each other, because an attached
+   * session keeps appending: an `await` between them would serve events cut at
+   * N beside a baseline folded to N+1, which is one response describing two
+   * moments. The caller does its awaiting before this call.
+   * @param source - the live or detached session this read is served from.
+   * @param includeProjections - whether the caller asked for the baseline (a tail page does).
+   * @returns the events and, when asked, the baseline for that same position.
+   */
+  function historyCutOf(
+    source: HistorySource,
+    includeProjections: boolean,
+  ): { events: SessionEvent[]; projections?: SessionProjectionsBlock } {
+    if (source.kind === 'detached') {
+      const projections = includeProjections ? detachedProjectionsFor(ctx, source.events) : undefined
+      return { events: source.events, ...projections === undefined ? {} : { projections } }
     }
+    const events = [...source.session.events]
+    const projections = includeProjections ? projectionsFor(ctx, source.session) : undefined
+    return { events, ...projections === undefined ? {} : { projections } }
   }
 
   /**
@@ -2032,9 +2073,22 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
 
       async history(request) {
         const { sessionId, beforeSeq, maxMessages } = request.payload
-        let state: { header: SessionHeader; events: SessionEvent[]; projections?: SessionProjectionsBlock }
         try {
-          state = await historyStateFor(sessionId, beforeSeq === undefined)
+          const source = await historySourceFor(sessionId)
+          // Both awaits happen BEFORE the cut. Ensuring the recorded
+          // composition's standing mount is what registers its projection
+          // units, so a first cold read would otherwise serve a baseline
+          // missing every preset-owned key; and an attached session keeps
+          // appending, so awaiting between the two reads would pair events cut
+          // at N with a baseline folded to N+1.
+          const scope = await presenterScopeFor(sessionId, sourceSession(source))
+          const cut = historyCutOf(source, beforeSeq === undefined)
+          const page = historyPage(ctx, cut.events, beforeSeq, maxMessages, scope)
+          return ok(request, {
+            events: page.events,
+            hasMore: page.hasMore,
+            ...cut.projections === undefined ? {} : { projections: cut.projections },
+          })
         } catch (error: unknown) {
           if (error instanceof SessionNotFound) {
             return err(request, { code: 'session-not-found', message: error.message, details: { sessionId } })
@@ -2045,12 +2099,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
             details: {},
           })
         }
-        const page = historyPage(ctx, state.events, beforeSeq, maxMessages, await presenterScopeFor(sessionId, state))
-        return ok(request, {
-          events: page.events,
-          hasMore: page.hasMore,
-          ...state.projections === undefined ? {} : { projections: state.projections },
-        })
       },
 
       async models(request) {

packages/preset/agent-presets/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/agent-presets/README.md
-README.md: e31dc8e666096baf6fd6b2cf9407110c7678c6e1
-README.zh.md: cf7e24bb0f256623beec1b86c70473a70be03cb5
+README.md: 98891c8710adc7d72dee20a8466742ee6f649956
+README.zh.md: 0fcc5fa4d697affc2185b9251c6a60dee6510042

packages/preset/agent-presets/README.md

@@ -133,7 +133,8 @@ Prefix-stable for the life of an agent: a composition is installed once, before
 ## Known Limitations and Deferred Work
 
 - **A preset cannot be changed once a session has produced anything** — `recompose` re-links a BLANK session's parent scope to another standing mount, and only a blank one: switching a composition that already ran would strand tools the model has called. Changing the default affects only sessions created afterwards.
-- **A generation is keyed on the composition file alone** — the stamp check notices `agent.cordis.yml` changing, not an edit to a skill file or asset beside it; those reach new sessions only once the composition file itself moves or the process restarts. Sessions already joined keep their generation, and nothing reclaims a superseded one while the process lives (bounded by how often compositions are edited, not by sessions).
+- **A generation is keyed on the composition file alone** — the stamp check notices `agent.cordis.yml` changing, not an edit to a skill file or asset beside it; those reach new sessions only once the composition file itself moves or the process restarts.
+- **A superseded generation is never reclaimed** — sessions already joined keep the generation they run on, and the roster holds no join count that could tell when the last one left, so the whole subtree stays mounted until the process ends. The cost is per generation rather than per session, but it is not free: `dsh-skill-local` watches its roots by default, so each edit-then-create cycle adds a live watcher set. Bounded by how often compositions are edited — which the settings-page authoring flow makes a per-save event rather than a per-deploy one. Reclaiming one needs a joined-agent count on the standing mount; see the `TODO` at `ensureStanding`.
 - **A copy is never mounted to validate** — it is byte-identical to its source, so a source broken on disk yields a copy exactly as broken as the source; discovery's health check marks both rows on the next roster read rather than deferring the failure to a session start.
 - **Health is a shape check, not a mount** — discovery proves the composition parses in the loader dialect and holds named rows, not that every row's module resolves or activates; a row naming an absent package still fails at the first session, which rolls the creation back.
 - **A copy is a snapshot that drifts** — upgrading the deployment does not update copies of shipped presets, and there is no patch semantics at this layer to express "standard plus one change" (that is the bundle layer's `cordis.patch.yml`); the shipped set itself accepts the same cost — `cordis` and `code` are full copies of `standard` — so the whole assembly stays readable in one file.

packages/preset/agent-presets/README.zh.md

@@ -133,7 +133,8 @@ Indirectly, through the plugins a standing composition registers, which own ever
 ## Known Limitations and Deferred Work
 
 - **会话一旦产出内容便无法更换 preset** —— `recompose` 把**空白**会话的父作用域重链到另一个常驻挂载，且仅限空白会话：切换已运行过的组装会抽走模型已调用的工具。更改默认值只影响此后创建的会话。
-- **代际只以组装文件为键** —— stamp 检查只察觉 `agent.cordis.yml` 的变化，察觉不到旁边 skill 文件或资产的编辑；那些编辑要等组装文件本身变动或进程重启才达到新会话。已加入的会话保持其代际，进程存活期间不回收被替代的代际（上限取决于组装被编辑的频率，而非会话数）。
+- **代际只以组装文件为键** —— stamp 检查只察觉 `agent.cordis.yml` 的变化，察觉不到旁边 skill 文件或资产的编辑；那些编辑要等组装文件本身变动或进程重启才达到新会话。
+- **被替代的代际永不回收** —— 已加入的会话保持其运行所在的代际，而名单没有加入计数可以判断最后一个何时离开，因此整棵子树一直挂到进程结束。代价按代际计而非按会话计，但并非为零：`dsh-skill-local` 默认监听自己的根目录，因此每一轮「编辑后建会话」都会新增一套活的 watcher。上限取决于组装被编辑的频率——而设置页的编写流程把这件事从「每次部署」变成了「每次保存」。要回收就需要给常驻挂载加上已加入 agent 的计数；见 `ensureStanding` 处的 `TODO`。
 - **副本从不被实际挂载以校验** —— 它与来源逐字节相同，因此磁盘上已坏的来源会产出与来源同样损坏的副本；发现过程的健康检查会在下一次读取名单时把两行都标出来，而不是把失败推迟到会话启动。
 - **健康是形状检查，不是挂载** —— 发现过程只证明组装能以加载器方言解析、由具名行组成，不证明每一行的模块都能解析并激活；引用不存在的包的行仍在第一个会话处失败，并回滚该会话的创建。
 - **副本是会漂移的快照** —— 升级部署不会更新随附 preset 的副本，本层也没有表达「standard 加一处改动」的 patch 语义（那是 bundle 层 `cordis.patch.yml` 的能力）；随附集合自己也接受同样的代价——`cordis` 与 `code` 就是 `standard` 的完整副本——换来整份组装在一个文件里可读。

packages/preset/agent-presets/package.json

@@ -34,12 +34,14 @@
   "peerDependencies": {
     "@deepseek-ai/cordis-plugin-include": "workspace:^",
     "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-atomic-write": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-settings": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
     "@deepseek-ai/cordis": "workspace:^"
   },
   "dependencies": {

packages/preset/agent-presets/src/index.ts

@@ -25,6 +25,8 @@ import { stat } from 'node:fs/promises'
 import { Context, Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { bindScopeParent, createScope, scopeOf, type Scope, type ScopeKey, type ScopeParentBinding } from '@deepseek-ai/dsh-scope'
+// Type-only: resolves the `agent/created` lifecycle event this service watches.
+import type {} from '@deepseek-ai/dsh-agent'
 import { settingsNamespace, type SettingsScope, type default as SettingsService } from '@deepseek-ai/dsh-settings'
 import { discoverPresets } from './discovery.ts'
 import { copyComposition, deleteComposition, readComposition } from './authoring.ts'
@@ -130,6 +132,28 @@ export class AgentPresets extends Service {
         this.settingsService = undefined
       }, 'agentPresets.settings()')
     })
+
+    // Advisory, not fatal: a synchronous `agent/created` listener that throws
+    // VETOES publication, and this service must not, because composing an agent
+    // outside the roster is legal — `recompose` binds exactly such a bare agent
+    // below, and the ACP, SDK-server, and headless entry points all create one.
+    // The invariant companion is the check that fails loud, at assembly. Why an
+    // unjoined agent matters at all has one home: the [Agent
+    // Note](../../../../.agents/notes/implemented/architecture/2026-08-10-host-plane-ownership-after-presets.md).
+    //
+    // Known false positive: a session created bare and bound later by
+    // `recompose` is warned about once, before its first bind. No shipped flow
+    // does that today — the Web surface mounts in `setup` and children join
+    // through `composeFrom` before publication.
+    ctx.on('agent/created', ({ agent }) => {
+      if (this.config.roots.length === 0) return
+      if (this.composedPreset(agent.ctx) !== undefined) return
+      ctx.logger.warn(
+        `agent "${agent.id}" was published without joining an agent preset; `
+        + 'its tools, prompt sections, and skill catalog resolve against the empty global layer '
+        + '(join through AgentPresets.mount() or composeFrom() in the agent factory setup)',
+      )
+    })
   }
 
   /**
@@ -440,6 +464,12 @@ export class AgentPresets extends Service {
       // disappearing, and failing the session over a stat would not.
       const current = await compositionStamp(preset.path)
       if (current === undefined || sameStamp(mounted.stamp, current)) return mounted
+      // TODO: reclaim the superseded generation once the last agent joined to
+      // it is gone. The subtree is not inert — `dsh-skill-local` watches its
+      // roots — and the settings-page authoring flow turns "a composition
+      // changed" into a per-save event. This needs a joined-agent count on
+      // StandingMount, incremented in `mount`/`composeFrom`/`recompose` and
+      // decremented when the agent's scope key dies.
       // Guarded delete: a caller that raced this one may have already started
       // the next generation, and dropping THAT pointer would fork a third.
       if (this.standing.get(preset.id) === pending) this.standing.delete(preset.id)

packages/preset/agent-presets/src/invariant.ts

@@ -5,6 +5,10 @@
 
 import type { Context } from '@deepseek-ai/cordis'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+// Type-only: resolves the `system-prompt/assemble` waterfall this companion
+// joins, and the `agent` field `dsh-agent` merges into its context.
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-agent'
 // Imported through the package name, not `./mount.ts`: a module shared between
 // the two build entry points becomes a third chunk that the published `files`
 // list does not carry, which `verify-built-package-invariants` rejects.
@@ -18,9 +22,10 @@ export const name = 'agent-presets-invariant'
 export const inject = ['invariants']
 
 /**
- * Assert that no installed preset composition reaches the root service realm.
+ * Assert that no installed preset composition reaches the root service realm,
+ * and that a deployment configuring a roster composes every agent from it.
  *
- * `mountPreset` proves this once, when the subtree settles. A row that
+ * `mountPreset` proves the first once, when the subtree settles. A row that
  * publishes later — from a timer, or an asynchronous continuation after its
  * plugin returned — would escape that one-shot audit, so re-check every live
  * mount whenever a service registration changes.
@@ -37,6 +42,33 @@ const install: InvariantInstaller = (ctx, fail) => {
       )
     }
   }, { global: true })
+
+  // An agent that joined no preset resolves `tools`, `system-prompt`, and
+  // `skill` against the empty global layer, so the model receives nothing.
+  // `composedPreset()` is the roster's own answer to "did this agent join",
+  // read from the live scope chain — see the [Agent
+  // Note](../../../../.agents/notes/implemented/architecture/2026-08-10-host-plane-ownership-after-presets.md)
+  // for why the warning beside it is advisory while this one fails.
+  //
+  // Two conditions, each load-bearing. `context.agent` is what makes this an
+  // AGENT assembly: a scope-only assembly — a cold read resolving presenters
+  // in a standing key, a diagnostic — is not an agent and must not be judged
+  // on whether it joined anything. And assembly rather than publication is the
+  // moment that matters, because an unjoined agent is legal until it addresses
+  // a model: `recompose` binds a bare agent as its first link, and that agent
+  // is unjoined for its whole life up to the switch.
+  ctx.on('system-prompt/assemble', (_assembly, context, next) => {
+    const presets = ctx.get('agentPresets')
+    const agent = context.agent
+    if (presets !== undefined && presets.config.roots.length > 0
+      && agent !== undefined && presets.composedPreset(agent.ctx) === undefined) {
+      fail(
+        `agent "${agent.id}" addressed a model without joining any agent preset while a roster is `
+        + 'composed; its tools, prompt sections, and skill catalog resolve against the empty global layer',
+      )
+    }
+    return next()
+  })
 }
 
 /**

packages/preset/agent-presets/tests/invariant.spec.ts

@@ -7,7 +7,7 @@ import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry from '@deepseek-ai/dsh-tools'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { assembleContextFor } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import { describe, expect, it } from 'vitest'
@@ -84,4 +84,34 @@ describe('agent-presets invariants', () => {
       setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'isolated'),
     })).resolves.toBeDefined()
   })
+
+  it('rejects an agent that addresses a model without joining any preset', async () => {
+    const ctx = await harness()
+    // The delegation shape: an agent composed outside the roster joined no
+    // standing mount, so every registry view it reads is the empty global
+    // layer. Publication alone stays legal — `recompose` binds exactly such an
+    // agent — so nothing fires until that empty world reaches a prompt.
+    const handle = await ctx.agents.create({ sessionId: SessionId('inv-unjoined') })
+
+    await expect(ctx.systemPrompt.assemble(assembleContextFor(handle.agent)))
+      .rejects.toThrow(/without joining any agent preset/)
+  })
+
+  it('admits a joined agent, a scopeless read, and a standing-key read', async () => {
+    const ctx = await harness()
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('inv-joined'),
+      setup: async (agentCtx: Context) => void await ctx.agentPresets.mount(agentCtx, 'standard'),
+    })
+
+    await expect(ctx.systemPrompt.assemble(assembleContextFor(handle.agent))).resolves.toBeDefined()
+    // A scopeless assembly belongs to no agent, so it cannot be an unjoined one.
+    await expect(ctx.systemPrompt.assemble({})).resolves.toBeDefined()
+    // Neither can a scope that is not an agent at all: a standing preset key
+    // has no parent of its own, so a chain-length rule would reject the cold
+    // read that resolves presenters in it. `context.agent` is what keeps this
+    // check to agent assemblies.
+    const standing = await ctx.agentPresets.standingKeyFor('standard')
+    await expect(ctx.systemPrompt.assemble({ scope: standing })).resolves.toBeDefined()
+  })
 })

packages/preset/agent-presets/tests/mount.spec.ts

@@ -499,6 +499,35 @@ describe('replacing a composition', () => {
     expect(toolNames(ctx, handle.agent)).toEqual(['alpha'])
   })
 
+  it('names an agent that was published without joining any preset', async () => {
+    const ctx = await harness()
+    const warnings: string[] = []
+    ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+
+    await ctx.agents.create({ sessionId: SessionId('sess-unjoined-warn') })
+    // Advisory, not fatal: a synchronous `agent/created` throw would veto
+    // publication, and creating an agent outside the roster stays legal.
+    expect(warnings.filter(line => line.includes('sess-unjoined-warn'))).toHaveLength(1)
+    expect(warnings.at(-1)).toMatch(/without joining an agent preset/)
+
+    warnings.length = 0
+    await agentOn(ctx, 'sess-joined-quiet', 'minimal')
+    expect(warnings).toEqual([])
+  })
+
+  it('says nothing when the deployment configures no roster at all', async () => {
+    // Presets are optional: every surface except the Web bundle keeps its
+    // model-facing rows in the host plane, so an agent with a chain of one is
+    // exactly right there and the diagnostic must stay silent.
+    const rosterless = await harness({ default: 'standard', roots: [] })
+    const warnings: string[] = []
+    rosterless.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof rosterless.logger.warn
+
+    await rosterless.agents.create({ sessionId: SessionId('sess-no-roster') })
+
+    expect(warnings).toEqual([])
+  })
+
   it('composes an agent that had nothing installed', async () => {
     // An agent created without a preset has no binding to re-link, so the
     // switch is its first bind — exactly a mount — and once bound only the

packages/preset/agent-presets/tsconfig.json

@@ -18,12 +18,18 @@
     {
       "path": "../../../vendor/include"
     },
+    {
+      "path": "../../core/agent"
+    },
     {
       "path": "../../core/scope"
     },
     {
       "path": "../../core/session"
     },
+    {
+      "path": "../../core/system-prompt"
+    },
     {
       "path": "../../settings/settings"
     },

packages/scaffold/server/src/server.ts

@@ -216,6 +216,10 @@ export class HarnessSdkServer {
   }
 
   private async createSession(sessionId: string): Promise<SessionRecord> {
+    // No preset composition: this server's compositions keep the model-facing
+    // rows in the host plane, so this agent reads them from the global layer. A
+    // deployment that configures a roster has to join one here first
+    // (@deepseek-ai/dsh-agent-presets README, "Composing a child agent").
     const handle = await this.ctx.agents.create({
       sessionId: SessionId(sessionId),
       meta: { cwd: this.cwd },

packages/self-modification/tool-cordis/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/self-modification/tool-cordis/README.md
-README.md: 4f856523cca4800cdbb98951183fbea1e3c96c87
-README.zh.md: 7bb21396452ddbe49cf3008cd89cd6044b3c4a51
+README.md: be629ca9be5bff1e6f658f05476e8f2880804e44
+README.zh.md: 45f3536d3460106c45051093d097729a366eca1a

packages/self-modification/tool-cordis/README.md

@@ -87,3 +87,4 @@ Mounting or unmounting a prompt or tool contribution changes later request prefi
 - **The sandbox is containment for honest code, not a security boundary** — host-realm helpers on the sandbox global are reachable, so mount code can reach Node; load this plugin as deliberately as you would grant a bash tool (see § Trust stance).
 - **The `ctx` façade exposes no `effect()`** — mount code cannot register a bespoke disposer; `on`/`provide`/`tools.register` are the supported cleanup paths.
 - **`vmTimeoutMs` bounds only synchronous evaluation** — an async mount body escapes it; there is no async budget on mount code.
+- **Temporary Plugins belong to the composition, not to the session that mounted one** — the group fiber and the `dyn-N` table are this row's own, so every agent the row covers shares them: registered inside an agent preset's standing mount, one session's mount is visible in another session's tool catalog and `cordis_inspect what:"temporary"`, and the second mount of an id replaces the first. Several sessions running one preset concurrently is where that becomes observable. Per-session temporary plugins would need the group and table keyed by the calling agent.

packages/self-modification/tool-cordis/README.zh.md

@@ -87,3 +87,4 @@ Namespace 插件：命名导出 `name`／`inject`／`Config`／`apply`，无默
 - **沙箱只用于约束诚实代码，并非安全边界**：可以访问沙箱全局变量上的 host realm helper，因此挂载代码可以触达 Node；加载该插件时，应当像授予 bash 工具一样慎重（见 § 信任立场）。
 - **`ctx` façade 不公开 `effect()`**：挂载代码无法注册定制 disposer；`on`／`provide`／`tools.register` 是受支持的清理路径。
 - **`vmTimeoutMs` 只限制同步求值**：async 挂载主体可逃出该边界；挂载代码没有 async 预算。
+- **临时 Plugin 属于组装，而不属于挂载它的那个会话**：group fiber 与 `dyn-N` 表是本行自己的，因此本行覆盖的每个 agent 共享它们——注册在某个 agent preset 的常驻挂载里时，一个会话挂载出来的东西会出现在另一个会话的工具目录和 `cordis_inspect what:"temporary"` 里，同一个 id 的第二次挂载会顶掉第一次。多个会话并发运行同一 preset 时这一点才变得可观察。要做到逐会话，需要把 group 与表按调用方 agent 建键。

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

@@ -1242,7 +1242,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     methods: [
       {
         signature: 'presentAs(mode: ToolPresentationMode): () => void',
-        jsDoc: '/**\n * Present this agent\'s tools in `mode` instead of the deployment default.\n *\n * Scoped only, and one declaration per agent: this is how an agent preset\n * composes a Code Mode agent beside native ones in the same process, and a\n * process-global override would be the `mode` config field instead.\n * @param mode - the presentation this agent\'s model sees.\n * @returns the exact disposer that restores the deployment default.\n */',
+        jsDoc: '/**\n * Present the calling scope\'s tools in `mode` instead of the deployment\n * default. Nearest scope on the chain wins, so a preset\'s standing\n * declaration covers every agent joined under it.\n *\n * Scoped only, and one declaration per scope: this is how an agent preset\n * composes Code Mode agents beside native ones in the same process, and a\n * process-global override would be the `mode` config field instead.\n * @param mode - the presentation the covered agents\' models see.\n * @returns the exact disposer that restores the deployment default.\n */',
       },
       {
         signature: 'register(definition: ToolDefinition): () => void',

packages/session/session-projection/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-projection/README.md
-README.md: 2615b253999c798172168ec9d0232eb965b07fbc
-README.zh.md: 0712e9c7a61fbcf43939791b3e7cd24af6777c3a
+README.md: 9018b133bb69ed4717fede14c9a2070a07c3fa62
+README.zh.md: b91908117fd452855a82976515d13165803def43

packages/session/session-projection/README.md

@@ -42,6 +42,7 @@ None; projections never assemble or send provider requests.
 ## Known Limitations and Deferred Work
 
 - **Every tail page carries every registered key** — there is no per-key opt-out or lazy-key request shape yet; acceptable while values are UI-scale whole states (a todo list, a goal snapshot), revisit if a domain's value grows large.
+- **The unit table is process-wide, so key presence is not a per-session capability signal** — a key registered by ANY agent preset appears in every session's snapshot, including sessions whose own composition mounts nothing that produces it. A client must read the VALUE (`plan.active`, an empty todo list) rather than treat an absent key as absence of the feature; a unit whose empty value is indistinguishable from a real one belongs on the host plane instead, which is why `dsh-token-meter` sits there.
 - **Eager drive touches every unit per event** — cheap by construction (whole-value rule, same-reference gate), but a hot path would justify per-unit event-type prefilters, addable without contract change.
 - **Registry cells live in memory only** — a restart rebuilds by folding the log on first touch; compositions that mount `dsh-session-projection-cache` seed that fold from persisted rows instead.
 - **Synchronous unit discipline is only partially mechanical** — the boundary `schema.parse` rejects a Promise-returning `view`, but an `apply` that blocks or reads torn non-session state is a review concern; the invariant companion documents why no runtime check exists.

packages/session/session-projection/README.zh.md

@@ -42,6 +42,7 @@
 ## 已知限制与暂缓事项
 
 - **每个尾页携带每个已注册的 key**——尚无逐 key 的 opt-out 或惰性 key 请求形状；在值都是 UI 量级的全量状态（一张 todo 清单、一份 goal 快照）时可以接受，若某领域的值变大再重议。
+- **单元表是进程级的，因此 key 是否存在不能当作逐会话的能力信号**——只要**任何**一个 agent preset 注册了某个 key，它就出现在每个会话的快照里，包括自身组装完全不产出该值的会话。客户端必须读**值**（`plan.active`、空的 todo 列表），不能把 key 缺席当作功能缺席；如果某个单元的空值与真实值无法区分，它就该待在宿主平面——`dsh-token-meter` 正因如此留在那里。
 - **主动驱动（eager drive）逐事件触达每个单元**——按构造开销很低（全量值规则、同引用闸门），但若出现热点路径，可加按单元的事件类型预过滤，约定不变。
 - **注册表 cell 只活在内存里**——重启后首次触达时靠折叠日志重建；挂载了 `dsh-session-projection-cache` 的组合改由持久行播种该折叠。
 - **单元同步纪律只有部分可机械把关**——边界 `schema.parse` 能拒绝返回 Promise 的 `view`，但阻塞的 `apply`、或读取撕裂的非会话状态的 `apply`，只能靠评审把关；invariant 配套记载了为何不存在运行时检查。