@linxin666/dsh-client-ui-task-board 0.4.2 → 0.4.4

package/src/client/locales.ts

@@ -29,8 +29,11 @@ export const zh = {
   'board.updated': '更新于',
   'board.created': '创建于',
   'board.hostError': 'Host 操作失败：{error}',
-  'board.hostError.notMounted': '任务看板的后台接口没有挂载：宿主可能没有加载该插件，也可能后台数据正被另一个 DSH 实例占用。重启 DSH 服务后再试',
+  'board.hostError.notMounted': '任务看板的后台接口没有挂载：宿主没有加载这个插件（可能未安装、未启用，或该行启动失败）。重启 DSH 服务后再试',
+  'board.hostError.ledgerLocked': '任务看板的账本已被另一个 DSH 进程占用（占用者 pid {pid}），本实例没有注册后台接口：关闭那个 DSH 实例，或等它退出后再点重试——反复重启本实例无效（宿主原因：{detail}）',
+  'board.hostError.degraded': '任务看板这一行在启动时降级，后台接口没有注册（宿主原因：{detail}）',
   'board.hostError.unauthorized': '登录状态已失效，请刷新页面后重试',
+  'board.hostError.forbidden': '当前环境未通过同源校验：桌面外壳或反向代理可能未传递浏览器标记，也没有携带宿主认证凭据',
   'board.hostError.locked': '任务看板的后台数据被占用：{detail}',
   'board.hostError.timeout': '后台 {seconds} 秒内没有响应，请稍后重试',
   'board.hostError.unreachable': '连接不上本机 DSH 服务，请确认它仍在运行',
@@ -55,6 +58,20 @@ export const zh = {
   'new.aiParseFailed': '解析失败：{error}',
   'board.retryHost': '重试连接 Host',
   'board.hostMeta': 'Host 时区 {timeZone} · revision {revision}',
+  // 新建/编辑对话框的区域分组：折叠后每个区域仍以一行摘要显示当前配置。
+  'new.section.parse': 'AI 解析',
+  'new.section.content': '任务内容',
+  'new.section.labels': '标签',
+  'new.section.execution': '执行设置',
+  'new.section.run': '运行方式',
+  'new.section.handover': '交接与续跑',
+  'new.section.schedule': '定时运行',
+  'new.summary.none': '未设置',
+  'new.summary.labelCount': '{count} 个标签',
+  'new.summary.filled': '已填写',
+  'new.summary.scheduleOff': '未启用',
+  'new.summary.multiRound': '多轮 /goal',
+  'new.summary.singleRound': '单轮',
   'new.title': '标题',
   'new.titlePlaceholder': '一句话描述要做什么',
   'new.description': '描述',
@@ -146,13 +163,31 @@ export const zh = {
   'detail.schedule.invalid': 'Cron 表达式无效',
   'detail.schedule.notScheduled': '尚未排程',
   'detail.schedule.dueSoon': '即将运行',
+  'detail.schedule.timeZone': '时区',
+  'detail.schedule.timeZoneHost': 'Host 时区（{timeZone}）',
+  'detail.schedule.timeZoneHostUnknown': 'Host 时区（未知）',
+  'detail.schedule.timeZoneHint': 'Cron 的墙上时间按此时区解读；夏令时跳变会跳过不存在的时刻，重复的时刻只触发一次。',
+  'detail.schedule.timeZoneSearch': '搜索时区…',
+  'detail.schedule.timeZoneNone': '没有匹配的时区',
+  'detail.schedule.nextRunOverdue': '已逾期 {duration}',
+  'detail.schedule.duration.days': '{count} 天',
+  'detail.schedule.duration.hours': '{count} 小时',
+  'detail.schedule.duration.minutes': '{count} 分钟',
+  'detail.schedule.duration.seconds': '{count} 秒',
   'card.scheduled': '定时',
   'new.workspace': '工作区',
-  'new.mode': '模式',
+  'new.agentPreset': 'Agent 预设',
   'new.permission': '权限',
   'new.model': '模型',
   'exec.workspace.recent': '最近使用（默认）',
-  'exec.mode.default': '部署默认',
+  'exec.mode.inherit': '继承（部署默认）',
+  'exec.mode.inheritWith': '继承（部署默认：{preset}）',
+  'exec.mode.builtinGroup': '内置预设',
+  'exec.mode.customGroup': '自定义预设',
+  'preset.builtin.standard': '标准',
+  'preset.builtin.ptc': 'PTC（程序化工具调用）',
+  'preset.builtin.minimal': '极简',
+  'preset.builtin.cordis': 'Cordis',
   'exec.mode.defaultSuffix': '（默认）',
   'exec.mode.brokenSuffix': '（不可用）',
   'exec.mode.removed': '（已移除）',
@@ -168,8 +203,10 @@ export const zh = {
   'exec.teamRunHint': '开启后：执行本任务只启动一个 Leader 会话，每个子任务由它派生为 teammate 并在该会话内并行工作（子任务自身的权限钉住不适用）。关闭则每个成员各开独立会话。',
   'exec.teamRunUnavailable': '当前部署未提供 Agent Teams 服务，无法启用。',
   'exec.reuseSessionHint': '开启后，本任务的后续执行在上一次会话里继续（该会话空闲且仍存在时），不再每次新建对话；每次复用时都会重新应用上面钉住的权限与模型。',
+  'exec.goalRun': '以 dsh 内置的 /goal 开始执行任务',
+  'exec.goalRunHint': '默认开启：执行时把任务目标作为持久目标交给 dsh 内置的 /goal，会话会自动续跑多轮，直到 agent 标记目标完成；看板在该目标真正结束后才结算本次执行。关闭则只执行一轮普通对话。',
   'detail.executionSettings': '执行设置',
-  'exec.hint': '执行时生效：工作区决定执行会话落在哪个工作区；模式决定会话的 agent 预设；权限经 /permission 命令应用到会话。留空则使用运行时默认。',
+  'exec.hint': '执行时生效：工作区决定执行会话落在哪个工作区；Agent 预设决定会话的组合（工具面与提示词段）；权限经 /permission 命令应用到会话。留空则继承部署默认。',
   // 插件设置卡片（settings.plugin.item 席位）。
   'settings.title': '任务看板',
   'settings.description': '控制 Host 任务看板、agent 播报与运行期间的系统空闲睡眠保护。',
@@ -254,8 +291,11 @@ export const en: Record<keyof typeof zh, string> = {
   'board.updated': 'Updated',
   'board.created': 'Created',
   'board.hostError': 'Host action failed: {error}',
-  'board.hostError.notMounted': 'The task board Host API is not mounted: the Host may not have loaded the plugin, or another DSH instance holds the ledger. Restart the DSH service and try again',
+  'board.hostError.notMounted': 'The task board Host API is not mounted: the Host did not load this plugin (not installed, disabled, or its row failed to start). Restart the DSH service and try again',
+  'board.hostError.ledgerLocked': 'Another DSH process (pid {pid}) holds the task board ledger, so this instance registered no Host API: close that DSH instance, or wait for it to exit and retry. Restarting this instance cannot help (reason: {detail})',
+  'board.hostError.degraded': 'The task board row degraded during start, so its Host API was not registered: {detail}',
   'board.hostError.unauthorized': 'This session is no longer signed in; reload the page and try again',
+  'board.hostError.forbidden': 'The request did not pass the same-origin fence: the desktop shell or reverse proxy may not have forwarded browser credentials',
   'board.hostError.locked': 'The task board ledger is locked: {detail}',
   'board.hostError.timeout': 'The Host did not answer within {seconds}s; try again shortly',
   'board.hostError.unreachable': 'Cannot reach the local DSH service; make sure it is still running',
@@ -280,6 +320,20 @@ export const en: Record<keyof typeof zh, string> = {
   'new.aiParseFailed': 'Parsing failed: {error}',
   'board.retryHost': 'Retry Host connection',
   'board.hostMeta': 'Host time zone {timeZone} · revision {revision}',
+  // Create/edit dialog regions: a collapsed region still shows a one-line summary of its values.
+  'new.section.parse': 'AI Parse',
+  'new.section.content': 'Task Content',
+  'new.section.labels': 'Tags',
+  'new.section.execution': 'Execution Settings',
+  'new.section.run': 'Run Mode',
+  'new.section.handover': 'Handover',
+  'new.section.schedule': 'Scheduled Runs',
+  'new.summary.none': 'Not set',
+  'new.summary.labelCount': '{count} tags',
+  'new.summary.filled': 'Filled',
+  'new.summary.scheduleOff': 'Off',
+  'new.summary.multiRound': 'multi-round /goal',
+  'new.summary.singleRound': 'single round',
   'new.title': 'Title',
   'new.titlePlaceholder': 'What should be done, in one line',
   'new.description': 'Description',
@@ -371,13 +425,31 @@ export const en: Record<keyof typeof zh, string> = {
   'detail.schedule.invalid': 'Invalid cron expression',
   'detail.schedule.notScheduled': 'Not scheduled yet',
   'detail.schedule.dueSoon': 'Due soon',
+  'detail.schedule.timeZone': 'Time zone',
+  'detail.schedule.timeZoneHost': 'Host time zone ({timeZone})',
+  'detail.schedule.timeZoneHostUnknown': 'Host time zone (unknown)',
+  'detail.schedule.timeZoneHint': 'The cron wall clock is read in this zone; daylight-saving gaps are skipped and a repeated time fires once.',
+  'detail.schedule.timeZoneSearch': 'Search time zones…',
+  'detail.schedule.timeZoneNone': 'No matching time zone',
+  'detail.schedule.nextRunOverdue': 'Overdue by {duration}',
+  'detail.schedule.duration.days': '{count}d',
+  'detail.schedule.duration.hours': '{count}h',
+  'detail.schedule.duration.minutes': '{count}m',
+  'detail.schedule.duration.seconds': '{count}s',
   'card.scheduled': 'scheduled',
   'new.workspace': 'Workspace',
-  'new.mode': 'Mode',
+  'new.agentPreset': 'Agent preset',
   'new.permission': 'Permission',
   'new.model': 'Model',
   'exec.workspace.recent': 'Most recent (default)',
-  'exec.mode.default': 'Deployment default',
+  'exec.mode.inherit': 'Inherit (deployment default)',
+  'exec.mode.inheritWith': 'Inherit (deployment default: {preset})',
+  'exec.mode.builtinGroup': 'Built-in presets',
+  'exec.mode.customGroup': 'Custom presets',
+  'preset.builtin.standard': 'Standard',
+  'preset.builtin.ptc': 'PTC (programmatic tool calling)',
+  'preset.builtin.minimal': 'Minimal',
+  'preset.builtin.cordis': 'Cordis',
   'exec.mode.defaultSuffix': ' (default)',
   'exec.mode.brokenSuffix': ' (unavailable)',
   'exec.mode.removed': ' (removed)',
@@ -393,8 +465,10 @@ export const en: Record<keyof typeof zh, string> = {
   '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.',
+  'exec.goalRun': "Start the run with dsh's built-in /goal",
+  'exec.goalRunHint': 'On by default: the run arms dsh built-in /goal with the task objective, so the session keeps working automatic continuation rounds until the agent marks the goal complete, and the board settles the execution only when that goal really ends. Off: one plain turn.',
   '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.',
+  'exec.hint': 'Applied when the task runs: the workspace decides where the execution session lands; the agent preset composes the session (tool face and prompt sections); the permission is applied through the /permission command. Blank inherits the deployment default.',
   // Plugin settings card (the `settings.plugin.item` seat).
   'settings.title': 'Task Board',
   'settings.description': 'Configure the Host task board, agent announcement, and idle-system-sleep protection while work is pending.',

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/schedule-zone.ts

@@ -0,0 +1,135 @@
+/**
+ * Shared scheduling helpers for the board's schedule editors (the new-task
+ * dialog and the task detail panel): the time-zone picker inventory, the
+ * relative next-run wording, and the combined absolute + relative label.
+ *
+ * Everything here is browser-side presentation built on the same pure engine
+ * the Host schedules with (`core/schedule.ts`), so the preview a user sees is
+ * computed by the code that will actually arm the rule.
+ */
+import { isValidTimeZone } from '../core/schedule.ts'
+import { t } from './locales.ts'
+
+/** One selectable zone, in the order the picker shows it. */
+export interface ZoneChoice {
+  /** Canonical IANA id, or `''` for the Host-zone entry. */
+  id: string
+  /** Display label. */
+  label: string
+}
+
+/**
+ * The runtime's zone inventory, read once. `Intl.supportedValuesOf` is not
+ * available in every engine, so a missing inventory degrades to `UTC` rather
+ * than offering a list that cannot resolve.
+ *
+ * The inventory is deliberately NOT truncated. A capped list silently omits
+ * whole regions, and because a `<select>` whose value matches no option falls
+ * back to its first option, an omitted zone would make the control show — and
+ * then save — a different zone than the rule actually stores.
+ */
+let inventoryCache: readonly string[] | undefined
+
+function zoneInventory(): readonly string[] {
+  if (inventoryCache !== undefined) return inventoryCache
+  let inventory: readonly string[] = []
+  try {
+    inventory = typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : []
+  } catch {
+    inventory = []
+  }
+  inventoryCache = inventory.length > 0 ? inventory : ['UTC']
+  return inventoryCache
+}
+
+/**
+ * Zones offered by the picker: the Host zone first (the default, and the entry
+ * a rule with no stored zone follows), then the runtime's own inventory.
+ *
+ * The Host entry is always present, even before the Host snapshot reports a
+ * zone: it is the entry that stores no zone, so dropping it would leave a rule
+ * unable to express "follow the Host" and would let the control silently
+ * display an unrelated zone.
+ *
+ * A stored zone the inventory does not list (a rule written on another machine
+ * or under a different ICU build) is appended, so opening the editor can never
+ * silently rewrite the rule's zone.
+ * @param hostTimeZone - zone the Host reported for this deployment, when known.
+ * @param storedTimeZone - zone the edited rule already stores, when any.
+ * @returns the de-duplicated choice list.
+ */
+export function zoneChoices(hostTimeZone: string | undefined, storedTimeZone?: string): ZoneChoice[] {
+  const host = hostTimeZone !== undefined && isValidTimeZone(hostTimeZone) ? hostTimeZone : undefined
+  const choices: ZoneChoice[] = []
+  const seen = new Set<string>()
+  choices.push({
+    id: '',
+    label: host === undefined
+      ? t('detail.schedule.timeZoneHostUnknown')
+      : t('detail.schedule.timeZoneHost', { timeZone: host }),
+  })
+  if (host !== undefined) seen.add(host)
+  for (const zone of zoneInventory()) {
+    if (seen.has(zone) || !isValidTimeZone(zone)) continue
+    seen.add(zone)
+    choices.push({ id: zone, label: zone })
+  }
+  if (storedTimeZone !== undefined && !seen.has(storedTimeZone) && isValidTimeZone(storedTimeZone)) {
+    choices.push({ id: storedTimeZone, label: storedTimeZone })
+  }
+  return choices
+}
+
+/** Compact duration parts, largest unit first, with at most two units kept. */
+function durationParts(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000))
+  const days = Math.floor(total / 86400)
+  const hours = Math.floor((total % 86400) / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const seconds = total % 60
+  const parts: string[] = []
+  if (days > 0) parts.push(t('detail.schedule.duration.days', { count: String(days) }))
+  if (hours > 0) parts.push(t('detail.schedule.duration.hours', { count: String(hours) }))
+  if (minutes > 0) parts.push(t('detail.schedule.duration.minutes', { count: String(minutes) }))
+  if (parts.length < 2 && (seconds > 0 || parts.length === 0)) {
+    parts.push(t('detail.schedule.duration.seconds', { count: String(seconds) }))
+  }
+  return parts.slice(0, 2).join(' ')
+}
+
+/**
+ * The relative half of a next-run label: how far away the instant is, or how
+ * far past it the board is running. `now` is passed in rather than sampled so
+ * callers can share one clock reading across a row, and tests stay
+ * deterministic.
+ * @param targetMs - the instant being described.
+ * @param now - the reference instant.
+ * @returns localized relative wording.
+ */
+export function relativeTimeLabel(targetMs: number, now: number): string {
+  const delta = targetMs - now
+  if (delta < 0) return t('detail.schedule.nextRunOverdue', { duration: durationParts(-delta) })
+  return `${durationParts(delta)}`
+}
+
+/**
+ * The full next-run label: the absolute wall clock in the schedule's own zone,
+ * plus the relative distance in parentheses. Showing both matters because a
+ * rule's zone can differ from the reader's, so the wall clock alone is
+ * ambiguous and the distance alone loses the actual moment.
+ * @param targetMs - the instant being described.
+ * @param timeZone - zone to render the absolute half in.
+ * @param formatAbsolute - formatter for the absolute half (keeps Intl caching in the caller).
+ * @param now - the reference instant.
+ * @param translate - translate function, bound so this module stays dependency-light.
+ * @returns the combined label.
+ */
+export function nextRunLabel(
+  targetMs: number,
+  timeZone: string | undefined,
+  formatAbsolute: (ms: number, timeZone?: string) => string,
+  now: number,
+): string {
+  const absolute = formatAbsolute(targetMs, timeZone)
+  return `${absolute} (${relativeTimeLabel(targetMs, now)})`
+}

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),
+  }
+}