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

package/src/client/board/TaskDetail.tsx

@@ -5,7 +5,7 @@
  * execution's session transcript.
  */
 import { useEffect, useState } from 'react'
-import type { BoardController } from '../../core/controller.ts'
+import type { BoardController, ControllerSnapshot } from '../../core/controller.ts'
 import { isValidCron } from '../../core/schedule.ts'
 import { MANUAL_STATUSES, TASK_PERMISSIONS, tagTone, type ExecutionRecord, type TaskPermission, type TaskRecord } from '../../core/tasks.ts'
 import { canEditTaskContent } from '../../core/use-cases/task-update.ts'
@@ -13,11 +13,13 @@ import { requiresPermissionConfirmation } from '../../core/handover.ts'
 import { DEFAULT_SUBTASK_DEPTH, directSubtasks, taskDepth } from '../../core/subtask.ts'
 import { t, type TaskBoardKey } from '../locales.ts'
 import { SCHEDULE_PRESETS } from '../schedule-presets.ts'
+import { nextRunLabel, zoneChoices } from '../schedule-zone.ts'
 import css from '../board.module.css'
 import { ConfirmDialog } from './ConfirmDialog.tsx'
 import { EditTaskModal, EditTagsModal } from './EditTaskModal.tsx'
 import { LinkSubtaskModal } from './LinkSubtaskModal.tsx'
 import { NewTaskModal } from './NewTaskModal.tsx'
+import { inheritPresetLabel, presetLabel } from './preset-label.ts'
 import { formatHostTimestamp, formatTime } from './TaskCard.tsx'
 import { STATUS_KEY } from './status-key.ts'
 
@@ -63,20 +65,16 @@ function ExecutionRow({ execution, timeZone, onOpen }: { execution: ExecutionRec
 }
 
 /** The execution-target editor: workspace / mode / permission pickers. */
-function ExecutionSettingsSection({ controller, task, pending }: { controller: BoardController; task: TaskRecord; pending: boolean }) {
-  const [options, setOptions] = useState(controller.getSnapshot().executionOptions)
-  // Whether this deployment serves the Agent Teams service: without it a team
-  // run is refused, so the opt-in is offered read-only with the reason.
-  const teamRunOffered = (): boolean => controller.getSnapshot().host?.teamRunAvailable === true
-  const [teamRunAvailable, setTeamRunAvailable] = useState(teamRunOffered())
-  useEffect(
-    () => controller.subscribe(() => {
-      const snapshot = controller.getSnapshot()
-      setOptions(snapshot.executionOptions)
-      setTeamRunAvailable(snapshot.host?.teamRunAvailable === true)
-    }),
-    [controller],
-  )
+function ExecutionSettingsSection({ controller, task, pending, executionOptions, teamRunAvailable }: {
+  controller: BoardController
+  task: TaskRecord
+  pending: boolean
+  /** Picker option sets, owned by the detail overlay's snapshot. */
+  executionOptions: ControllerSnapshot['executionOptions']
+  /** Whether this deployment serves the Agent Teams service. */
+  teamRunAvailable: boolean
+}) {
+  const options = executionOptions
   const workspaceId = task.workspaceId ?? ''
   const mode = task.mode ?? ''
   const permission = task.permission ?? ''
@@ -107,18 +105,18 @@ function ExecutionSettingsSection({ controller, task, pending }: { controller: B
         </select>
       </label>
       <label className={css.field}>
-        <span className={css.fieldLabel}>{t('new.mode')}</span>
+        <span className={css.fieldLabel}>{t('new.agentPreset')}</span>
         <select
           className={css.select}
           value={mode}
           disabled={pending}
           onChange={event => { controller.updateTask(task.id, { mode: event.target.value }) }}
         >
-          <option value="">{t('exec.mode.default')}</option>
+          <option value="">{inheritPresetLabel(options.presets)}</option>
           {!modeKnown && <option value={mode}>{mode}{t('exec.mode.removed')}</option>}
           {options.presets.map(preset => (
             <option key={preset.id} value={preset.id} disabled={preset.broken !== undefined}>
-              {preset.name ?? preset.id}
+              {presetLabel(preset)}
               {preset.isDefault ? t('exec.mode.defaultSuffix') : ''}
               {preset.broken !== undefined ? t('exec.mode.brokenSuffix') : ''}
             </option>
@@ -164,6 +162,16 @@ function ExecutionSettingsSection({ controller, task, pending }: { controller: B
         <span>{t('exec.reuseSession')}</span>
       </label>
       <p className={css.detailText}>{t('exec.reuseSessionHint')}</p>
+      <label className={css.scheduleToggle}>
+        <input
+          type="checkbox"
+          checked={task.goalRun !== false}
+          disabled={pending}
+          onChange={event => { controller.updateTask(task.id, { goalRun: event.target.checked }) }}
+        />
+        <span>{t('exec.goalRun')}</span>
+      </label>
+      <p className={css.detailText}>{t('exec.goalRunHint')}</p>
       <label className={css.scheduleToggle}>
         <input
           type="checkbox"
@@ -178,7 +186,7 @@ function ExecutionSettingsSection({ controller, task, pending }: { controller: B
   )
 }
 
-/** The scheduled-runs editor: enable toggle, cron input + presets, next-run info. */
+/** The scheduled-runs editor: enable toggle, cron input + presets, zone, next-run info. */
 function ScheduleSection({ controller, task, pending }: { controller: BoardController; task: TaskRecord; pending: boolean }) {
   const schedule = task.schedule
   const [cron, setCron] = useState(schedule?.cron ?? '0 9 * * *')
@@ -186,7 +194,12 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
   const [nextRunAt, setNextRunAt] = useState<number | undefined>(schedule?.nextRunAt)
   const [lastTriggeredAt, setLastTriggeredAt] = useState<number | undefined>(schedule?.lastTriggeredAt)
   const [error, setError] = useState<string | undefined>(undefined)
-  const timeZone = controller.getSnapshot().host?.scheduler.timeZone
+  const hostTimeZone = controller.getSnapshot().host?.scheduler.timeZone
+  // The rule's own zone; '' means "follow the Host zone" (no stored zone).
+  const [zone, setZone] = useState<string>(schedule?.timeZone ?? '')
+  // One clock reading per render pass, so the absolute and relative halves of
+  // the label always describe the same instant.
+  const now = Date.now()
 
   // Keep the editor in sync when the task record changes underneath (the
   // schedule rolls forward as runs trigger).
@@ -195,8 +208,9 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
     setEnabled(schedule?.enabled ?? false)
     setNextRunAt(schedule?.nextRunAt)
     setLastTriggeredAt(schedule?.lastTriggeredAt)
+    setZone(schedule?.timeZone ?? '')
     setError(undefined)
-  }, [task.id, schedule?.enabled, schedule?.cron, schedule?.nextRunAt, schedule?.lastTriggeredAt])
+  }, [task.id, schedule?.enabled, schedule?.cron, schedule?.timeZone, schedule?.nextRunAt, schedule?.lastTriggeredAt])
 
   /** Validate + persist the current cron text (Enter or blur). */
   const saveCron = (value: string): void => {
@@ -210,6 +224,16 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
     controller.setSchedule(task.id, { cron: trimmed })
   }
 
+  /**
+   * Change the rule's zone. `''` clears the stored zone, which is how a user
+   * returns a rule to following the Host zone.
+   */
+  const changeZone = (value: string): void => {
+    setZone(value)
+    setError(undefined)
+    controller.setSchedule(task.id, { timeZone: value === '' ? null : value })
+  }
+
   /** Arm/disarm the schedule (arming first persists the edited cron). */
   const toggleEnabled = (next: boolean): void => {
     const trimmed = cron.trim()
@@ -232,12 +256,18 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
     controller.setSchedule(task.id, { cron: preset })
   }
 
+  // The zone the rule's wall clock is actually read in: its own when set,
+  // otherwise the Host zone. The preview must use the same one the Host will.
+  const effectiveZone = zone === '' ? hostTimeZone : zone
   const nextLabel = !enabled || nextRunAt === undefined
     ? t('detail.schedule.notScheduled')
-    : nextRunAt <= Date.now()
+    : nextRunAt <= now
       ? t('detail.schedule.dueSoon')
-      : formatHostTimestamp(nextRunAt, timeZone)
-  const lastLabel = lastTriggeredAt === undefined ? '—' : formatHostTimestamp(lastTriggeredAt, timeZone)
+      : nextRunLabel(nextRunAt, effectiveZone, formatHostTimestamp, now)
+  const lastLabel = lastTriggeredAt === undefined ? '—' : formatHostTimestamp(lastTriggeredAt, effectiveZone)
+  // The rule's own stored zone rides the list even when this runtime's
+  // inventory does not carry it, so opening the editor cannot rewrite it.
+  const zones = zoneChoices(hostTimeZone, schedule?.timeZone)
 
   return (
     <section className={css.detailSection}>
@@ -276,6 +306,23 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
           ))}
         </select>
       </div>
+      {/* A list is used instead of a free-text field so only zones the Host can
+          also resolve are offered; the Host zone entry clears the stored value. */}
+      <label className={css.scheduleZone}>
+        <span>{t('detail.schedule.timeZone')}</span>
+        <select
+          className={css.schedulePreset}
+          value={zone}
+          disabled={pending}
+          aria-label={t('detail.schedule.timeZone')}
+          title={t('detail.schedule.timeZoneHint')}
+          onChange={event => { changeZone(event.target.value) }}
+        >
+          {zones.map(choice => (
+            <option key={choice.id === '' ? '__host' : choice.id} value={choice.id}>{choice.label}</option>
+          ))}
+        </select>
+      </label>
       {error !== undefined && <p className={css.formError}>{error}</p>}
       <p className={css.scheduleMeta}>
         {t('detail.schedule.nextRun')} {nextLabel}
@@ -290,17 +337,14 @@ function ScheduleSection({ controller, task, pending }: { controller: BoardContr
  * and the actions that grow or prune the tree. Every gate here mirrors the
  * Host lineage gate for affordance only; the Host re-checks the action.
  */
-function SubtaskSection({ controller, task, pending, archived }: {
+function SubtaskSection({ controller, task, pending, archived, snapshot }: {
   controller: BoardController
   task: TaskRecord
   pending: boolean
   archived: boolean
+  /** Detail-overlay snapshot; the overlay already re-renders on every notify. */
+  snapshot: ControllerSnapshot
 }) {
-  const [snapshot, setSnapshot] = useState(controller.getSnapshot())
-  useEffect(
-    () => controller.subscribe(() => setSnapshot(controller.getSnapshot())),
-    [controller],
-  )
   const [showAdd, setShowAdd] = useState(false)
   const [showLink, setShowLink] = useState(false)
   const tasks = snapshot.tasks
@@ -440,7 +484,7 @@ export function TaskDetail({ controller, task }: { controller: BoardController;
             <p className={css.detailText}>{current.description !== '' ? current.description : '—'}</p>
           </section>
 
-          <SubtaskSection controller={controller} task={current} pending={pending} archived={archived} />
+          <SubtaskSection controller={controller} task={current} pending={pending} archived={archived} snapshot={snapshot} />
 
           {current.tags !== undefined && current.tags.length > 0 && (
             <section className={css.detailSection} data-dsh-part="tags">
@@ -484,7 +528,7 @@ export function TaskDetail({ controller, task }: { controller: BoardController;
               <h4>{t('detail.handover')}</h4>
               <p className={css.detailText}>
                 {t('new.workspace')}: {current.handover.workspaceId ?? t('exec.workspace.recent')}
-                {' · '}{t('new.mode')}: {current.handover.mode ?? t('exec.mode.default')}
+                {' · '}{t('new.agentPreset')}: {current.handover.mode ?? t('exec.mode.inherit')}
                 {' · '}{t('new.permission')}: {current.handover.permission === undefined ? t('exec.permission.default') : t(`exec.permission.${current.handover.permission}` as TaskBoardKey)}
               </p>
               <p className={css.detailText}><strong>{t('detail.handover.references')}</strong></p>
@@ -518,7 +562,13 @@ export function TaskDetail({ controller, task }: { controller: BoardController;
 
           {!archived && (
             <>
-              <ExecutionSettingsSection controller={controller} task={current} pending={pending} />
+              <ExecutionSettingsSection
+                controller={controller}
+                task={current}
+                pending={pending}
+                executionOptions={snapshot.executionOptions}
+                teamRunAvailable={snapshot.host?.teamRunAvailable === true}
+              />
               <ScheduleSection controller={controller} task={current} pending={pending} />
             </>
           )}

package/src/client/board/TaskForm.tsx

@@ -4,7 +4,7 @@
  * NewTaskModal and the EditTaskModal. State stays in the owning modal; these
  * are controlled components.
  */
-import type { ReactNode } from 'react'
+import { useState, type ReactNode } from 'react'
 import { TAG_NAME_MAX_LENGTH, TAG_PROMPT_MAX_LENGTH, TASK_TAG_LIMIT, normalizeTags, type TaskTag } from '../../core/tasks.ts'
 import { t } from '../locales.ts'
 import css from '../board.module.css'
@@ -45,7 +45,7 @@ export function ModalShell({
       >
         <h2 className={css.modalTitle}>{title}</h2>
 
-        {children}
+        <div className={css.modalBody}>{children}</div>
 
         {error !== undefined && <p className={css.formError}>{error}</p>}
 
@@ -72,6 +72,51 @@ export function ModalShell({
   )
 }
 
+/**
+ * One collapsible region of a task form (create/edit dialog UX): the form
+ * groups its configuration into a few regions instead of stacking every field
+ * in one long column, so a normal-sized dialog needs no scrollbar. A collapsed
+ * region keeps a one-line summary of the values it holds, so nothing is hidden
+ * without a trace; a region holding a blocking error is forced open by its
+ * owner (forceOpen) rather than reporting the error out of sight.
+ */
+export function CollapsibleSection({
+  title,
+  summary,
+  defaultOpen = false,
+  forceOpen = false,
+  children,
+}: {
+  title: string
+  /** One-line value preview rendered only while the region is collapsed. */
+  summary?: string | undefined
+  /** Whether the region starts expanded (the owner's default layout). */
+  defaultOpen?: boolean
+  /** Open regardless of the stored state: an error inside must stay visible. */
+  forceOpen?: boolean
+  children: ReactNode
+}) {
+  const [open, setOpen] = useState(defaultOpen)
+  const expanded = forceOpen || open
+  return (
+    <section className={css.formSection} data-dsh-part="form-section" data-open={expanded ? 'true' : undefined}>
+      <button
+        type="button"
+        className={css.formSectionHeader}
+        aria-expanded={expanded}
+        onClick={() => { setOpen(value => !value) }}
+      >
+        <span className={css.formSectionChevron} aria-hidden="true" />
+        <span className={css.formSectionTitle}>{title}</span>
+        {!expanded && summary !== undefined && summary !== '' && (
+          <span className={css.formSectionSummary}>{summary}</span>
+        )}
+      </button>
+      {expanded && <div className={css.formSectionBody}>{children}</div>}
+    </section>
+  )
+}
+
 /** Title + description + prompt fields shared by the new and edit task forms. */
 export function TaskContentFields({
   title,
@@ -106,7 +151,7 @@ export function TaskContentFields({
         <span className={css.fieldLabel}>{t('new.description')}</span>
         <textarea
           className={css.input}
-          rows={3}
+          rows={2}
           value={description}
           placeholder={t('new.descriptionPlaceholder')}
           onChange={event => onDescriptionChange(event.target.value)}

package/src/client/board/preset-label.ts

@@ -0,0 +1,44 @@
+/**
+ * Display-only labels for the agent-preset roster, shared by the task form and
+ * the detail view.
+ *
+ * The deployment's four built-in presets (the `standard` / `ptc` / `minimal` /
+ * `cordis` rows the shipped web-app bundle declares) carry no display name in
+ * the registry roster, so a picker would list bare ids beside the user presets.
+ * The map below only supplies names for those four; any other id — a renamed
+ * built-in, a community preset, a user preset — falls back to the roster name
+ * and then to the id, so this table can never hide or mislabel a preset.
+ */
+import type { ExecutionPresetOption } from '../../core/controller.ts'
+import { t, type TaskBoardKey } from '../locales.ts'
+
+/** Built-in preset id -> display-name key (display sugar only). */
+const BUILTIN_PRESET_LABELS: Record<string, TaskBoardKey> = {
+  standard: 'preset.builtin.standard',
+  ptc: 'preset.builtin.ptc',
+  minimal: 'preset.builtin.minimal',
+  cordis: 'preset.builtin.cordis',
+}
+
+/** Whether one roster row is a shipped built-in preset. */
+export function isBuiltinPreset(id: string): boolean {
+  return BUILTIN_PRESET_LABELS[id] !== undefined
+}
+
+/** Display label of one preset row: built-in label, roster name, or raw id. */
+export function presetLabel(preset: Pick<ExecutionPresetOption, 'id' | 'name'>): string {
+  const builtin = BUILTIN_PRESET_LABELS[preset.id]
+  if (builtin !== undefined && (preset.name ?? '').trim() === '') return t(builtin)
+  return preset.name ?? preset.id
+}
+
+/**
+ * Label of the empty ("inherit") choice: names the preset a run actually lands
+ * on when the card pins nothing, which is the deployment default the roster
+ * marks with `isDefault`.
+ */
+export function inheritPresetLabel(presets: readonly ExecutionPresetOption[]): string {
+  const fallback = presets.find(preset => preset.isDefault)
+  if (fallback === undefined) return t('exec.mode.inherit')
+  return t('exec.mode.inheritWith', { preset: presetLabel(fallback) })
+}

package/src/client/board.module.css

@@ -415,10 +415,10 @@
 .modal {
   display: flex;
   flex-direction: column;
-  gap: 12px;
+  gap: 10px;
   width: min(520px, calc(100vw - 48px));
   max-height: calc(100vh - 96px);
-  overflow-y: auto;
+  overflow: hidden;
   padding: 18px;
   background: var(--dsw-alias-bg-base);
   border: 1px solid var(--dsw-alias-border-l2);
@@ -449,6 +449,95 @@
   margin-top: 4px;
 }
 
+/* --- form sections (create/edit dialog) --------------------------------------
+ * The task form groups its configuration into collapsible regions so the
+ * dialog fits without a scrollbar: only the content region starts open, and
+ * every collapsed header carries a one-line summary of what it holds. The
+ * body keeps an overflow fallback for tiny viewports. The chevron is drawn
+ * with borders (no glyph), so no font or emoji can change it.
+ * ----------------------------------------------------------------------------- */
+
+.modalBody {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* Every direct child keeps its natural height: a column flex item shrinks by
+   default, and a shrunk region would clip its own fields behind its
+   `overflow: hidden` instead of letting the body scroll. */
+.modalBody > * {
+  flex: none;
+}
+
+.formSection {
+  display: flex;
+  flex-direction: column;
+  border: 1px solid var(--dsw-alias-separator-primary);
+  border-radius: 10px;
+  overflow: hidden;
+}
+
+.formSectionHeader {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  padding: 7px 10px;
+  font-family: inherit;
+  font-size: 12.5px;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  text-align: left;
+  background: transparent;
+  border: 0;
+  cursor: pointer;
+}
+
+.formSectionHeader:hover {
+  background: var(--dsw-alias-bg-mask-1);
+}
+
+.formSectionChevron {
+  flex: none;
+  width: 0;
+  height: 0;
+  margin-left: 1px;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-left: 5px solid var(--dsw-alias-label-tertiary);
+  transition: transform 120ms ease;
+}
+
+.formSection[data-open='true'] .formSectionChevron {
+  transform: rotate(90deg);
+}
+
+.formSectionTitle {
+  flex: none;
+}
+
+.formSectionSummary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  font-weight: 400;
+  color: var(--dsw-alias-label-tertiary);
+  text-align: right;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.formSectionBody {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 8px 10px 10px;
+  border-top: 1px solid var(--dsw-alias-separator-primary);
+}
+
 .field {
   display: flex;
   flex-direction: column;
@@ -635,6 +724,21 @@
   outline: none;
 }
 
+/* Zone row: the label and the picker share the cron row's geometry so the two
+   controls read as one editor. */
+.scheduleZone {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 12.5px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.scheduleZone select {
+  flex: 1;
+  min-width: 0;
+}
+
 .scheduleMeta {
   margin: 0;
   font-size: 12px;
@@ -942,7 +1046,8 @@
 .input:focus-visible,
 .select:focus-visible,
 .schedulePreset:focus-visible,
-.scheduleToggle input:focus-visible {
+.scheduleToggle input:focus-visible,
+.formSectionHeader:focus-visible {
   outline: 2px solid var(--dsw-alias-state-business-primary);
   outline-offset: 2px;
 }
@@ -957,7 +1062,9 @@
 .input,
 .select,
 .schedulePreset,
-.scheduleToggle input {
+.scheduleToggle input,
+.formSectionHeader,
+.formSectionChevron {
   transition: background-color 120ms ease, color 120ms ease, border-color 120ms ease, outline-color 120ms ease, box-shadow 120ms ease, transform 120ms ease;
 }
 
@@ -1017,7 +1124,9 @@
   .input,
   .select,
   .schedulePreset,
-  .scheduleToggle input {
+  .scheduleToggle input,
+  .formSectionHeader,
+  .formSectionChevron {
     transition: none;
   }
 

package/src/client/host-api.ts

@@ -1,3 +1,5 @@
+import { degradedRowOf, ledgerOwnerPid } from '../core/degraded-reason.ts'
+import { TASK_BOARD_PACKAGE } from '../core/package-name.ts'
 import type { TaskRecord } from '../core/tasks.ts'
 import { t } from './locales.ts'
 import {
@@ -37,7 +39,20 @@ const TASK_PARSE_TIMEOUT_SECONDS = 45
  * "Unexpected token 'o', \"not found\" is not valid JSON" is what a missing
  * Host half looks like today.
  */
-export type HostApiFailure = 'not-mounted' | 'unauthorized' | 'locked' | 'rejected' | 'timeout' | 'unreachable' | 'unexpected'
+export type HostApiFailure =
+  /** The board's own routes are not registered and nothing explains why. */
+  | 'not-mounted'
+  /** Another live DSH process owns the ledger, so this instance registered no board routes (#1730). */
+  | 'ledger-locked'
+  /** This row degraded during start for some other reason the family health route reports (#1730). */
+  | 'degraded'
+  | 'unauthorized'
+  | 'forbidden'
+  | 'locked'
+  | 'rejected'
+  | 'timeout'
+  | 'unreachable'
+  | 'unexpected'
 
 /** Transport failure carrying a stable class next to its user-facing message. */
 export class HostApiError extends Error {
@@ -47,6 +62,86 @@ export class HostApiError extends Error {
   }
 }
 
+/**
+ * Same-origin family health route served by the dsh-web-all shell: the
+ * degraded ledger, in which a family row that failed during apply appears WITH
+ * its reason. DOCUMENT-RELATIVE for the same reason as the board's own routes
+ * (issue #1707). A 404 here means the family shell is absent or older than the
+ * route, which is not itself a failure of the board.
+ */
+const FAMILY_DEGRADED_ROUTE = 'api/dsh-web-all/degraded'
+
+/** Health-route ceiling: an unresponsive family shell must not hold the board's first paint. */
+const DEGRADED_LOOKUP_TIMEOUT_MS = 2_000
+
+/**
+ * The failure text for a row this browser knows failed during start.
+ *
+ * A ledger lock is the one class with an owner the user can act on, so its
+ * reason is unpacked into the pid plus what to do about it; every other
+ * degraded row is reported with the shell's own reason verbatim. The raw
+ * reason rides along either way, because it is the only text that names the
+ * lock file or the recovery step when the pid is not the whole story.
+ * @param reason - the shell's one-line failure reason (never empty).
+ */
+function degradedFailureMessage(reason: string): { failure: 'ledger-locked' | 'degraded'; message: string } {
+  const pid = ledgerOwnerPid(reason)
+  if (pid === undefined) return { failure: 'degraded', message: t('board.hostError.degraded', { detail: reason }) }
+  return { failure: 'ledger-locked', message: t('board.hostError.ledgerLocked', { pid: String(pid), detail: reason }) }
+}
+
+/**
+ * The degraded record the family shell holds for THIS board, or undefined when
+ * the row is healthy, the shell is absent, or the answer is unusable. The
+ * lookup is best-effort by contract: any uncertainty keeps the caller's own
+ * failure text instead of replacing it with a weaker one.
+ * @param fetchImpl - fetch implementation (injected for tests).
+ * @returns the ledger's reason for this row, or undefined when it names none.
+ */
+async function fetchDegradedReason(fetchImpl: typeof fetch): Promise<string | undefined> {
+  const controller = new AbortController()
+  const timer = globalThis.setTimeout(() => { controller.abort() }, DEGRADED_LOOKUP_TIMEOUT_MS)
+  try {
+    const response = await fetchImpl(FAMILY_DEGRADED_ROUTE, { signal: controller.signal, headers: { accept: 'application/json' }, cache: 'no-store' })
+    if (!response.ok) return undefined
+    return degradedRowOf(await response.json(), TASK_BOARD_PACKAGE)?.reason
+  } catch {
+    return undefined
+  } finally {
+    globalThis.clearTimeout(timer)
+  }
+}
+
+/**
+ * Name the real reason this board's routes are missing (issue #1730).
+ *
+ * The core webserver answers an unmounted route with a bare 404, which cannot
+ * distinguish "this deployment never loaded the plugin" from "this row
+ * degraded during start" — a second DSH process holding `ledger-v2.lock` is
+ * the case that matters, because the panel's advice ("restart the service")
+ * is then false: the lock belongs to the other process, and restarting cannot
+ * win it. The family health route knows the difference, so the 404 is
+ * disambiguated there before anything is shown.
+ * @param fallback - copy for the plain "routes are not there" failure, which
+ *   is route-specific (the board's state route and the AI-parse route phrase
+ *   their own absence); it is also what is shown when the ledger names nothing.
+ * @param fetchImpl - fetch implementation (injected for tests).
+ * @returns the HostApiError to throw for a missing board route.
+ */
+export async function missingRouteFailure(
+  fallback: string = t('board.hostError.notMounted'),
+  fetchImpl: typeof fetch = fetch,
+): Promise<HostApiError> {
+  const absent = (): HostApiError => new HostApiError('not-mounted', fallback, 404)
+  const reason = await fetchDegradedReason(fetchImpl)
+  // A shell that predates the reason field (or recorded none) tells us the row
+  // is degraded but not why; the route's own wording is more honest than an
+  // empty "because".
+  if (reason === undefined || reason === '') return absent()
+  const described = degradedFailureMessage(reason)
+  return new HostApiError(described.failure, described.message, 404)
+}
+
 function uuid(): string {
   return globalThis.crypto?.randomUUID?.() ?? `browser-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`
 }
@@ -79,14 +174,18 @@ async function readJson<T>(response: Response): Promise<T> {
     // The Host answered with a reason of its own. A ledger lock is the one
     // class worth naming in the panel's words; the authentication fence and
     // every other action rejection are reported as they arrive.
-    if (hostError === 'forbidden') throw new HostApiError('unauthorized', t('board.hostError.unauthorized'), response.status)
+    if (hostError === 'forbidden') throw new HostApiError('forbidden', t('board.hostError.forbidden'), response.status)
     if (response.status === 503 || /lock/i.test(hostError)) {
       throw new HostApiError('locked', t('board.hostError.locked', { detail: hostError }), response.status)
     }
     throw new HostApiError('rejected', hostError, response.status)
   }
-  if (response.status === 404) throw new HostApiError('not-mounted', t('board.hostError.notMounted'), 404)
-  if (response.status === 401 || response.status === 403) throw new HostApiError('unauthorized', t('board.hostError.unauthorized'), response.status)
+  // A bare 404 is the ONLY signal that this board's routes are absent; the
+  // family health route is what turns it into the real reason when this row
+  // degraded during start (issue #1730).
+  if (response.status === 404) throw await missingRouteFailure()
+  if (response.status === 403) throw new HostApiError('forbidden', t('board.hostError.forbidden'), 403)
+  if (response.status === 401) throw new HostApiError('unauthorized', t('board.hostError.unauthorized'), 401)
   throw new HostApiError('unexpected', t('board.hostError.unexpected', { status: String(response.status) }), response.status)
 }
 
@@ -193,8 +292,12 @@ export class HttpTaskBoardHostTransport implements TaskBoardHostTransport {
       if (record !== undefined && isTaskParseDraft(record.draft)) return record.draft
       throw new HostApiError('unexpected', t('new.aiParseFailed', { error: t('board.hostError.unexpected', { status: String(response.status) }) }), response.status)
     }
-    if (response.status === 404) throw new HostApiError('not-mounted', t('new.aiParseUnavailable'), 404)
-    if (response.status === 401 || response.status === 403) throw new HostApiError('unauthorized', t('board.hostError.unauthorized'), response.status)
+    // The parse route lives beside the board's own routes, so a 404 means the
+    // same thing here: absent routes, with the same health-ledger detail and
+    // this route's own wording as the fallback.
+    if (response.status === 404) throw await missingRouteFailure(t('new.aiParseUnavailable'))
+    if (response.status === 403) throw new HostApiError('forbidden', t('board.hostError.forbidden'), 403)
+    if (response.status === 401) throw new HostApiError('unauthorized', t('board.hostError.unauthorized'), 401)
     const code = typeof record?.code === 'string' ? record.code : undefined
     if (code === 'no-model') throw new HostApiError('rejected', t('new.aiParseNoModel'), response.status)
     if (code === 'timeout') throw new HostApiError('timeout', t('new.aiParseTimeout', { seconds: String(TASK_PARSE_TIMEOUT_SECONDS) }), response.status)