@linxin666/dsh-client-ui-task-board 0.4.1 → 0.4.3

package/src/client/index.ts

@@ -24,17 +24,17 @@ import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
 // Type-only: pulls the workspace plugin's Context merge (ctx.uiWorkspace), the
 // multi-instance navigation face that replaced ISessions.open().
 import type {} from '@deepseek-ai/dsh-client-ui-workspace/client'
-import { BoardController } from '../core/controller.ts'
+import { BoardController, TASK_BOARD_PANEL_ID } from '../core/controller.ts'
 import { mainViewSessionId } from './main-session.ts'
 import { LocalStorageTaskStore } from '../core/store.ts'
 import { claimTaskboardApply, releaseTaskboardApply } from './apply-guard.ts'
-import { mountBoard } from './board-mount.tsx'
-import { mountSidebarEntry } from './sidebar-entry.ts'
+import { registerTaskBoardPanel } from './native-panel.tsx'
 import { TaskBoardSettingsCard, TaskBoardSettingsCardController, type TaskBoardSettings } from './TaskBoardSettingsCard.tsx'
 import { en, zh, setRuntimeTranslate, type TaskBoardKey } from './locales.ts'
 import { HttpTaskBoardHostTransport } from './host-api.ts'
 import { reportDailyHeartbeat } from './telemetry.ts'
 import { installPluginCard } from './plugin-card-seat.ts'
+import { createServedEntryForm } from './settings-entry-form.ts'
 
 /** Locale namespace this plugin owns. */
 const NS = 'task-board'
@@ -124,7 +124,7 @@ declare module '@deepseek-ai/cordis' {
  * on hosts below that cohort, which serve the same roster through the
  * connection RPC face.
  */
-export const inject = ['slots', 'sessions', 'workspaces', 'connection', 'configForms', 'locale', 'remote', 'remote.session', 'uiWorkspace']
+export const inject = ['slots', 'sessions', 'workspaces', 'connection', 'configForms', 'locale', 'remote', 'remote.session', 'uiWorkspace', 'layout']
 
 /** One agent-preset row the mode picker consumes (either face's wire shape). */
 interface PresetRosterRow {
@@ -241,6 +241,18 @@ export function apply(ctx: ClientContext): void {
     const controller = new BoardController({
       store,
       transport: new HttpTaskBoardHostTransport(),
+      // Panel navigation belongs to the layout service: the board asks it to
+      // select its own panel id (or the conversation) instead of taking over
+      // the center column at the DOM level. The lookup stays lazy so a
+      // selection issued before the service settles still lands once it does,
+      // and the face throws by contract before the layout root entry mounts,
+      // which the controller tolerates.
+      panel: {
+        select: panelId => {
+          const layout = ctx.get('layout') as { selectPanel?: (id: string | null) => void } | undefined
+          layout?.selectPanel?.(panelId)
+        },
+      },
       sessions: {
         // The main-view Session comes from the catalog's per-source ownership
         // counts; navigation belongs to the workspace UI since the
@@ -362,12 +374,24 @@ export function apply(ctx: ClientContext): void {
     }
     void pushModelOptions()
     disposers.push(ctx.on('connection/reset', () => { void pushModelOptions() }))
+    // Native panel surfaces: one sidebar row and one center-column page, both
+    // through the official slot seats the shell itself renders. The layout's
+    // panel selection is reconciled back into the controller so the board's own
+    // view state follows the user clicking another panel row.
     try {
-      disposers.push(mountSidebarEntry(controller, ctx.locale))
-      disposers.push(mountBoard(controller, ctx.locale))
+      disposers.push(registerTaskBoardPanel(ctx, controller))
+      const layoutFace = ctx.get('layout') as { panelInfo?: { subscribe(listener: () => void): () => void; getSnapshot(): { activePanelId: unknown } } } | undefined
+      if (layoutFace?.panelInfo !== undefined) {
+        const sync = (): void => {
+          const active = layoutFace.panelInfo!.getSnapshot().activePanelId
+          controller.syncPanelSelection(active === TASK_BOARD_PANEL_ID ? TASK_BOARD_PANEL_ID : null)
+        }
+        sync()
+        disposers.push(layoutFace.panelInfo.subscribe(sync))
+      }
     } catch (error) {
-      // DOM failures degrade the board, never the GUI.
-      console.error('[dsh-task-board] mount failed:', error)
+      // A shell that cannot serve the seats degrades the board, never the GUI.
+      console.error('[dsh-task-board] panel registration failed:', error)
     }
 
     uiDisposer = () => {
@@ -384,7 +408,17 @@ export function apply(ctx: ClientContext): void {
     if (enabled) mountUi()
     else uiDisposer?.()
   }
-  settingsForm.subscribe(syncEnabled)
+  const unsubscribeSettings = settingsForm.subscribe(syncEnabled)
+  // The mounted surfaces and the settings subscription belong to this fiber.
+  // The loader replaces a rebuilt bundle IN PLACE (fiber teardown and re-apply
+  // without a page reload), and that same teardown removes the dictionaries
+  // this row and board render through — a row left behind would stay visible
+  // showing raw dictionary keys, and a surviving subscription could mount a
+  // second one from a dead instance.
+  ctx.effect(() => () => {
+    unsubscribeSettings()
+    uiDisposer?.()
+  }, 'task-board: DOM surfaces')
   syncEnabled()
 }
 
@@ -405,22 +439,26 @@ export function bindSettingsForm(ctx: ClientContext): ConfigForm<TaskBoardSettin
   if (binder !== undefined && typeof binder.bind === 'function') {
     return binder.bind<TaskBoardSettings>({ namespace: TASK_BOARD_NS })
   }
-  return ctx.configForms.get<TaskBoardSettings>(servedEntryId(ctx.configForms))
+  return createServedEntryForm<TaskBoardSettings>({
+    forms: ctx.configForms,
+    entryIds: TASK_BOARD_ENTRY_IDS,
+  })
 }
 
 /**
- * The profile entry id this package's own row carries.
+ * The profile entry id this package's own row carries, for a page that serves
+ * no family binder.
  *
  * The shared describe mirror is the only local evidence of which row id this
- * profile actually serves, but it answers asynchronously: at plugin
- * activation it usually holds nothing yet. An unanswered mirror therefore
- * binds the aggregate row id rather than guessing among the candidates —
- * the form is bound once for the session, so a wrong guess would leave the
- * card reporting an unserved namespace even after the mirror settles.
+ * profile actually serves, but it answers asynchronously: at plugin activation
+ * it usually holds nothing yet. An unanswered mirror therefore binds the
+ * aggregate row id rather than guessing among the candidates, and the binding
+ * is re-resolved once the mirror answers — see
+ * {@link createServedEntryForm}, which owns that rebinding.
  * @param forms - the shared configuration forms service.
- * @returns the entry id to bind.
+ * @returns the entry id to bind before the mirror answers.
  */
-function servedEntryId(forms: ConfigForms): string {
+export function servedEntryId(forms: ConfigForms): string {
   let served: readonly string[] | undefined
   try {
     served = forms.describe().getSnapshot().view?.namespaces.map(view => view.ns)

package/src/client/locales.ts

@@ -157,12 +157,16 @@ export const zh = {
   'exec.mode.brokenSuffix': '（不可用）',
   'exec.mode.removed': '（已移除）',
   'exec.permission.default': '会话默认',
+  'exec.permission.inheritParent': '继承父任务（{permission}）',
   'exec.permission.read-only': '只读',
   'exec.permission.workspace-write': '工作区可写',
   'exec.permission.danger-full-access': '完全访问',
   'exec.model.default': '宿主默认（agent-default-model）',
   'exec.model.unknown': '（未知模型/回退默认）',
   'exec.reuseSession': '在同一对话继续',
+  'exec.teamRun': '用 Agent Team 执行（Leader/teammate）',
+  'exec.teamRunHint': '开启后：执行本任务只启动一个 Leader 会话，每个子任务由它派生为 teammate 并在该会话内并行工作（子任务自身的权限钉住不适用）。关闭则每个成员各开独立会话。',
+  'exec.teamRunUnavailable': '当前部署未提供 Agent Teams 服务，无法启用。',
   'exec.reuseSessionHint': '开启后，本任务的后续执行在上一次会话里继续（该会话空闲且仍存在时），不再每次新建对话；每次复用时都会重新应用上面钉住的权限与模型。',
   'detail.executionSettings': '执行设置',
   'exec.hint': '执行时生效：工作区决定执行会话落在哪个工作区；模式决定会话的 agent 预设；权限经 /permission 命令应用到会话。留空则使用运行时默认。',
@@ -170,7 +174,7 @@ export const zh = {
   'settings.title': '任务看板',
   'settings.description': '控制 Host 任务看板、agent 播报与运行期间的系统空闲睡眠保护。',
   'settings.enabled': '启用任务看板',
-  'settings.enabledHint': '关闭后隐藏侧边栏入口与看板视图。',
+  'settings.enabledHint': '关闭后隐藏侧边栏入口与看板视图，并注销 task_board_* agent 工具；开启时任何会话都可以通过这些工具读写看板、子任务与定时计划。',
   'settings.announceToAgent': '向 agent 播报任务看板',
   'settings.announceToAgentHint': '开启：每条 agent 系统提示都会包含本看板的说明；关闭：不播报，agent 仅在用户主动提及时了解看板。',
   'settings.preventIdleSleep': '阻止系统空闲睡眠',
@@ -194,6 +198,36 @@ export const zh = {
   'settings.unsaved': '未保存',
   'settings.saveFailed': '部署未接受这些值，已保留供你修改。',
   'settings.invalidNumber': '请输入数字，留空则使用默认值。',
+  'settings.maxSubtaskDepth': '子任务深度上限',
+  'settings.maxSubtaskDepthHint': '默认 1：一个任务只允许一层子任务，子任务不能再创建或关联子任务。最大 3。执行父任务会并发执行它的整棵子任务树，层级越深，一次执行开启的会话越多。',
+  'settings.maxSubtaskDepthOption': '{depth} 层',
+  // 子任务（父子关系、级联执行、关联/解除关联）。
+  'detail.parent': '父任务',
+  'detail.parent.open': '打开父任务',
+  'detail.subtasks': '子任务',
+  'detail.subtasks.empty': '还没有子任务',
+  'detail.subtasks.add': '添加子任务',
+  'detail.subtasks.link': '关联现有任务',
+  'detail.subtasks.detach': '解除关联',
+  'detail.subtasks.runningLock': '子任务正在执行，结算后才能解除关联或改挂父任务',
+  'detail.subtasks.runHint': '执行本任务会同时并发执行它的 {count} 个子任务；子任务失败不影响其它子任务继续执行。',
+  'detail.subtasks.waiting': '等待子任务结算',
+  'detail.subtasks.depthLimit': '当前子任务深度上限为 {depth} 层，子任务不能再创建或关联子任务。',
+  'detail.subtasks.hostOnly': '连接 Host 后才能创建或关联子任务。',
+  'new.subtaskTitle': '新建子任务',
+  'new.subtaskInherit': '未单独选择的执行设置继承父任务（工作区、模式、权限、模型），可在此覆盖。',
+  'link.subtask.title': '关联现有任务',
+  'link.subtask.hint': '只能关联没有父任务的在看板任务；关联后它成为本任务的子任务。',
+  'link.subtask.empty': '没有可关联的任务',
+  'link.subtask.confirm': '关联',
+  'card.subtask': '子任务',
+  'card.subtasks': '{count} 子任务',
+  'card.subtasksFailed': '{count} 失败',
+  'card.subtasksRunning': '{count} 运行中',
+  'card.subtasksBreakdown': '子任务 {total}：已完成 {done}，运行中 {running}，失败 {failed}',
+  'board.hideSubtasks': '隐藏子任务',
+  'board.showSubtasks': '显示子任务',
+  'board.subtaskFilterHint': '看板默认只显示父任务；搜索或按标签筛选时会自动展开子任务。',
 } satisfies Record<string, string>
 
 /** en dictionary, complete against the zh key set. */
@@ -348,12 +382,16 @@ export const en: Record<keyof typeof zh, string> = {
   'exec.mode.brokenSuffix': ' (unavailable)',
   'exec.mode.removed': ' (removed)',
   'exec.permission.default': 'Session default',
+  'exec.permission.inheritParent': 'Inherit parent ({permission})',
   'exec.permission.read-only': 'Read-only',
   'exec.permission.workspace-write': 'Workspace Write',
   'exec.permission.danger-full-access': 'Full Access',
   'exec.model.default': 'Host default (agent-default-model)',
   'exec.model.unknown': ' (unknown / fallback to default)',
   'exec.reuseSession': 'Continue in the same conversation',
+  'exec.teamRun': 'Run with an Agent Team (Lead + teammates)',
+  'exec.teamRunHint': 'On: running this task starts one Lead session and spawns a teammate per subtask inside it, working in parallel (a subtask permission pin does not apply). Off: every member gets its own independent session.',
+  'exec.teamRunUnavailable': 'This deployment serves no Agent Teams service, so team runs cannot be enabled.',
   'exec.reuseSessionHint': 'When on, later runs continue in the previous session (when that session is idle and still exists) instead of starting a new conversation each time; the pinned permission and model above are re-applied on every reuse.',
   'detail.executionSettings': 'Execution Settings',
   'exec.hint': 'Applied when the task runs: the workspace decides where the execution session lands; the mode composes the session\'s agent preset; the permission is applied through the /permission command. Blank = runtime default.',
@@ -361,7 +399,7 @@ export const en: Record<keyof typeof zh, string> = {
   'settings.title': 'Task Board',
   'settings.description': 'Configure the Host task board, agent announcement, and idle-system-sleep protection while work is pending.',
   'settings.enabled': 'Enable the task board',
-  'settings.enabledHint': 'When off, the sidebar entry and board view are hidden.',
+  'settings.enabledHint': 'When off, the sidebar entry and board view are hidden and the task_board_* agent tools are unregistered; while on, any session can read and drive the board, its subtasks and its schedules through those tools.',
   'settings.announceToAgent': 'Announce the task board to agents',
   'settings.announceToAgentHint': 'On: every agent system prompt includes a note about this board. Off: no announcement; agents learn about the board only when you mention it.',
   'settings.preventIdleSleep': 'Prevent idle system sleep',
@@ -385,6 +423,36 @@ export const en: Record<keyof typeof zh, string> = {
   'settings.unsaved': 'Unsaved',
   'settings.saveFailed': 'The deployment did not accept these values; they were left for you to correct.',
   'settings.invalidNumber': 'Enter a number, or leave blank to use the default.',
+  'settings.maxSubtaskDepth': 'Subtask depth limit',
+  'settings.maxSubtaskDepthHint': 'Default 1: a task may carry one level of subtasks, and a subtask cannot create or link further subtasks. Maximum 3. Running a task also runs its whole subtask tree concurrently, and every extra level opens more sessions per run.',
+  'settings.maxSubtaskDepthOption': '{depth} levels',
+  // Subtasks (parent/child links, cascade runs, link/detach).
+  'detail.parent': 'Parent task',
+  'detail.parent.open': 'Open parent task',
+  'detail.subtasks': 'Subtasks',
+  'detail.subtasks.empty': 'No subtasks yet',
+  'detail.subtasks.add': 'Add subtask',
+  'detail.subtasks.link': 'Link existing task',
+  'detail.subtasks.detach': 'Detach',
+  'detail.subtasks.runningLock': 'This subtask is running; it can be detached or re-linked once it settles',
+  'detail.subtasks.runHint': 'Running this task also runs its {count} subtasks concurrently; one subtask failing does not stop the others.',
+  'detail.subtasks.waiting': 'Waiting for subtasks',
+  'detail.subtasks.depthLimit': 'The subtask depth limit is {depth}; a subtask cannot create or link further subtasks.',
+  'detail.subtasks.hostOnly': 'Connect to the Host to create or link subtasks.',
+  'new.subtaskTitle': 'New Subtask',
+  'new.subtaskInherit': 'Execution settings left unset inherit the parent (workspace, mode, permission, model); override any of them here.',
+  'link.subtask.title': 'Link an existing task',
+  'link.subtask.hint': 'Only an on-board task without a parent can be linked; it then becomes a subtask of this task.',
+  'link.subtask.empty': 'No task can be linked',
+  'link.subtask.confirm': 'Link',
+  'card.subtask': 'subtask',
+  'card.subtasks': '{count} subtasks',
+  'card.subtasksFailed': '{count} failed',
+  'card.subtasksRunning': '{count} running',
+  'card.subtasksBreakdown': 'Subtasks {total}: {done} done, {running} running, {failed} failed',
+  'board.hideSubtasks': 'Hide subtasks',
+  'board.showSubtasks': 'Show subtasks',
+  'board.subtaskFilterHint': 'The board shows parent tasks only; a text or label filter reveals the subtasks automatically.',
 }
 
 /** The dictionary key union. */

package/src/client/native-panel.tsx

@@ -0,0 +1,124 @@
+/**
+ * Native panel registration for the task board.
+ *
+ * The board is an official-style center-column panel, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail, the panel switch and the window-chrome interplay exactly as it does for
+ * the shipped Plugins and Schedule pages, so the board renders through the same
+ * container the desktop application's Plugins page uses.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * @module @linxin666/dsh-client-ui-task-board/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+import { TASK_BOARD_PANEL_ID, type BoardController } from '../core/controller.ts'
+import { TaskBoard } from './board/TaskBoard.tsx'
+import { t } from './locales.ts'
+import css from './board.module.css'
+
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { TASK_BOARD_PANEL_ID }
+
+/** Row order among the shell's global panel rows (Plugins is 0, Schedule 10). */
+const PANEL_ORDER = 20
+
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM the
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative board glyph.
+ */
+export function TaskBoardPanelIcon({ size }: { size: number; active: boolean }): React.ReactElement {
+  return (
+    <svg
+      data-dsh-panel-entry={TASK_BOARD_PANEL_ID}
+      viewBox="0 0 16 16"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.3"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="2" y="2.5" width="12" height="11" rx="1.5" />
+      <path d="M2 6.5h12M6.5 6.5v7" />
+    </svg>
+  )
+}
+
+/**
+ * The main-slot page. The layout mounts it only while the board is the selected
+ * panel, so the conversation keeps the center column untouched the rest of the
+ * time; the wrapper carries the pinned `data-dsh-taskboard-view` semantic
+ * anchor (L2 contract, skins) and the container query context the board's
+ * responsive rules read.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the board page.
+ */
+export function TaskBoardPanel({ controller }: { controller: BoardController }): React.ReactElement {
+  return (
+    <div className={css.panel} data-dsh-taskboard-view="" data-dsh-plugin="task-board">
+      <TaskBoard controller={controller} />
+    </div>
+  )
+}
+
+/** The injected face both registrations receive. */
+interface PanelFace {
+  controller: BoardController
+}
+
+/**
+ * Register the board's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the board simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the board controller the page and the row drive.
+ * @returns disposer releasing both registrations.
+ */
+export function registerTaskBoardPanel(ctx: ClientContext, controller: BoardController): () => void {
+  const slots = ctx.slots as {
+    inject(key: string, callback: () => () => void): () => void
+    register(options: Record<string, unknown>, component: unknown): () => void
+  }
+  const disposers: Array<() => void> = []
+
+  disposers.push(slots.inject('sidebar.panellist', () => slots.register({
+    name: 'sidebar.panellist',
+    id: TASK_BOARD_PANEL_ID,
+    order: PANEL_ORDER,
+    // The shell resolves this through resolveSlotLabel on every locale change,
+    // so the module-level translate reads the active language at call time.
+    label: () => t('entry.label'),
+  }, TaskBoardPanelIcon)))
+
+  disposers.push(slots.inject('main', () => slots.register({
+    name: 'main',
+    key: TASK_BOARD_PANEL_ID,
+    inject: (): PanelFace => ({ controller }),
+  }, TaskBoardPanel as never)))
+
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose()
+  }
+}

package/src/client/settings-entry-form.ts

@@ -0,0 +1,142 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-entry-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-entry-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Family settings form bound to the profile entry id a Host actually serves.
+ *
+ * Under the 0.1.7 settings model a form is addressed by PROFILE ENTRY ID, while
+ * a family card knows only its own settings namespace. The family binder
+ * (`ctx.get('webUiSettings')`, published by dsh-web-settings) resolves one onto
+ * the other and is the preferred transport; this module is the fallback for a
+ * page that serves no binder — the group plugin is not installed, or its client
+ * half has not applied yet (the aggregate mounts its children in order, and a
+ * child still waiting on its own injects publishes nothing).
+ *
+ * The shared describe mirror is the only local evidence of which row id this
+ * profile serves, but it answers asynchronously: at plugin activation it usually
+ * holds nothing yet. A one-shot guess therefore cannot be right for every
+ * deployment, and the form is bound once per session:
+ *
+ * - binding the bare namespace made every save answer `No configurable plugin
+ *   entry "<namespace>"` on an aggregate install (the namespace is not an entry
+ *   id there), which the card reported as "the deployment did not accept these
+ *   values";
+ * - binding the aggregate row id would break a standalone install, whose row id
+ *   is the namespace or the package's own `ui-*` row.
+ *
+ * So the fallback starts on the most likely row and REBINDS the moment the
+ * mirror names one of this package's rows. Until the mirror answers, the form
+ * reports the binding it holds (usually `loading`), which the card renders as an
+ * unavailable form rather than a doomed one.
+ */
+import type { ConfigForm, ConfigFormSnapshot, ConfigForms } from '@deepseek-ai/dsh-client-ui-settings/client'
+
+/** Options of {@link createServedEntryForm}. */
+export interface ServedEntryFormOptions<T> {
+  /** The shared configuration forms service (`ctx.configForms`). */
+  forms: ConfigForms
+  /**
+   * Profile entry ids this package's rows carry, most likely first: the
+   * aggregate's generated row, the package's own standalone row, then the bare
+   * namespace. The first is the fallback while the mirror has no answer; the
+   * last is the answer when the mirror serves none of them.
+   */
+  entryIds: readonly string[]
+}
+
+/** The snapshot a form reports before the Host has answered with this entry. */
+function pendingSnapshot<T>(): ConfigFormSnapshot<T> {
+  return {
+    status: 'loading',
+    value: undefined,
+    base: undefined,
+    user: undefined,
+    revision: undefined,
+    writable: false,
+    mode: 'host',
+  }
+}
+
+/**
+ * Create a settings form bound to the profile entry id this Host serves, and
+ * rebound whenever the shared describe mirror names a different one of this
+ * package's rows.
+ * @param options - the shared forms service and this package's candidate row ids.
+ * @returns a form delegating to the currently resolved entry's own form.
+ */
+export function createServedEntryForm<T>(options: ServedEntryFormOptions<T>): ConfigForm<T> {
+  const { forms, entryIds } = options
+  const fallbackId = entryIds[0]
+  const namespaceId = entryIds[entryIds.length - 1]
+  const listeners = new Set<() => void>()
+  let boundId: string | undefined
+  let bound: ConfigForm<T> | undefined
+  let offBound: (() => void) | undefined
+  let snapshot: ConfigFormSnapshot<T> = pendingSnapshot<T>()
+
+  /** Republish: the delegated snapshot when one is bound, the pending one otherwise. */
+  const publish = (): void => {
+    if (bound !== undefined) snapshot = bound.getSnapshot()
+    for (const listener of [...listeners]) listener()
+  }
+
+  /**
+   * The entry id the mirror currently justifies. An unanswered or empty mirror
+   * is not evidence of absence, so it keeps the first candidate; a mirror that
+   * answers without any of this package's rows leaves the namespace itself.
+   * @returns the entry id to bind.
+   */
+  const resolve = (): string => {
+    let served: readonly string[] | undefined
+    try {
+      served = forms.describe().getSnapshot().view?.namespaces.map(row => row.ns)
+    } catch {
+      // A mirror that refuses the read is unanswered too, not absent.
+      served = undefined
+    }
+    if (served === undefined || served.length === 0) return fallbackId
+    return entryIds.find(id => served.includes(id)) ?? namespaceId
+  }
+
+  /** Bind (or rebind) the resolved entry's form; a no-op while it is unchanged. */
+  const bind = (): void => {
+    const target = resolve()
+    if (target === boundId) return
+    offBound?.()
+    offBound = undefined
+    let form: ConfigForm<T>
+    try {
+      form = forms.get<T>(target)
+    } catch {
+      // A service that refuses the id stays unbound; the next mirror answer
+      // retries rather than pinning a wrong entry for the session.
+      boundId = undefined
+      return
+    }
+    boundId = target
+    bound = form
+    offBound = form.subscribe(() => { publish() })
+    publish()
+  }
+
+  // The mirror subscription lives for the page: the card owns its form for the
+  // session, and the ConfigForm contract carries no disposer to hang it on. The
+  // callback is cheap (a resolve plus a no-op while the id is unchanged). A
+  // mirror without a subscription seat keeps the initial binding.
+  try {
+    forms.describe().subscribe(() => { bind() })
+  } catch {
+    // A describe face that refuses the subscription: the initial binding stands.
+  }
+  bind()
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => { listeners.delete(listener) }
+    },
+    set: (field, value) => bound?.set(field, value) ?? Promise.resolve(false),
+    unset: (field) => bound?.unset(field) ?? Promise.resolve(false),
+    mutate: (ops, expectedRevision) => bound?.mutate(ops, expectedRevision) ?? Promise.resolve(false),
+  }
+}