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

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/seats.tsx

@@ -0,0 +1,58 @@
+/**
+ * The board's child seats, threaded from the slot registration that declares
+ * them down to the components that consume them.
+ *
+ * The framework hands the declaring component a `renderSlot` binding; the board
+ * wraps that binding in a React context so a provider's contribution can render
+ * deep inside TaskDetail, the card, or the settings card without those
+ * components knowing which providers exist.
+ *
+ * @module dsh-task-board/client/seats
+ */
+import { createContext, useContext } from 'react'
+import type { ReactNode } from 'react'
+import {
+  TASK_BOARD_CARD_DECORATION,
+  TASK_BOARD_DETAIL_SECTION,
+  TASK_BOARD_SETTINGS_SECTION,
+  type TaskBoardCardDecorationProps,
+  type TaskBoardDetailSectionProps,
+  type TaskBoardSettingsSectionProps,
+} from '../core/extension.ts'
+
+/** The three provider seats, adapted to plain render functions. */
+export interface TaskBoardSeats {
+  detailSection: (props: TaskBoardDetailSectionProps) => ReactNode
+  settingsSection: (props: TaskBoardSettingsSectionProps) => ReactNode
+  cardDecoration: (props: TaskBoardCardDecorationProps) => ReactNode
+}
+
+/** Nothing registered: every seat renders empty. */
+export const EMPTY_TASK_BOARD_SEATS: TaskBoardSeats = {
+  detailSection: () => null,
+  settingsSection: () => null,
+  cardDecoration: () => null,
+}
+
+/** The framework `renderSlot` binding shape (key + owner props share). */
+export type SlotRenderBinding = (key: string, owner: Record<string, unknown>) => ReactNode
+
+/** Adapt one framework renderSlot binding to the board's seat interface. */
+export function seatsFromRenderSlot(renderSlot: SlotRenderBinding | undefined): TaskBoardSeats {
+  if (renderSlot === undefined) return EMPTY_TASK_BOARD_SEATS
+  return {
+    detailSection: props => renderSlot(TASK_BOARD_DETAIL_SECTION, props as unknown as Record<string, unknown>),
+    settingsSection: props => renderSlot(TASK_BOARD_SETTINGS_SECTION, props as unknown as Record<string, unknown>),
+    cardDecoration: props => renderSlot(TASK_BOARD_CARD_DECORATION, props as unknown as Record<string, unknown>),
+  }
+}
+
+const TaskBoardSeatsContext = createContext<TaskBoardSeats>(EMPTY_TASK_BOARD_SEATS)
+
+/** Provider the board's registered components wrap their subtree in. */
+export const TaskBoardSeatsProvider = TaskBoardSeatsContext.Provider
+
+/** Read the current seat set (empty when no board registration is above). */
+export function useTaskBoardSeats(): TaskBoardSeats {
+  return useContext(TaskBoardSeatsContext)
+}

package/src/client/service.ts

@@ -0,0 +1,94 @@
+/**
+ * The board's browser-half extension service (`taskBoard`).
+ *
+ * It gives a provider's browser half the client capability face from the
+ * contract: dispatch over the board's same-origin action channel, card
+ * visibility predicates, and a subscription to the board mirror. The board
+ * controller is attached and detached as the master switch mounts and unmounts
+ * the UI, so the service can be provided before any controller exists.
+ *
+ * @module dsh-task-board/client/service
+ */
+import type { BoardController } from '../core/controller.ts'
+import type {
+  TaskBoardClientFace,
+  TaskBoardClientMirror,
+  TaskBoardExtensionActionRequest,
+  TaskBoardVisibilityPredicate,
+} from '../core/extension.ts'
+import type { TaskRecord } from '../core/tasks.ts'
+
+export class TaskBoardClientService implements TaskBoardClientFace {
+  private controller: BoardController | undefined
+  private enabled = false
+  private unsubscribeController: (() => void) | undefined
+  /** Predicates registered before the controller exists, replayed on attach. */
+  private readonly pendingVisibility: TaskBoardVisibilityPredicate[] = []
+  private readonly listeners = new Set<(mirror: TaskBoardClientMirror) => void>()
+
+  /** Bind the live board controller (called when the UI mounts). */
+  attach(controller: BoardController): void {
+    if (this.controller === controller) return
+    this.detach()
+    this.controller = controller
+    this.unsubscribeController = controller.subscribe(() => { this.notify() })
+    for (const predicate of this.pendingVisibility.splice(0)) controller.registerVisibility(predicate)
+    this.notify()
+  }
+
+  /** Release the current controller (called when the UI unmounts). */
+  detach(): void {
+    if (this.controller === undefined) return
+    this.unsubscribeController?.()
+    this.unsubscribeController = undefined
+    this.controller = undefined
+    this.notify()
+  }
+
+  /** Apply the board's master switch. */
+  setEnabled(enabled: boolean): void {
+    if (this.enabled === enabled) return
+    this.enabled = enabled
+    this.notify()
+  }
+
+  dispatch(request: TaskBoardExtensionActionRequest): Promise<boolean> {
+    if (this.controller === undefined) return Promise.resolve(false)
+    return this.controller.dispatchExtension(request)
+  }
+
+  registerVisibility(predicate: TaskBoardVisibilityPredicate): () => void {
+    if (this.controller !== undefined) return this.controller.registerVisibility(predicate)
+    this.pendingVisibility.push(predicate)
+    return () => {
+      const index = this.pendingVisibility.indexOf(predicate)
+      if (index !== -1) this.pendingVisibility.splice(index, 1)
+    }
+  }
+
+  subscribe(callback: (mirror: TaskBoardClientMirror) => void): () => void {
+    this.listeners.add(callback)
+    return () => { this.listeners.delete(callback) }
+  }
+
+  snapshot(): TaskBoardClientMirror {
+    const state = this.controller?.getSnapshot()
+    return {
+      enabled: this.enabled,
+      tasks: (state?.tasks ?? []) as readonly TaskRecord[],
+      extensions: state?.extensions ?? {},
+    }
+  }
+
+  private notify(): void {
+    const mirror = this.snapshot()
+    for (const listener of [...this.listeners]) {
+      try {
+        listener(mirror)
+      } catch (error) {
+        // A provider's mirror callback must never break the board.
+        console.error('[dsh-task-board] extension mirror callback failed', error)
+      }
+    }
+  }
+}

package/src/client/settings-card.module.css

@@ -36,8 +36,8 @@
   border: 0;
   border-radius: 12px;
   align-items: center;
-  gap: 12px;
-  padding: 14px 16px;
+  gap: 13px;
+  padding: 16px;
   display: flex;
 }
 
@@ -51,8 +51,8 @@
   box-sizing: border-box;
   border-radius: 12px;
   align-items: center;
-  gap: 12px;
-  padding: 14px 16px;
+  gap: 13px;
+  padding: 16px;
   display: flex;
 }
 
@@ -64,6 +64,25 @@
   display: flex;
 }
 
+/* Optional leading plugin mark: a quiet tile that takes the ink color on
+   hover and while the card is open, so the whole row reads as one control. */
+.mark {
+  flex: none;
+  display: grid;
+  place-items: center;
+  width: 34px;
+  height: 34px;
+  border-radius: 10px;
+  background: var(--dsw-alias-bg-module-platform);
+  color: var(--dsw-alias-label-secondary);
+  transition: color 0.16s;
+}
+
+.header:hover .mark,
+.cardOpen .mark {
+  color: var(--dsw-alias-label-primary);
+}
+
 .name {
   color: var(--dsw-alias-label-primary);
   font-size: 15px;
@@ -95,7 +114,13 @@
 .chevron {
   color: var(--dsw-alias-label-tertiary);
   flex: none;
-  transition: transform 0.16s;
+  width: 16px;
+  height: 16px;
+  transition: transform 0.16s, color 0.16s;
+}
+
+.header:hover .chevron {
+  color: var(--dsw-alias-label-secondary);
 }
 
 .chevronOpen {
@@ -406,6 +431,7 @@
 @media (prefers-reduced-motion: reduce) {
   .card,
   .header,
+  .mark,
   .chevron,
   .chevronOpen,
   .discard,

package/src/client/settings-form.ts

@@ -215,6 +215,8 @@ export class CardForm<T> {
   private readonly disposeForm: () => void
   private disposed = false
   private saving = false
+  /** A save asked for while one was in flight; it runs once the first settles (#1754). */
+  private saveQueued = false
   private failed = false
   private failedReason: string | undefined
 
@@ -283,7 +285,7 @@ export class CardForm<T> {
       resetField: (field) => {
         this.stage(field, { text: this.specOf(field).format(this.baseValue(field)), clear: true })
       },
-      save: () => { void this.save() },
+      save: () => { void this.requestSave() },
       discard: () => {
         if (this.staged.size === 0 && !this.failed) return
         this.staged.clear()
@@ -310,6 +312,30 @@ export class CardForm<T> {
    * the user can correct them instead of retyping.
    * @returns settlement after the mutation and the read-back.
    */
+  /**
+   * Run one save, and re-run it once if another was asked for while this one
+   * was still in flight.
+   *
+   * A save is a Host round trip that also drives the profile reconcile, and
+   * the Host runs that write inside one exclusive transaction. Answering a
+   * press that arrives mid-flight by returning immediately dropped the edit
+   * with no explanation, which is the "the save button stops working after a
+   * few rounds" report (#1754). Serializing instead means a save pressed while
+   * another is still settling runs against the settled state - which is what
+   * the operator meant by pressing it again.
+   * @returns settlement after the mutation and the read-back.
+   */
+  async requestSave(): Promise<void> {
+    if (this.saving) {
+      this.saveQueued = true
+      return
+    }
+    await this.save()
+    if (!this.saveQueued) return
+    this.saveQueued = false
+    await this.requestSave()
+  }
+
   async save(): Promise<void> {
     const plan = this.plan()
     const valid = plan.filter((item): item is PlannedWrite & { judge: () => boolean } => item.judge !== undefined)

package/src/core/controller.ts

@@ -12,12 +12,14 @@
  * owns only the orchestration seam (state, persistence, notify, navigation).
  */
 import type { TaskStore } from './store.ts'
-import { withStatus, type NewTaskInput, type TaskRecord, type TaskStatus } from './tasks.ts'
+import { hasOpenExecution, withStatus, type NewTaskInput, type TaskRecord, type TaskStatus } from './tasks.ts'
 import { applyArchiveTask, applyRestoreTask } from './use-cases/task-archive.ts'
 import { applyCreateTask } from './use-cases/task-create.ts'
 import { applyDeleteTask } from './use-cases/task-delete.ts'
 import { applyScheduleNextRun as applyScheduleRollForward, applySetSchedule } from './use-cases/task-schedule.ts'
+import { resolveHostTimeZone } from './schedule.ts'
 import { applySetParent } from './use-cases/task-parent.ts'
+import { applyDeleteTag, applyRenameTag } from './use-cases/task-tag.ts'
 import { applyUpdateTask, type TaskUpdatePatch } from './use-cases/task-update.ts'
 import { DEFAULT_SUBTASK_DEPTH } from './subtask.ts'
 import type {
@@ -27,6 +29,10 @@ import type {
   TaskBoardParseRequest,
   TaskBoardSnapshot,
 } from '../protocol.ts'
+import type {
+  TaskBoardExtensionActionRequest,
+  TaskBoardVisibilityPredicate,
+} from './extension.ts'
 
 export interface TaskBoardTransport {
   bootstrap(legacy: readonly TaskRecord[]): Promise<TaskBoardSnapshot>
@@ -135,7 +141,7 @@ export interface ExecutionOptionsSnapshot {
  * (revision/scheduler/power); a full snapshot also carries the deployment
  * constants the UI reads (session default permission, subtask depth).
  */
-export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable'>
+export type HostMirror = Pick<TaskBoardSnapshot, 'revision' | 'scheduler' | 'power' | 'sessionDefaultPermission' | 'maxSubtaskDepth' | 'teamRunAvailable' | 'extensions'>
 
 /** Immutable controller snapshot for UI subscriptions. */
 export interface ControllerSnapshot {
@@ -153,6 +159,15 @@ export interface ControllerSnapshot {
   canParseTask?: boolean
   transportError?: string
   host?: HostMirror
+  /**
+   * Provider card-visibility predicates, in registration order. A task shows
+   * only while every predicate accepts it; providers hide their own off-board
+   * cards here instead of the board hard-coding a provider rule. Optional so a
+   * hand-built snapshot (tests, a shell-less composition) defaults to visible.
+   */
+  visibility?: readonly TaskBoardVisibilityPredicate[]
+  /** Read-only summaries published by running extensions, keyed by extension id. */
+  extensions?: Readonly<Record<string, unknown>>
 }
 
 /** The selected task (resolved from the ledger), or undefined. */
@@ -200,6 +215,8 @@ export class BoardController {
   private readonly taskQueues = new Map<string, Promise<void>>()
   private transportError: string | undefined
   private hostState: HostMirror | undefined
+  /** Provider visibility predicates (immutable array; replaced on change). */
+  private visibility: readonly TaskBoardVisibilityPredicate[] = []
   private remoteSubscribed = false
   private remoteInitialization: Promise<boolean> | undefined
 
@@ -250,9 +267,42 @@ export class BoardController {
       ...(typeof this.deps.transport?.parseDraft === 'function' ? { canParseTask: true } : {}),
       ...(this.transportError === undefined ? {} : { transportError: this.transportError }),
       ...(this.hostState === undefined ? {} : { host: this.hostState }),
+      visibility: this.visibility,
+      ...(this.hostState?.extensions === undefined ? {} : { extensions: this.hostState.extensions }),
+    }
+  }
+
+  /**
+   * Register one card-visibility predicate. The returned disposer removes it;
+   * both changes notify subscribers so the board re-renders.
+   */
+  registerVisibility(predicate: TaskBoardVisibilityPredicate): () => void {
+    this.visibility = [...this.visibility, predicate]
+    this.notify()
+    return () => {
+      const next = this.visibility.filter(candidate => candidate !== predicate)
+      if (next.length === this.visibility.length) return
+      this.visibility = next
+      this.notify()
     }
   }
 
+  /**
+   * Deliver one provider action through the board's same-origin channel. A
+   * board without a Host transport (the legacy in-memory path) refuses it.
+   */
+  async dispatchExtension(request: TaskBoardExtensionActionRequest): Promise<boolean> {
+    if (this.deps.transport === undefined) return false
+    const action: TaskBoardAction = {
+      kind: 'extension-action',
+      extensionId: request.extensionId,
+      action: request.action,
+      ...(request.taskId === undefined ? {} : { taskId: request.taskId }),
+      ...(request.payload === undefined ? {} : { payload: request.payload }),
+    }
+    return await this.commitRemote(action, request.taskId)
+  }
+
   subscribe(fn: () => void): () => void {
     this.listeners.add(fn)
     return () => { this.listeners.delete(fn) }
@@ -506,6 +556,44 @@ export class BoardController {
     return true
   }
 
+  /**
+   * Rename one label across the whole ledger; a name already in use merges the
+   * two labels. Host-backed: the ledger owns the transition and confirms it, so
+   * the board's label row reflects whether the Host accepted the edit.
+   * @returns true when the edit was accepted by the authority.
+   */
+  async renameTag(from: string, to: string): Promise<boolean> {
+    if (this.deps.transport !== undefined) {
+      return await this.commitRemote({ kind: 'rename-tag', from, to })
+    }
+    const result = applyRenameTag(this.tasks, from, to, this.now())
+    if (result.error !== undefined) return false
+    if (result.changed) {
+      this.tasks = [...result.tasks]
+      this.persistAndNotify()
+    }
+    return true
+  }
+
+  /**
+   * Remove one label from every task that carries it, board and archive alike —
+   * the board's label row is drawn from the whole ledger, so a label left on an
+   * archived card would come straight back.
+   * @returns true when the edit was accepted by the authority.
+   */
+  async deleteTag(name: string): Promise<boolean> {
+    if (this.deps.transport !== undefined) {
+      return await this.commitRemote({ kind: 'delete-tag', name })
+    }
+    const result = applyDeleteTag(this.tasks, name, this.now())
+    if (result.error !== undefined) return false
+    if (result.changed) {
+      this.tasks = [...result.tasks]
+      this.persistAndNotify()
+    }
+    return true
+  }
+
   // --- scheduling ---------------------------------------------------------------
 
   /**
@@ -517,8 +605,12 @@ export class BoardController {
    * @param patch - fields to change (absent fields keep their current value).
    * @returns true when applied, false when rejected (invalid cron / unknown task).
    */
-  setSchedule(id: string, patch: { enabled?: boolean; cron?: string }): boolean {
-    const { tasks, applied } = applySetSchedule(this.tasks, id, patch, this.now())
+  setSchedule(id: string, patch: { enabled?: boolean; cron?: string; timeZone?: string | null }): boolean {
+    // The Host zone is the fallback a rule with no stored zone follows: the
+    // mirrored snapshot carries it, and a controller without a Host mirror
+    // (pure client tests) falls back to the process zone.
+    const hostTimeZone = this.hostState?.scheduler.timeZone ?? resolveHostTimeZone()
+    const { tasks, applied } = applySetSchedule(this.tasks, id, patch, this.now(), hostTimeZone)
     if (!applied) return false
     if (this.deps.transport !== undefined) {
       void this.commitRemote({ kind: 'set-schedule', taskId: id, patch }, id)
@@ -567,7 +659,9 @@ export class BoardController {
    */
   async runTask(id: string): Promise<boolean> {
     const task = this.tasks.find(candidate => candidate.id === id)
-    if (task === undefined || task.archivedAt !== undefined || task.status === 'running') return false
+    // Only an open execution blocks a second launch; the 'running' column is a
+    // board statement and a card parked there by hand still runs on request.
+    if (task === undefined || task.archivedAt !== undefined || hasOpenExecution(task)) return false
     if (this.deps.transport === undefined) return false
     return await this.commitRemote({ kind: 'run', taskId: id }, id, currentOf(this.deps.sessions))
   }
@@ -719,6 +813,7 @@ export class BoardController {
     const sessionDefaultPermission = snapshot.sessionDefaultPermission ?? this.hostState?.sessionDefaultPermission
     const maxSubtaskDepth = snapshot.maxSubtaskDepth ?? this.hostState?.maxSubtaskDepth
     const teamRunAvailable = snapshot.teamRunAvailable ?? this.hostState?.teamRunAvailable
+    const extensions = snapshot.extensions ?? this.hostState?.extensions
     return {
       revision: snapshot.revision,
       scheduler: snapshot.scheduler,
@@ -726,6 +821,7 @@ export class BoardController {
       ...(sessionDefaultPermission === undefined ? {} : { sessionDefaultPermission }),
       ...(maxSubtaskDepth === undefined ? {} : { maxSubtaskDepth }),
       ...(teamRunAvailable === undefined ? {} : { teamRunAvailable }),
+      ...(extensions === undefined ? {} : { extensions }),
     }
   }
 

package/src/core/degraded-reason.ts

@@ -0,0 +1,81 @@
+/**
+ * The family health ledger's degraded-record contract (issues #1528, #1730).
+ *
+ * A family plugin row that fails during apply is recorded by the dsh-web-all
+ * shell as a degraded record; the shell serves the ledger through its
+ * loopback-only `GET /api/dsh-web-all/degraded` route because the failed
+ * plugin could not register any route of its own — the task board whose ledger
+ * lock is held by another DSH process is exactly that case, and without this
+ * the panel could only report "the Host API is not mounted".
+ *
+ * Both halves define this shape: the shell WRITES it (packages/dsh-web-all,
+ * src/degraded.ts — the two packages have no import edge, one is bundled into
+ * the other's profile) and a plugin's browser half PARSES it. The edits move
+ * together.
+ */
+
+/** Where a degraded row failed: module import, plugin shape, or fiber start. */
+export type DegradedStage = 'import' | 'shape' | 'start'
+
+/** One degraded family row as the shell's health route serves it. */
+export interface DegradedRow {
+  /** Real plugin package name from the shell row config. */
+  plugin: string
+  /** Where the failure happened. */
+  stage: DegradedStage
+  /** The shell's one-line reason, for display. */
+  reason: string
+}
+
+/**
+ * The one degraded record naming `plugin`, or undefined when that row is not
+ * degraded (or the payload does not come from the shell's own shape). A
+ * plugin may appear once: the shell keys the ledger by package name and
+ * refreshes the record on every new failure.
+ * @param body - parsed JSON body of the health route.
+ * @param plugin - the real plugin package name to look for.
+ * @returns the degraded row, or undefined when the ledger does not name it.
+ */
+export function degradedRowOf(body: unknown, plugin: string): DegradedRow | undefined {
+  if (typeof body !== 'object' || body === null) return undefined
+  const ledger = (body as { ok?: unknown; degraded?: unknown })
+  if (ledger.ok !== true || !Array.isArray(ledger.degraded)) return undefined
+  for (const entry of ledger.degraded) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const record = entry as { plugin?: unknown; stage?: unknown; reason?: unknown }
+    if (record.plugin !== plugin) continue
+    const stage = record.stage === 'import' || record.stage === 'shape' || record.stage === 'start' ? record.stage : undefined
+    if (stage === undefined) continue
+    return { plugin, stage, reason: typeof record.reason === 'string' ? record.reason : '' }
+  }
+  return undefined
+}
+
+/** The ledger owner pid a task-board lock reason names, when it names one. */
+const OWNED_BY_PROCESS_RE = /already owned by process\s+(\d+)/
+
+/**
+ * The marker the ledger appends when it could NOT confirm the recorded PID
+ * belongs to the lock's real owner: the PID was reused by an unrelated process
+ * after a crash, and the reason then carries the manual-removal step instead.
+ * That reason must be rendered verbatim — telling the user to close "the other
+ * DSH instance" would send them after a process that never touched the board.
+ */
+const UNCONFIRMED_OWNER_MARKER = 'reused after a crash'
+
+/**
+ * Extract the pid of the LIVE process a ledger-lock failure blames, when the
+ * reason identifies one. The task board's lock refusal is the one degraded
+ * reason that carries an owner the user can act on, so the panel renders the
+ * pid in its own sentence and adds the guidance that actually applies.
+ * @param reason - the shell's one-line failure reason.
+ * @returns the confirmed owner pid, or undefined when the reason names none or
+ *   warns that the PID may have been reused (its own text owns the recovery).
+ */
+export function ledgerOwnerPid(reason: string): number | undefined {
+  if (reason.includes(UNCONFIRMED_OWNER_MARKER)) return undefined
+  const match = OWNED_BY_PROCESS_RE.exec(reason)
+  if (match === null) return undefined
+  const pid = Number(match[1])
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined
+}