@linxin666/dsh-client-ui-task-board 0.1.19 → 0.2.0

package/src/host-runner.ts

@@ -0,0 +1,134 @@
+import type { ApiProxy, RpcId } from '@deepseek-ai/dsh-host-apiproxy'
+import type { TaskRecord } from './core/tasks.ts'
+
+function request<T>(payload: T) {
+  return { rpcId: `task-board-${crypto.randomUUID()}` as RpcId, payload }
+}
+
+function failure(error: { code: string; message: string }): Error {
+  return new Error(`${error.code}: ${error.message}`)
+}
+
+export type ExecutionInspection =
+  | { outcome: 'pending' }
+  | { outcome: 'succeeded' }
+  | { outcome: 'failed'; error: string }
+  | { outcome: 'cancelled'; error: string }
+
+/** A post-create launch failure that still identifies the session to the ledger. */
+export class SessionLaunchError extends Error {
+  constructor(readonly sessionId: string, cause: unknown) {
+    super(`execution session ${sessionId} failed during launch: ${cause instanceof Error ? cause.message : String(cause)}`, { cause })
+    this.name = 'SessionLaunchError'
+  }
+}
+
+function isErrorTurnEnd(data: unknown): boolean {
+  if (typeof data !== 'object' || data === null) return false
+  const reason = (data as { reason?: unknown }).reason
+  return typeof reason === 'object' && reason !== null && (reason as { kind?: unknown }).kind === 'error'
+}
+
+export class HostExecutionRunner {
+  constructor(private readonly api: ApiProxy) {}
+
+  async launch(task: TaskRecord): Promise<string> {
+    if (task.workspaceId !== undefined) {
+      const workspaces = await this.api.workspace.list(request({}))
+      if (!workspaces.result.ok) throw failure(workspaces.result.error)
+      if (!workspaces.result.value.items.some(item => item.workspaceId === task.workspaceId)) {
+        throw new Error(`workspace not found: ${task.workspaceId}`)
+      }
+    }
+    if (task.mode !== undefined) {
+      const presets = await this.api.agentPresets.list(request({}))
+      if (!presets.result.ok) throw failure(presets.result.error)
+      const preset = presets.result.value.presets.find(item => item.id === task.mode)
+      if (preset === undefined) throw new Error(`agent preset not found: ${task.mode}`)
+      if (preset.broken !== undefined) throw new Error(`agent preset is unavailable: ${preset.broken}`)
+    }
+    const created = await this.api.sessions.create(request({
+      ...(task.workspaceId === undefined ? {} : { workspaceId: task.workspaceId as never }),
+      ...(task.mode === undefined ? {} : { agentPreset: task.mode }),
+    }))
+    if (!created.result.ok) throw failure(created.result.error)
+    const sessionId = created.result.value.sessionId
+    try {
+      const renamed = await this.api.sessions.rename(request({ sessionId, title: task.title }))
+      if (!renamed.result.ok) throw failure(renamed.result.error)
+      if (task.permission !== undefined) {
+        const command = await this.api.sessions.prompt(request({
+          sessionId,
+          mode: 'queue' as const,
+          content: [{ type: 'text' as const, text: `/permission ${task.permission}` }],
+        }))
+        if (!command.result.ok) throw failure(command.result.error)
+        if (command.result.value.command?.kind !== 'success') throw new Error('permission command was not acknowledged')
+      }
+      const prompt = await this.api.sessions.prompt(request({
+        sessionId,
+        mode: 'queue' as const,
+        content: [{ type: 'text' as const, text: task.prompt !== '' ? task.prompt : task.title }],
+      }))
+      if (!prompt.result.ok) throw failure(prompt.result.error)
+    } catch (error) {
+      throw new SessionLaunchError(sessionId, error)
+    }
+    return sessionId
+  }
+
+  async listRunning(): Promise<{ known: true; count: number } | { known: false }> {
+    try {
+      const response = await this.api.sessions.list(request({}))
+      return response.result.ok
+        ? { known: true, count: response.result.value.items.filter(item => item.running).length }
+        : { known: false }
+    } catch {
+      return { known: false }
+    }
+  }
+
+  async inspect(sessionId: string, startedAt = 0): Promise<ExecutionInspection> {
+    const sessions = await this.api.sessions.list(request({}))
+    if (!sessions.result.ok) return { outcome: 'pending' }
+    const summary = sessions.result.value.items.find(item => item.sessionId === sessionId)
+    if (summary === undefined) return { outcome: 'cancelled', error: 'execution session no longer exists' }
+    if (summary.running) return { outcome: 'pending' }
+    const events: Array<{ event: { type: string; seq?: number; time?: number; data: unknown } }> = []
+    let beforeSeq: number | undefined
+    let reachedExecutionBoundary = false
+    for (let page = 0; page < 100; page += 1) {
+      const history = await this.api.sessions.history(request({
+        sessionId: summary.sessionId,
+        maxMessages: 100,
+        ...(beforeSeq === undefined ? {} : { beforeSeq }),
+      }))
+      if (!history.result.ok) return { outcome: 'pending' }
+      events.push(...history.result.value.events)
+      const oldestTime = history.result.value.events.reduce<number | undefined>((oldest, entry) => {
+        const time = entry.event.time
+        return typeof time !== 'number' ? oldest : oldest === undefined ? time : Math.min(oldest, time)
+      }, undefined)
+      if (!history.result.value.hasMore || (oldestTime !== undefined && oldestTime <= startedAt)) {
+        reachedExecutionBoundary = true
+        break
+      }
+      const oldestSeq = history.result.value.events.reduce<number | undefined>((oldest, entry) => {
+        const seq = entry.event.seq
+        return typeof seq !== 'number' ? oldest : oldest === undefined ? seq : Math.min(oldest, seq)
+      }, undefined)
+      if (oldestSeq === undefined || oldestSeq === beforeSeq) return { outcome: 'pending' }
+      beforeSeq = oldestSeq
+    }
+    if (!reachedExecutionBoundary) return { outcome: 'pending' }
+    const turnEnd = events
+      .filter(entry => entry.event.type === 'turn/end' && (
+        startedAt <= 0 || (typeof entry.event.time === 'number' && entry.event.time >= startedAt)
+      ))
+      .sort((a, b) => (a.event.seq ?? Number.MAX_SAFE_INTEGER) - (b.event.seq ?? Number.MAX_SAFE_INTEGER))[0]
+    if (turnEnd === undefined) return { outcome: 'pending' }
+    return isErrorTurnEnd(turnEnd.event.data)
+      ? { outcome: 'failed', error: 'agent turn ended with an error' }
+      : { outcome: 'succeeded' }
+  }
+}

package/src/host-service.ts

@@ -0,0 +1,209 @@
+import type { ApiProxy } from '@deepseek-ai/dsh-host-apiproxy'
+import { nextRunAtMs } from './core/schedule.ts'
+import type { TaskRecord } from './core/tasks.ts'
+import { HostTaskLedger, type OpenedRun } from './host-ledger.ts'
+import { HostExecutionRunner, SessionLaunchError } from './host-runner.ts'
+import { PowerInhibitor } from './power-inhibitor.ts'
+import type { TaskBoardAction, TaskBoardSnapshot } from './protocol.ts'
+
+const SESSION_POLL_MS = 5_000
+const SCHEDULE_TICK_MS = 30_000
+const RESUME_GAP_MS = SCHEDULE_TICK_MS + 15_000
+
+export class TaskBoardHostService {
+  readonly ledger: HostTaskLedger
+  readonly runner: HostExecutionRunner
+  readonly power: PowerInhibitor
+  private readonly listeners = new Set<() => void>()
+  private timers: Array<ReturnType<typeof setInterval>> = []
+  private lastScheduleTick: number | undefined
+  private disposed = false
+  private pollInFlight = false
+  private tickInFlight = false
+  private active = true
+  private preventIdleSleep = false
+  private readonly now: () => number
+
+  constructor(api: ApiProxy, options: { ledger?: HostTaskLedger; power?: PowerInhibitor; now?: () => number } = {}) {
+    this.ledger = options.ledger ?? new HostTaskLedger()
+    this.runner = new HostExecutionRunner(api)
+    this.power = options.power ?? new PowerInhibitor()
+    this.now = options.now ?? Date.now
+    this.ledger.subscribe(() => {
+      this.syncPowerReasons()
+      this.emit()
+    })
+    this.power.subscribe(() => { this.emit() })
+  }
+
+  start(): void {
+    if (this.disposed || this.timers.length > 0) return
+    this.syncPowerReasons()
+    this.timers.push(setInterval(() => { this.schedulePoll() }, SESSION_POLL_MS))
+    this.timers.push(setInterval(() => { this.scheduleTick(false) }, SCHEDULE_TICK_MS))
+    this.schedulePoll()
+    this.scheduleTick(true)
+  }
+
+  setConfiguration(active: boolean, preventIdleSleep: boolean): void {
+    const resumed = !this.active && active
+    this.active = active
+    this.preventIdleSleep = preventIdleSleep
+    if (resumed) {
+      const current = this.power.snapshot()
+      this.power.updateReasons({
+        runningSessions: current.runningSessions,
+        armedSchedules: this.armedSchedules(),
+        sessionStateKnown: false,
+      })
+    }
+    this.power.setEnabled(active && preventIdleSleep)
+    if (resumed) {
+      this.schedulePoll()
+      this.scheduleTick(true)
+    }
+    this.emit()
+  }
+
+  snapshot(): TaskBoardSnapshot {
+    const state = this.ledger.state()
+    return {
+      schemaVersion: 2,
+      revision: state.revision,
+      tasks: state.tasks,
+      scheduler: state.scheduler,
+      power: this.power.snapshot(),
+    }
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener)
+    return () => { this.listeners.delete(listener) }
+  }
+
+  apply(requestId: string, action: TaskBoardAction): TaskBoardSnapshot {
+    if (!this.active) throw new Error('task board is disabled')
+    const result = this.ledger.applyRequest(requestId, action)
+    if (result.run !== undefined) this.scheduleLaunch(result.run)
+    return {
+      schemaVersion: 2,
+      revision: result.state.revision,
+      tasks: result.state.tasks,
+      scheduler: result.state.scheduler,
+      power: this.power.snapshot(),
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true
+    for (const timer of this.timers.splice(0)) clearInterval(timer)
+    this.power.dispose()
+    this.ledger.dispose()
+    this.listeners.clear()
+  }
+
+  private async launch(opened: OpenedRun): Promise<void> {
+    try {
+      const sessionId = await this.runner.launch(opened.task)
+      this.ledger.attachSession(opened.task.id, opened.execution.id, sessionId)
+    } catch (error) {
+      if (error instanceof SessionLaunchError) {
+        this.ledger.attachSession(opened.task.id, opened.execution.id, error.sessionId)
+      }
+      this.ledger.settle(opened.task.id, opened.execution.id, 'failed', error instanceof Error ? error.message : String(error))
+    }
+  }
+
+  private async pollSessions(): Promise<void> {
+    if (this.disposed) return
+    if (!this.active && !this.hasOpenExecutions()) return
+    const running = await this.runner.listRunning()
+    const previous = this.power.snapshot()
+    this.power.updateReasons({
+      runningSessions: running.known ? running.count : previous.runningSessions,
+      armedSchedules: this.armedSchedules(),
+      sessionStateKnown: running.known,
+    })
+    if (running.known) await this.reconcileExecutions()
+    this.emit()
+  }
+
+  private async reconcileExecutions(): Promise<void> {
+    for (const task of this.ledger.state().tasks) {
+      for (const execution of task.executions) {
+        if (execution.sessionId === undefined || execution.endedAt !== undefined) continue
+        try {
+          const result = await this.runner.inspect(execution.sessionId, execution.startedAt)
+          if (result.outcome === 'pending') continue
+          this.ledger.settle(task.id, execution.id, result.outcome, 'error' in result ? result.error : undefined)
+        } catch {
+          // A transient inspection failure never settles a running execution.
+        }
+      }
+    }
+  }
+
+  private async tickSchedule(first: boolean): Promise<void> {
+    if (this.disposed || !this.active) return
+    const now = this.now()
+    const recovered = first || (this.lastScheduleTick !== undefined && now - this.lastScheduleTick > RESUME_GAP_MS)
+    this.lastScheduleTick = now
+    this.ledger.setScheduler({ lastTickAt: now })
+    if (recovered) {
+      this.ledger.skipMissed(now)
+      return
+    }
+    for (const task of this.ledger.state().tasks) {
+      if (task.archivedAt !== undefined) continue
+      const schedule = task.schedule
+      if (schedule === undefined || !schedule.enabled || schedule.nextRunAt === undefined || schedule.nextRunAt > now) continue
+      const next = nextRunAtMs(schedule.cron, schedule.nextRunAt)
+      const opened = this.ledger.openScheduled(task.id, next, now)
+      if (opened !== undefined) this.scheduleLaunch(opened)
+    }
+  }
+
+  private armedSchedules(): number {
+    return this.ledger.state().tasks.filter((task: TaskRecord) => task.archivedAt === undefined && task.schedule?.enabled === true).length
+  }
+
+  private hasOpenExecutions(): boolean {
+    return this.ledger.state().tasks.some(task => task.executions.some(execution => execution.endedAt === undefined))
+  }
+
+  private scheduleLaunch(opened: OpenedRun): void {
+    void this.launch(opened).catch(error => {
+      console.error('[dsh-task-board] execution launch settlement failed', error)
+    })
+  }
+
+  private schedulePoll(): void {
+    if (this.pollInFlight || this.disposed) return
+    this.pollInFlight = true
+    void this.pollSessions().catch(error => {
+      console.error('[dsh-task-board] session polling failed', error)
+    }).finally(() => { this.pollInFlight = false })
+  }
+
+  private scheduleTick(first: boolean): void {
+    if (this.tickInFlight || this.disposed) return
+    this.tickInFlight = true
+    void this.tickSchedule(first).catch(error => {
+      console.error('[dsh-task-board] scheduler tick failed', error)
+    }).finally(() => { this.tickInFlight = false })
+  }
+
+  private syncPowerReasons(): void {
+    const current = this.power.snapshot()
+    this.power.updateReasons({
+      runningSessions: current.runningSessions,
+      armedSchedules: this.armedSchedules(),
+      sessionStateKnown: current.sessionStateKnown,
+    })
+    this.power.setEnabled(this.active && this.preventIdleSleep)
+  }
+
+  private emit(): void {
+    for (const listener of [...this.listeners]) listener()
+  }
+}

package/src/index.ts

@@ -1,28 +1,31 @@
 /**
  * Host loader entry for the task-board plugin.
  *
- * Everything the board does is browser work (DOM, localStorage, driving the
- * client runtime's session services over the wire), so the host half's main
- * behavior is a system-prompt section announcing the plugin to every agent.
- * The section registers while this plugin is in the host composition (mount /
- * DSH restart) and disappears when the plugin leaves it (unmount / restart),
- * so agents always know the board exists and how to cooperate with it. The
- * announcement can be turned off through the web settings plugin-configuration
- * surface (`announceToAgent`); the section then disappears live.
+ * The Host owns the v2 ledger, action API, cron scheduler, session runner,
+ * execution reconciliation, and optional idle-sleep inhibitor. The browser is
+ * a same-origin asynchronous view over that service.
  */
 
 import type { Context } from '@deepseek-ai/cordis'
 import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-host-apiproxy'
+import type {} from '@deepseek-ai/dsh-host-webserver'
+import { TaskBoardHostService } from './host-service.ts'
+import { makeTaskBoardRoutes } from './host-routes.ts'
+import { mountOnce } from './mount-once.ts'
 
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 200
 
-export const inject = ['systemPrompt']
+/** Default environment variable holding the authenticated proxy token. */
+export const DEFAULT_PROXY_TOKEN_ENV = 'DSH_TASK_BOARD_PROXY_TOKEN'
+
+export const inject = ['systemPrompt', 'apiProxy', 'webServer']
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const TASK_BOARD_GUIDANCE = '本机已安装 dsh-task-board 插件（DSH Web GUI 的任务看板）：侧边栏「任务看板」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-task-board）统一维护，经聚合包 web-ui-all 一键安装。能力：多列看板管理任务；任务可真实执行（驱动 agent 会话）；任务可钉住执行目标——工作区 / 模式（agent 预设）/ 权限（read-only / workspace-write / danger-full-access），缺省用运行时默认；任务支持 5 段 cron 定时执行（如 0 23 * * *）；数据存浏览器 localStorage（键 dsh.taskBoard.v1）。限制：定时调度在浏览器端，需 GUI 标签页打开，错过即跳过；执行消耗 API 额度。用户提到「任务看板 / 看板 / 定时任务」时即指本插件，请据此协作。'
+export const TASK_BOARD_GUIDANCE = '本机已安装 dsh-task-board 插件（DSH Web GUI 的任务看板）：侧边栏「任务看板」入口；在 dsh-web-ui 插件全家桶仓库（packages/dsh-task-board）统一维护，经聚合包 web-ui-all 一键安装。能力：多列看板管理任务；Host 权威账本；关闭浏览器后仍由 Host 执行和结算；任务可钉住工作区、agent 预设和权限；支持 Host 本地时区的 5 段 cron，错过的触发点不补跑；可选且默认关闭的空闲系统睡眠保护允许屏幕熄灭，但不承诺拦截合盖、手动睡眠、休眠、关机或唤醒已睡眠机器。执行消耗 API 额度。用户提到「任务看板 / 看板 / 定时任务」时即指本插件，请据此协作。'
 
 /**
  * Settings namespace of the board's announcement capability — the section the
@@ -41,13 +44,35 @@ export interface Config {
   announceToAgent?: boolean
   /** Master switch for the plugin (browser half + host announcement). */
   enabled?: boolean
+  /** Prevent idle system sleep while sessions run or schedules are armed. */
+  preventIdleSleep?: boolean
+  /** Canonical reverse-proxy Host authorities admitted with a server-side token. */
+  trustedProxyHosts?: string[]
+  /** Environment variable whose value the authenticated proxy injects upstream. */
+  proxyTokenEnv?: string
 }
 
 export const Config: z<Config> = z.object({
   announceToAgent: z.boolean().default(true),
   enabled: z.boolean().default(true),
+  preventIdleSleep: z.boolean().default(false),
+  trustedProxyHosts: z.array(z.string()).default([]),
+  proxyTokenEnv: z.string().min(1).default(DEFAULT_PROXY_TOKEN_ENV),
 })
 
+/** Resolve proxy access without ever placing the token value in plugin config. */
+export function resolveProxyAccess(config: Config | undefined, env: NodeJS.ProcessEnv = process.env): { trustedProxyHosts: string[]; proxyToken?: string } {
+  const trustedProxyHosts = config?.trustedProxyHosts ?? []
+  if (trustedProxyHosts.length === 0) return { trustedProxyHosts }
+  const proxyTokenEnv = config?.proxyTokenEnv ?? DEFAULT_PROXY_TOKEN_ENV
+  if (proxyTokenEnv.trim() === '') throw new Error('task-board: proxyTokenEnv must not be empty')
+  const proxyToken = env[proxyTokenEnv]
+  if (proxyToken === undefined || proxyToken === '') {
+    throw new Error(`task-board: trustedProxyHosts requires a non-empty ${proxyTokenEnv} environment variable`)
+  }
+  return { trustedProxyHosts, proxyToken }
+}
+
 /** Schema default, re-read for hand-built test contexts (the loader applies them normally). */
 const DEFAULT_ANNOUNCE = true
 
@@ -59,7 +84,26 @@ const DEFAULT_ANNOUNCE = true
  * @param ctx - the plugin context (systemPrompt injected).
  * @param config - resolved plugin config (schema defaults applied by the loader).
  */
-export function apply(ctx: Context, config?: Config): void {
+export const apply = mountOnce('@linxin666/dsh-client-ui-task-board', applyImpl)
+
+function applyImpl(ctx: Context, config?: Config): void {
+  const host = new TaskBoardHostService(ctx.apiProxy)
+  host.setConfiguration(config?.enabled ?? true, config?.preventIdleSleep ?? false)
+  host.start()
+  ctx.effect(() => {
+    const disposers: Array<() => void> = []
+    try {
+      for (const route of makeTaskBoardRoutes(host, resolveProxyAccess(config))) disposers.push(ctx.webServer.register(route))
+    } catch (error) {
+      for (const dispose of disposers) dispose()
+      host.dispose()
+      throw error
+    }
+    return () => {
+      for (const dispose of disposers) dispose()
+      host.dispose()
+    }
+  }, 'task-board: host ledger, scheduler, and routes')
   // The live source the announcement reads: the settings section once the web
   // settings surface is served, the composition entry otherwise
   // (installSettingsSection swaps it when the namespace registers).
@@ -74,7 +118,9 @@ export function apply(ctx: Context, config?: Config): void {
       disposeSection()
       disposeSection = undefined
     }
-    if ((current().enabled ?? true) === false) return
+    const active = current().enabled ?? true
+    host.setConfiguration(active, current().preventIdleSleep ?? false)
+    if (!active) return
     if ((current().announceToAgent ?? DEFAULT_ANNOUNCE) === false) return
     disposeSection = ctx.systemPrompt.section({
       name: 'plugin:task-board',

package/src/loopback.ts

@@ -0,0 +1,63 @@
+// Generated by scripts/sync-shared.mjs from shared/host/loopback.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Loopback trust fence shared by the host route families: socket address,
+ * Host header, and browser same-origin markers. Packages receive this file as
+ * a generated copy via scripts/sync-shared.mjs; edit the shared source and
+ * re-run the sync instead of editing a copy.
+ *
+ * Semantics: RFC 5735 IPv4 127/8, ::1, IPv4-mapped ::ffff:127/8 (matching the
+ * remote-web-ui gate), localhost hostnames, plus the browser same-origin
+ * markers (sec-fetch-site and Origin) for the request-level fence.
+ * @module dsh-web-ui-shared/host/loopback
+ */
+
+import type { IncomingMessage } from 'node:http'
+
+/** IPv4 127/8 predicate (four decimal octets, first == 127). */
+export function isIPv4Loopback(v4: string): boolean {
+  const parts = v4.split('.')
+  return parts.length === 4
+    && parts[0] === '127'
+    && parts.every(part => /^\d{1,3}$/.test(part) && Number(part) <= 255)
+}
+
+/** Whether a socket remote address names the loopback range (127/8, ::1, IPv4-mapped). */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (address === undefined) return false
+  const normalized = address.toLowerCase()
+  if (normalized === '::1') return true
+  if (normalized.startsWith('::ffff:')) return isIPv4Loopback(normalized.slice('::ffff:'.length))
+  return isIPv4Loopback(normalized)
+}
+
+/** Whether a normalized URL hostname names the loopback authority (localhost, [::1], 127/8). */
+export function isLoopbackHostname(hostname: string): boolean {
+  if (hostname === 'localhost' || hostname === '[::1]') return true
+  return isIPv4Loopback(hostname)
+}
+
+/**
+ * Request-level trust fence: a loopback socket address AND a loopback Host
+ * header, plus browser same-origin markers. The socket address is
+ * authoritative; X-Forwarded-For is never trusted.
+ */
+export function isLoopbackRequest(request: IncomingMessage): boolean {
+  if (!isLoopbackAddress(request.socket.remoteAddress)) return false
+  const host = request.headers.host
+  if (typeof host !== 'string') return false
+  let hostUrl: URL
+  try {
+    hostUrl = new URL('http://' + host)
+  } catch {
+    return false
+  }
+  if (!isLoopbackHostname(hostUrl.hostname)) return false
+  if (request.headers['sec-fetch-site'] === 'cross-site') return false
+  const origin = request.headers.origin
+  if (origin === undefined) return true
+  try {
+    return new URL(origin).host === hostUrl.host
+  } catch {
+    return false
+  }
+}

package/src/mount-once.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/sync-shared.mjs from shared/host/mount-once.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
+/**
+ * Host single-instance guard shared by the plugin family. The family bundle
+ * (dsh-web-ui-all / dsh-skins) namespaces every child row id (web-ui-*), so
+ * the loader accepts a standalone install of the same package side by side;
+ * without this guard the second instance would still re-register the same
+ * webserver routes, tools, settings namespaces, and system-prompt sections
+ * and fail the boot. mountOnce makes the second host apply a no-op for the
+ * lifetime of the first instance (the browser half is already deduped by
+ * package name in the client module host).
+ *
+ * The registry rides a global symbol so two module instances of the same
+ * package (npm copy vs repository link) still share one verdict. cordis
+ * `ctx.effect` runs its callback immediately and treats the callback's
+ * return value as the fiber disposer, so the unmarker is returned, not run.
+ */
+
+const MOUNTED = Symbol.for('dsh-web-ui.mounted-plugins')
+
+interface MountRegistry {
+  [MOUNTED]?: Set<string>
+}
+
+function mountedSet(): Set<string> {
+  const registry = globalThis as MountRegistry
+  return (registry[MOUNTED] ??= new Set())
+}
+
+/**
+ * Wrap a cordis plugin apply so the package runs at most once per process.
+ * The first mount registers normally and unmarks when its fiber disposes;
+ * any later mount of the same package name is a no-op.
+ * @param packageName - npm package identity shared by every install source.
+ * @param fn - the original plugin apply.
+ * @returns an apply of the same shape.
+ */
+export function mountOnce<T extends (...args: any[]) => unknown>(packageName: string, fn: T): T {
+  return ((...args: unknown[]) => {
+    const mounted = mountedSet()
+    if (mounted.has(packageName)) return
+    mounted.add(packageName)
+    const ctx = args[0] as { effect?: (effect: () => unknown) => unknown } | undefined
+    ctx?.effect?.(() => () => {
+      mounted.delete(packageName)
+    })
+    return fn(...args)
+  }) as T
+}