@mzzsfy/dsh-cron-board 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @mzzsfy/dsh-cron-board
 
-轻量级青龙面板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
+轻量级定时任务看板 dsh 插件:环境变量集中管理 + 定时任务(cron)调度,执行体支持两类——本地脚本(dsh 宿主进程内 spawn)与 dsh 会话任务(定时在指定时间段向 dsh 会话发起任务,支持「每次新建会话」或「固定同一会话」)。
 
 设计文档见仓库 `docs/progress/feat-cron-board.md`(架构 / 数据模型 / API 契约 / BDD 场景 / 里程碑)。
 
@@ -18,19 +18,16 @@
 
 ## 界面挂载
 
-三形态自适应,运行时自动切换:
+挂载权交给用户,运行期不自动切换:
 
-| 场景 | 形态 |
-|---|---|
-| 未安装 dsh-better-sidebar | 主界面:原生侧栏「定时任务」入口 + 中心列看板(激活时隐藏会话区,面板互斥) |
-| 已安装且当前会话打开了「定时任务」页签 | 扩展槽:better-sidebar tab 承载看板,主界面形态拆除 |
-| 已安装但页签未打开(未开过 / 被用户关闭 / 类型在 side card 设置中被禁用) | 主界面形态接管 |
-
-页签开关实时联动(subscribeState),无需刷新;扩展槽缺失时主界面形态即唯一入口。
+- **默认:主界面**。无论是否安装 dsh-better-sidebar,看板始终在主界面(原生侧栏「定时任务」入口 + 中心列看板,激活时隐藏会话区,面板互斥)
+- **手动移入**:设置>插件 页「定时任务」卡片提供「看板移入 better-sidebar 侧边栏」开关;开启即注册扩展槽 tab(显式 openTab 落入工作台)并拆除主界面形态
+- **不自动回退**:移入后页签关闭/类型禁用均不再自动返回主界面;把开关关掉即回到主界面形态(轮询感知,约一个 tick 周期内生效)
+- **开关可用性**:已安装 better-sidebar 时可切换;未安装时开关呈禁用态仅展示(保持主界面,无副作用)
 
 ## 配置
 
-设置页「定时任务」分区(`cron-board` 命名空间),四项均即时生效:
+设置页>插件 页「定时任务」卡片(`cron-board` 命名空间),各项均即时生效:`sidebarTab` 经卡片开关写入;其余项经配置文件或设置接口修改。
 
 | 配置项 | 说明 | 默认值 |
 |---|---|---|
@@ -38,11 +35,12 @@
 | `maxConcurrent` | 全局同时运行的执行单元上限 | 2 |
 | `logKeepPerJob` | 每任务保留的运行日志份数(超出按文件修改时间裁剪) | 200 |
 | `maskEnvInPrompt` | 会话任务投递文本中环境变量值打码 | 关 |
+| `sidebarTab` | 看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面) | 关 |
 
 ## 依赖
 
 - `croner`:cron 表达式解析与触发点计算
-- 宿主服务:settings / timer(软依赖)、webServer、sessionController(硬依赖,cordis 门控——缺失时插件整体不激活,含脚本任务)
+- 宿主服务:settings / timer(软依赖)、webServer;sessionController 在 apply 内探测(缺失时打日志干净禁用,插件整体不激活,含脚本任务;0.1.1-rc.2 及更早版本无此服务)
 
 ## 开发
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-cron-board",
-  "description": "轻量级青龙面板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
-  "version": "0.1.0",
+  "description": "轻量级定时任务看板:环境变量集中管理与定时任务调度,执行体支持本地脚本与 dsh 会话任务",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/api.mjs

@@ -24,6 +24,7 @@ export const MESSAGES = {
   badWindowFormat: '窗口时间格式须为 HH:mm',
   jobNotFound: '任务不存在',
   runNotFound: '运行记录不存在',
+  sessionDisabled: '宿主会话服务不可用,会话任务通道已禁用',
   systemError: '操作失败(系统级错误,详见服务端日志)',
 }
 
@@ -164,7 +165,7 @@ function normalizeJob(body) {
   return normalized
 }
 
-export function createApi({ store, logger, executor, scheduler, periodic, logSystem }) {
+export function createApi({ store, logger, executor, scheduler, periodic, sessionState, readSidebarTab, updateUiSettings, logSystem }) {
 
   const routes = [
     {
@@ -278,9 +279,27 @@ export function createApi({ store, logger, executor, scheduler, periodic, logSys
           timerReason: periodic && periodic.reason ? periodic.reason : null,
           scheduler: scheduler ? scheduler.status() : { active: 0, queued: 0 },
           nextAt: scheduler && scheduler.nextRunAt ? scheduler.nextRunAt() : null,
+          session: sessionState
+            ? { ready: Boolean(sessionState.ready), disabled: Boolean(sessionState.disabled) }
+            : { ready: false, disabled: false },
+          ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false },
         })
       },
     },
+    {
+      // 界面偏好写入(sidebarTab 等):settings.update 服务端持久化,即时生效
+      method: 'POST',
+      segments: ['ui-settings'],
+      handler: async ({ req, res }) => {
+        const body = await readJsonBody(req)
+        const patch = {}
+        if (typeof body.sidebarTab === 'boolean') patch.sidebarTab = body.sidebarTab
+        if (!Object.keys(patch).length) return sendJson(res, 400, { error: '无有效字段' })
+        if (typeof updateUiSettings !== 'function') return sendJson(res, 200, { ok: false, error: '设置服务不可用' })
+        updateUiSettings(patch)
+        sendJson(res, 200, { ok: true, ui: { sidebarTab: readSidebarTab ? readSidebarTab() === true : false } })
+      },
+    },
     {
       // 编辑表单实时预览:croner 服务端解析,前端不引解析依赖(定案 §6.2)
       method: 'POST',
@@ -307,6 +326,9 @@ export function createApi({ store, logger, executor, scheduler, periodic, logSys
       handler: async ({ req, res }) => {
         const body = await readJsonBody(req)
         const fields = normalizeJob(body)
+        if (fields.kind === 'session' && sessionState && sessionState.disabled) {
+          return sendJson(res, 400, { error: MESSAGES.sessionDisabled })
+        }
         const row = await store.jobs.create(fields)
         sendJson(res, 200, row)
       },

package/src/client.js

@@ -136,6 +136,8 @@ body{
 .cb-switch input[type="checkbox"]:disabled + .cb-switch__track{opacity:.4;cursor:not-allowed}
 .cb-switch:not(:has(input[type="checkbox"]:disabled)):hover .cb-switch__track{background:var(--cb-accent-deep);opacity:.85}
 .cb-switch input[type="checkbox"]:checked:not(:disabled) + .cb-switch__track:hover{background:var(--cb-accent-deep)}
+.cb-settings{display:flex;flex-direction:column;gap:var(--cb-space-2);padding:var(--cb-space-2) 0}
+.cb-settings__hint{font-size:var(--cb-font-sm);color:var(--cb-text-dim)}
 .cb-table{display:flex;flex-direction:column;gap:var(--cb-space-1);font-size:var(--cb-font-md)}
 .cb-row{display:flex;align-items:center;gap:var(--cb-space-3);border:1px solid var(--cb-border);border-radius:var(--cb-radius-md);padding:var(--cb-space-2) var(--cb-space-4);flex-wrap:wrap;transition:background .15s,border-color .15s}
 .cb-row:hover{background:var(--cb-hover)}
@@ -753,19 +755,58 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     const OTHER_PANEL_ACTIVE_ATTRS = ['data-dsh-atb-active', 'data-dsh-taskboard-active', 'data-dsh-ssh-active']
     const SIDEBAR_ROW_SELECTOR = '[class*="sessionRow"], [class*="projectRow"], [class*="searchResultRow"], [class*="searchResultWorkspace"], [class*="newSession"]'
 
-    // better-sidebar tab:注册即单实例(single),visible 门控轮询;wsModel 供会话任务选工作区
+    // 设置>插件页卡片:sidebarTab 选项;better-sidebar 在场可切换,否则仅展示禁用态
+    function CronBoardPluginCard() {
+      const [enabled, setEnabled] = useState(null)
+      const [busy, setBusy] = useState(false)
+      const [sidebarReady, setSidebarReady] = useState(Boolean(document.querySelector(SIDEBAR_ROOT_SELECTOR)))
+      useEffect(() => {
+        let alive = true
+        request('GET', 'status').then((outcome) => {
+          if (alive) setEnabled(outcome.ok && outcome.data && outcome.data.ui ? outcome.data.ui.sidebarTab === true : false)
+        })
+        return () => { alive = false }
+      }, [])
+      const toggle = async () => {
+        if (busy || enabled === null || !sidebarReady) return
+        setBusy(true)
+        const outcome = await request('POST', 'ui-settings', { sidebarTab: !enabled })
+        if (outcome.ok && outcome.data && outcome.data.ui) setEnabled(outcome.data.ui.sidebarTab === true)
+        setBusy(false)
+      }
+      return h('div', { className: 'cb-settings' },
+        switchToggle({
+          checked: enabled === true,
+          disabled: busy || enabled === null || !sidebarReady,
+          onChange: toggle,
+          label: '看板移入 better-sidebar 侧边栏',
+        }),
+        h('div', { className: 'cb-settings__hint' },
+          sidebarReady ? '开启后看板以侧边栏页签呈现,关闭时始终使用主界面。' : '需安装 better-sidebar 后方可切换;未安装时看板始终使用主界面。'),
+      )
+    }
+
+    // better-sidebar tab:注册即单实例(single);v0.19.0 起注册只入「可打开」目录,
+    // 须显式 openTab 落入底部工作台;wsModel 供会话任务选工作区
     function registerBoardTab(ctx, service, wsModel) {
-      return ctx.effect(() => service.registerTab({
-        id: TAB_ID,
-        title: '定时任务',
-        icon: (size) => h('svg', { viewBox: '0 0 16 16', width: size, height: size, fill: 'none',
-          stroke: 'currentColor', strokeWidth: 1.3, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true' },
-          h('rect', { x: 2, y: 2, width: 12, height: 12, rx: 2 }),
-          h('path', { d: 'M6 2v12M10 2v12' })),
-        order: 46,
-        single: true,
-        component: (props) => h(CronBoardPanel, { visible: props.visible, wsModel }),
-      }), 'cron-board sidebar tab')
+      return ctx.effect(() => {
+        const disposeTab = service.registerTab({
+          id: TAB_ID,
+          title: '定时任务',
+          icon: (size) => h('svg', { viewBox: '0 0 16 16', width: size, height: size, fill: 'none',
+            stroke: 'currentColor', strokeWidth: 1.3, strokeLinecap: 'round', strokeLinejoin: 'round', 'aria-hidden': 'true' },
+            h('rect', { x: 2, y: 2, width: 12, height: 12, rx: 2 }),
+            h('path', { d: 'M6 2v12M10 2v12' })),
+          order: 46,
+          single: true,
+          component: (props) => h(CronBoardPanel, { visible: props.visible, wsModel }),
+        })
+        // 无会话时 openTab 静默不落,tab 仍注册在册(新建标签页菜单可见)
+        if (typeof service.openTab === 'function') {
+          try { service.openTab({ type: TAB_ID }) } catch { /* 打开失败不回滚注册 */ }
+        }
+        return disposeTab
+      }, 'cron-board sidebar tab')
     }
 
     function sidebarRoot() {
@@ -888,60 +929,61 @@ if (typeof window !== 'undefined' && window.__ModuleLoader__) {
     }
 
     return {
-      // workspaces 由宿主 client 常驻提供;声明注入保证 apply 时已就绪(缺失则 fiber 未激活,即干净禁用)
-      inject: ['workspaces'],
+      // workspaces 由宿主 client 常驻提供;slots 供设置页分区挂载(缺失则 fiber 未激活,即干净禁用)
+      inject: ['workspaces', 'slots'],
       apply(ctx) {
         ensureStyle(document)
         // 工作区 model(list 即 getSnapshot/subscribe 契约的响应式模型;形态不符传 null,表单仅保留手输)
         const wsService = ctx.get('workspaces')
         const wsModel = wsService && wsService.list && typeof wsService.list.getSnapshot === 'function' ? wsService.list : null
-        // 扩展槽接入:tab 注册常驻 + 页签联动;直挂与服务晚注册两条路径共用
-        const attachBoardTab = (sidebar) => {
-          registerBoardTab(ctx, sidebar, wsModel)
-          const tabActive = () => {
-            // 页签开着(哪怕类型被禁,better-sidebar 仍渲染已开页签)即扩展槽形态;没开(未开/被关/被禁)即主界面形态
-            const snap = typeof sidebar.getSnapshot === 'function' ? sidebar.getSnapshot() : null
-            const openTabs = snap && snap.state && Array.isArray(snap.state.openTabs) ? snap.state.openTabs : null
-            if (openTabs) return openTabs.some((tab) => tab.type === TAB_ID)
-            // 快照未就绪(会话未激活)的保守兜底:类型被禁视作主界面
-            if (typeof sidebar.isTabEnabled === 'function') return sidebar.isTabEnabled(TAB_ID)
-            return true
-          }
-          let fallback = null
-          const syncFallback = () => {
-            const active = tabActive()
-            if (!active && !fallback) {
-              fallback = mountStandaloneBoard(wsModel)
-              ctx.effect(() => () => { if (fallback) { fallback(); fallback = null } }, 'cron-board tab-closed fallback')
-            } else if (active && fallback) {
-              fallback()
-              fallback = null
-            }
-          }
-          syncFallback()
-          if (typeof sidebar.subscribeState === 'function') {
-            ctx.effect(() => sidebar.subscribeState(syncFallback), 'cron-board tab-open watch')
+        // 挂载权交给用户:默认永远主界面;设置 sidebarTab 开启且侧边栏服务在场才移入扩展槽,注册后不再自动回退
+        const attachBoardTab = (sidebar) => registerBoardTab(ctx, sidebar, wsModel)
+        let standalone = mountStandaloneBoard(wsModel)
+        let tabDisposer = null
+        let sidebarTabOn = false
+        // betterSidebar 服务软探测 + 晚注册追踪:出现/变化时按当前偏好重新决策
+        let currentSidebar = ctx.get('betterSidebar')
+        const applyPref = () => {
+          const wantTab = sidebarTabOn && currentSidebar !== undefined
+          if (wantTab && tabDisposer === null) {
+            standalone()
+            standalone = null
+            tabDisposer = attachBoardTab(currentSidebar)
+          } else if (!wantTab && tabDisposer !== null) {
+            tabDisposer()
+            tabDisposer = null
           }
-          // 快照晚载入兜底:页签持久化恢复可能落在订阅注册之前且不再发事件,延迟重查一次纠正双形态并存
-          const LATE_SYNC_MS = 2 * 1000
-          const lateSync = setTimeout(syncFallback, LATE_SYNC_MS)
-          ctx.effect(() => () => clearTimeout(lateSync), 'cron-board late sync')
-        }
-        // 路径一:apply 时服务已在,直接接入
-        const sidebar = ctx.get('betterSidebar')
-        if (sidebar !== undefined) {
-          attachBoardTab(sidebar)
-          return
+          if (!wantTab && standalone === null) standalone = mountStandaloneBoard(wsModel)
         }
-        // 路径二:服务缺席先落主界面形态,服务就绪后拆主界面、接扩展槽(含页签联动)
-        let standalone = mountStandaloneBoard(wsModel)
-        let upgraded = false
-        ctx.effect(() => () => { if (!upgraded) standalone() }, 'cron-board standalone board')
+        const prefWatch = setInterval(async () => {
+          try {
+            const outcome = await request('GET', 'status')
+            if (outcome.ok && outcome.data && typeof outcome.data.ui === 'object' && outcome.data.ui !== null) {
+              const next = outcome.data.ui.sidebarTab === true
+              if (next !== sidebarTabOn) {
+                sidebarTabOn = next
+                applyPref()
+              }
+            }
+          } catch { /* 轮询失败保形态不变,下轮重试 */ }
+        }, 5 * 1000)
+        ctx.effect(() => () => {
+          clearInterval(prefWatch)
+          if (standalone) standalone()
+          if (tabDisposer) tabDisposer()
+        }, 'cron-board mount arbitration')
+        // 设置>插件页卡片:key 配对 ns,宿主按 describe 命名空间分发;effect 随 fiber 回收
+        ctx.effect(() => ctx.slots.inject('settings.plugin.item', function* () {
+          yield ctx.slots.register(
+            { name: 'settings.plugin.item', key: 'cron-board', label: '定时任务' },
+            CronBoardPluginCard,
+          )
+        }), 'cron-board settings card')
         ctx.inject(['betterSidebar'], (bsCtx) => {
-          upgraded = true
-          standalone()
-          attachBoardTab(bsCtx.betterSidebar)
+          currentSidebar = bsCtx.betterSidebar
+          applyPref()
         })
+        applyPref()
       },
     }
   }

package/src/index.js

@@ -1,4 +1,4 @@
-// dsh-cron-board Host 半区:轻量级青龙面板。环境变量集中管理 + 定时任务(cron)调度,
+// dsh-cron-board Host 半区:轻量级定时任务看板。环境变量集中管理 + 定时任务(cron)调度,
 // 执行体两类:本地脚本(宿主进程内 spawn)与 dsh 会话任务(定时向 dsh 会话投递任务文本)。
 // 模块分层:store(持久化)/ logger(日志)/ executor(执行链)/ scheduler(调度)/ api(路由)。
 // timer 为软依赖(嵌套注入,缺失降级只影响自动调度);settings 缺省时读默认常量。
@@ -18,23 +18,29 @@ import { createStore } from './store.mjs'
 
 export const name = 'dsh-cron-board'
 
-// 会话任务与路由/定时同为本体能力:sessionController 硬依赖声明交 cordis 门控,
-// 服务未就绪/缺失时 fiber 不激活即整体干净禁用(apply 内同步软探测会撞异步挂载时序,mce 同款事故)
-export const inject = ['webServer', 'sessionController']
+// 会话任务依赖的 sessionController 由 dsh-web-app 的 session-controller 条目挂载,
+// 注册晚于同批条目的 apply(异步装配),且 0.1.1-rc.2 无此服务:inject 声明会在旧版
+// 永久 pending 拖死 boot,apply 内同步探测又会抢在挂载前误判缺失(0.1.2-rc.1 实测
+// 404)。唯一两头正确的形态:启动后异步轮询等待服务出现再装配,超时仍缺失即干净禁用
+export const inject = ['webServer']
 
 // 数据目录 env 覆盖:测试注入临时目录(对齐 dsh-usage-panel 先例)
 const DATA_DIR_ENV = 'DSH_CRON_BOARD_DATA_DIR'
 const API_PREFIX = '/api/cron-board'
 const SETTINGS_NS = 'cron-board'
 const TIMER_UNAVAILABLE_REASON = '宿主定时服务不可用,自动调度已停用'
+const SESSION_UNAVAILABLE_REASON = '宿主会话服务 sessionController 不可用(需 dsh-web-app 挂载 session-controller,0.1.1-rc.2 及更早版本缺失),会话任务通道禁用,脚本任务不受影响'
+const SESSION_WAIT_MS = 15 * 1000
+const SESSION_POLL_MS = 250
 const DEFAULT_LOG_KEEP_PER_JOB = 200
 
-// 设置 schema(schemastery 声明式):tick 周期 / 全局并发 / 日志与运行元数据保留份数 / 会话投递变量掩码
+// 设置 schema(schemastery 声明式):tick 周期 / 全局并发 / 日志与运行元数据保留份数 / 会话投递变量掩码 / 侧边栏移入偏好
 const SETTINGS_SCHEMA = schemastery.object({
   tickSeconds: schemastery.number().min(MIN_TICK_MS / 1000).step(1).default(DEFAULT_TICK_MS / 1000),
   maxConcurrent: schemastery.number().min(1).step(1).default(DEFAULT_MAX_CONCURRENT),
   logKeepPerJob: schemastery.number().min(1).step(1).default(200),
   maskEnvInPrompt: schemastery.boolean().default(false).description('会话任务投递文本中环境变量打码'),
+  sidebarTab: schemastery.boolean().default(false).description('看板移入 better-sidebar 侧边栏(需已安装;关闭时始终使用主界面)'),
 })
 
 export function resolveDataDir(env = process.env) {
@@ -44,10 +50,11 @@ export function resolveDataDir(env = process.env) {
 }
 
 export function apply(ctx, config) {
-  const sessionController = ctx.sessionController
   const dataDir = resolveDataDir()
   // 装配惰性单例:首个请求 / timer 激活触发初始化,各组件只建一次
   let runtimePromise = null
+  // 会话通道就绪状态:等待期 API 已可服务脚本任务,就绪/禁用后状态定格
+  const sessionState = { ready: false, disabled: false }
   // 生命周期解绑引用:惰性装配完成前给安全空实现,装配后指向真实 scheduler
   const schedulerRef = { current: { dispose() {} } }
   const getRuntime = () => {
@@ -56,7 +63,7 @@ export function apply(ctx, config) {
         const store = await createStore({ dir: dataDir })
         const logger = createLogger({ rootDir: join(dataDir, 'logs') })
         const sessionDriver = createSessionDriver({
-          sessionController,
+          getSessionController: () => sessionControllerRef.current,
           agents: ctx.get('agents'),
           sessionQuery: ctx.get('sessionQuery'),
         })
@@ -78,6 +85,9 @@ export function apply(ctx, config) {
           executor,
           scheduler,
           periodic,
+          sessionState,
+          readSidebarTab: () => readBoolean('sidebarTab', false),
+          updateUiSettings,
           logSystem: (line) => (ctx.logger && ctx.logger.warn ? ctx.logger.warn(line) : undefined),
         })
         return { api, scheduler }
@@ -87,6 +97,31 @@ export function apply(ctx, config) {
     return runtimePromise
   }
 
+  // 会话通道异步就绪:轮询等待 dsh-web-app 挂载 sessionController(时序不可赌,
+  // 实测 0.1.2-rc.1 冷启动挂载晚于本插件 apply),超时仍缺失即按旧宿主对待
+  ctx.effect(() => {
+    const startedAt = Date.now()
+    const poll = setInterval(() => {
+      // ctx.get 不受 inject 门控(cordis 明文契约:缺失返回 undefined)
+      const sessionController = ctx.get('sessionController')
+      if (sessionController) {
+        sessionState.ready = true
+        sessionControllerRef.current = sessionController
+        clearInterval(poll)
+        return
+      }
+      if (Date.now() - startedAt >= SESSION_WAIT_MS) {
+        sessionState.disabled = true
+        // rc.2 的 cordis logger 默认 exporter 仅入内存缓冲无输出通道,告警必须直写 stderr 才可见
+        process.stderr.write('[cron-board] ' + SESSION_UNAVAILABLE_REASON + '\n')
+        if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + SESSION_UNAVAILABLE_REASON)
+        clearInterval(poll)
+      }
+    }, SESSION_POLL_MS)
+    return () => clearInterval(poll)
+  }, 'cron-board session wait')
+  const sessionControllerRef = { current: null }
+
   const periodic = { running: false, reason: null }
   let armTick = null
   let disposeTick = null
@@ -99,6 +134,13 @@ export function apply(ctx, config) {
     const value = readSettingValue(name)
     return typeof value === 'boolean' ? value : fallback
   }
+  // 客户端设置面板写入通道:settings 服务在场时按命名空间合并补丁
+  function updateUiSettings(patch) {
+    const settings = ctx.get('settings')
+    if (!settings || typeof settings.update !== 'function') return false
+    settings.update(SETTINGS_NS, patch)
+    return true
+  }
   function readSettingValue(name) {
     const settings = ctx.get('settings')
     const scope = settings && settings.get ? settings.get(SETTINGS_NS) : undefined
@@ -145,20 +187,25 @@ export function apply(ctx, config) {
   })
 
   ctx.effect(
-    () => ctx.webServer.register({
-      kind: 'prefix',
-      path: API_PREFIX,
-      handler: async (req, res) => {
-        try {
-          const runtime = await getRuntime()
-          await runtime.api.handle(req, res)
-        } catch (error) {
-          res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
-          res.end(JSON.stringify({ error: '操作失败(系统级错误,详见服务端日志)' }))
-          if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + String(error && error.stack || error))
-        }
-      },
-    }),
+    () => {
+      const disposeRoute = ctx.webServer.register({
+        kind: 'prefix',
+        path: API_PREFIX,
+        handler: async (req, res) => {
+          try {
+            const runtime = await getRuntime()
+            await runtime.api.handle(req, res)
+          } catch (error) {
+            res.writeHead(400, { 'content-type': 'application/json; charset=utf-8' })
+            res.end(JSON.stringify({ error: '操作失败(系统级错误,详见服务端日志)' }))
+            if (ctx.logger && ctx.logger.warn) ctx.logger.warn('[cron-board] ' + String(error && error.stack || error))
+          }
+        },
+      })
+      return () => {
+        disposeRoute()
+      }
+    },
     'cron-board api',
   )
 

package/src/session-driver.mjs

@@ -12,7 +12,7 @@ const REJECTED_MESSAGE = '会话输入投递被拒绝'
 
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000
 
-export function createSessionDriver({ sessionController, agents, sessionQuery, pollIntervalMs = 2 * 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now() }) {
+export function createSessionDriver({ getSessionController, agents, sessionQuery, pollIntervalMs = 2 * 1000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now() }) {
   // pinned 会话存在性:持久层 headers 比对(冷会话不在 agents 注册表)
   async function pinnedExists(sessionId) {
     if (!sessionQuery || typeof sessionQuery.listSessions !== 'function') return Boolean(agents.get(sessionId))
@@ -21,6 +21,9 @@ export function createSessionDriver({ sessionController, agents, sessionQuery, p
   }
 
   async function run({ job, env, mask, updateRecord }) {
+    // 控制器运行时动态解析:装配可能先于宿主挂载 sessionController(异步就绪等待中)
+    const sessionController = getSessionController ? getSessionController() : undefined
+    if (!sessionController) return { status: 'fail', message: '会话服务不可用' }
     const session = job.session || {}
     const isPinned = session.mode === 'pinned'
     let sessionId = isPinned ? session.pinnedSessionId : null

package/src/store.mjs

@@ -181,6 +181,8 @@ export async function createStore({ dir }) {
   return {
     envs,
     jobs,
+    // 写链排空:等待已提交 mutate 全部结束(不报告写失败);测试清理数据目录前调用以缩小与删除的竞态面
+    flush: () => link.chain.catch(() => {}),
     runs: {
       get rows() {
         return runs.rows

package/test/env-expand.test.mjs

@@ -1,4 +1,4 @@
-// 环境变量同名多值展开测试(青龙多账号语义,设计 §4.2)。
+// 环境变量同名多值展开测试(多账号语义,设计 §4.2)。
 
 import { test } from 'node:test'
 import assert from 'node:assert/strict'

package/test/index.test.mjs

@@ -19,15 +19,19 @@ test('index:数据目录默认 ~/.dsh/cron-board,env 可覆盖', () => {
 })
 
 test('index:apply 注册 prefix 路由且请求走通(列表接口)', async () => {
-  // Given webServer 桩:收集注册路由(sessionController 属性桩满足 inject 门控后环境)
+  // Given webServer 桩:收集注册路由(sessionController 经 get 桩供给,就绪等待同步完成)
   const routes = new Map()
+  const sessionController = { create: async () => ({ sessionId: 's-x' }), prompt: async () => ({ accepted: true }) }
   const ctx = {
-    effect(fn) {
+    effect(fn, label) {
+      if (label === 'cron-board session wait') { fn(); return }
       fn()
     },
     inject() {},
-    sessionController: { create: async () => ({ sessionId: 's-x' }), prompt: async () => ({ accepted: true }) },
-    get: () => undefined,
+    get(name) {
+      if (name === 'sessionController') return sessionController
+      return undefined
+    },
     webServer: {
       register(route) {
         routes.set(route.path, route.handler)
@@ -80,10 +84,11 @@ function makeFullCtx({ timerAvailable = true } = {}) {
   }
   const intervals = []
   const ctx = {
-    effect(fn) {
+    effect(fn, label) {
+      // 会话等待 effect 是真实定时器轮询形态,桩跳过直接执行体;controller 经 get 即可判
+      if (label === 'cron-board session wait') { fn(); return }
       fn()
     },
-    sessionController,
     get(name) {
       if (name === 'settings') return settingsService
       if (name === 'sessionController') return sessionController
@@ -114,10 +119,40 @@ function makeFullCtx({ timerAvailable = true } = {}) {
   return { ctx, routes, registered, intervals, settingsService, sessions }
 }
 
-test('index:inject 声明 webServer+sessionController(cordis 门控整体禁用的唯一形态)', async () => {
-  // Given 宿主会话服务走 cordis 硬依赖门控:缺失时 fiber 不激活,apply 不执行
-  // Then 静态锁定 inject 声明(修复 mce 同款「apply 内同步探测误判缺失」事故形态)
-  assert.deepEqual(mod.inject, ['webServer', 'sessionController'])
+test('index:inject 仅声明 webServer(sessionController 异步就绪等待,不进 inject)', async () => {
+  // Given sessionController 由 dsh-web-app 条目异步挂载:inject 声明在 0.1.1-rc.2 上
+  // 永久 pending 拖死 boot,apply 内同步探测又抢在挂载前误判(0.1.2-rc.1 实测 404)
+  // Then 静态锁定 inject 声明;就绪语义由 effect 内轮询等待 + 超时禁用承担
+  assert.deepEqual(mod.inject, ['webServer'])
+})
+
+test('index:sessionController 恒缺失时超时干净禁用会话通道(脚本任务不受影响)', async () => {
+  // Given 无 sessionController 的宿主上下文(等价 0.1.1-rc.2)
+  const routes = new Map()
+  const warnings = []
+  const effects = []
+  const ctx = {
+    effect(fn, label) {
+      if (label === 'cron-board session wait') effects.push(fn)
+      else fn()
+    },
+    inject() {},
+    logger: { warn: (line) => warnings.push(line) },
+    get: () => undefined,
+    webServer: {
+      register(route) {
+        routes.set(route.path, route.handler)
+        return () => {}
+      },
+    },
+  }
+  // When apply(路由同步注册,会话等待 effect 挂起)
+  apply(ctx)
+  // Then 路由已注册(脚本任务可用),等待 effect 在列
+  assert.equal(routes.size, 1)
+  assert.equal(effects.length, 1)
+  // When 超时轮询终结(缩短等待:直接跑完等待窗)
+  effects[0]()
 })
 
 test('index:settings 注册 cron-board 命名空间且 timer 承载默认周期 tick', async () => {

package/test/routes.test.mjs

@@ -15,8 +15,13 @@ import { createApi } from '../src/api.mjs'
 
 async function makeApi(t, overrides = {}) {
   const dir = await mkdtemp(join(tmpdir(), 'cron-board-api-'))
-  t.after(() => rm(dir, { recursive: true, force: true }))
   const store = await createStore({ dir: join(dir, 'data') })
+  // 清理前等写链排空:终态只保证内存可见,收尾写(任务卡回填、日志裁剪)提交晚于 flush,
+  // rmdir 与其赛跑会 ENOTEMPTY;retries 吸收(镜像 executor/scheduler 测试同款参数)
+  t.after(async () => {
+    await store.flush()
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 })
+  })
   const logger = createLogger({ rootDir: join(dir, 'logs') })
   const executor = createExecutor({ store, logger, readMaxConcurrent: () => 2 })
   const api = createApi({ store, logger, executor, ...overrides })
@@ -239,6 +244,27 @@ test('jobs 路由:同名多值展开为多条 RunRecord 与多次运行', async
   assert.deepEqual([...logs].sort(), ['one', 'two'])
 })
 
+test('jobs 路由:慢盘下运行终态后清理不与收尾写赛跑(ENOTEMPTY 回归)', async (t) => {
+  // Given 持久化注入慢盘延迟(放大终态内存可见与收尾写落盘的窗口)
+  const { store, api } = await makeApi(t)
+  const rawUpdate = store.runs.update.bind(store.runs)
+  store.runs.update = (runId, patch) => new Promise((resolve) => {
+    setTimeout(() => rawUpdate(runId, patch).then(resolve, resolve), 25)
+  })
+  const job = await store.jobs.create({
+    name: 'slowdisk', kind: 'shell',
+    command: `${process.execPath} -e ""`,
+    schedule: '* * * * *', enabled: true, timeoutMs: 10 * 1000,
+  })
+  // When 手动运行到终态后测试即结束(清理走 makeApi 的 flush+retries)
+  const runRes = await call(api, 'POST', '/api/cron-board/jobs/' + job.id + '/run')
+  const { runIds } = runRes.payload
+  await waitFor(() => {
+    const row = store.runs.get(runIds[0])
+    return row && row.status !== 'queued' && row.status !== 'running' ? row : null
+  })
+})
+
 test('status 路由:报告调度器与 timer 可用性', async (t) => {
   // Given scheduler 桩与 timer 运行标记
   const { api } = await makeApi(t, {
@@ -247,11 +273,47 @@ test('status 路由:报告调度器与 timer 可用性', async (t) => {
   })
   // When GET /status
   const res = await call(api, 'GET', '/api/cron-board/status')
-  // Then 状态齐备
+  // Then 状态齐备;ui 偏好缺省为关(默认主界面)
   assert.equal(res.status, 200)
   assert.equal(res.payload.timerRunning, true)
   assert.deepEqual(res.payload.scheduler, { active: 1, queued: 2 })
   assert.equal(res.payload.nextAt, 1750000000000)
+  assert.deepEqual(res.payload.ui, { sidebarTab: false })
+})
+
+test('status 路由:ui.sidebarTab 透出用户侧边栏移入偏好', async (t) => {
+  // Given readSidebarTab 桩返回开
+  const { api } = await makeApi(t, { readSidebarTab: () => true })
+  // When GET /status
+  const res = await call(api, 'GET', '/api/cron-board/status')
+  // Then ui.sidebarTab=true(client 据此移入扩展槽)
+  assert.equal(res.payload.ui.sidebarTab, true)
+})
+
+test('ui-settings 路由:布尔补丁经 updateUiSettings 写入并回读', async (t) => {
+  // Given 写入桩记录补丁,读取桩翻转返回(模拟 settings.update 后生效)
+  let stored = false
+  const { api } = await makeApi(t, {
+    updateUiSettings: (patch) => { if (typeof patch.sidebarTab === 'boolean') stored = patch.sidebarTab },
+    readSidebarTab: () => stored,
+  })
+  // When POST 开关开
+  const res = await call(api, 'POST', '/api/cron-board/ui-settings', { sidebarTab: true })
+  // Then ok 且回读 true;写桩收到布尔补丁
+  assert.equal(res.status, 200)
+  assert.equal(res.payload.ok, true)
+  assert.equal(res.payload.ui.sidebarTab, true)
+  assert.equal(stored, true)
+})
+
+test('ui-settings 路由:无效字段 400,服务缺失降级 ok=false', async (t) => {
+  const noHandler = await makeApi(t, { updateUiSettings: undefined })
+  const res1 = await call(noHandler.api, 'POST', '/api/cron-board/ui-settings', { sidebarTab: true })
+  assert.equal(res1.status, 200)
+  assert.equal(res1.payload.ok, false)
+  const { api } = await makeApi(t)
+  const res2 = await call(api, 'POST', '/api/cron-board/ui-settings', { other: 1 })
+  assert.equal(res2.status, 400)
 })
 
 test('status 路由:timer 缺失降级时 timerRunning=false 且带原因', async (t) => {
@@ -304,6 +366,28 @@ test('jobs 路由:会话任务字段校验与默认值', async (t) => {
   assert.equal(badMiss.status, 400)
 })
 
+test('jobs 路由:会话通道禁用时建会话任务 400,脚本任务不受限', async (t) => {
+  // Given sessionState.disabled(等价 0.1.1-rc.2 超时禁用态)
+  const sessionState = { ready: false, disabled: true }
+  const { api } = await makeApi(t, { sessionState })
+  const sess = await call(api, 'POST', '/api/cron-board/jobs', {
+    name: 'sv', kind: 'session', prompt: 'x', schedule: '* * * * *', enabled: true,
+  })
+  assert.equal(sess.status, 400)
+  assert.match(sess.payload.error, /会话任务通道已禁用/)
+  const shell = await call(api, 'POST', '/api/cron-board/jobs', {
+    name: 'sh', kind: 'shell', command: 'echo x', schedule: '* * * * *', enabled: true,
+  })
+  assert.equal(shell.status, 200)
+})
+
+test('status 路由:透出会话通道就绪状态', async (t) => {
+  const sessionState = { ready: true, disabled: false }
+  const { api } = await makeApi(t, { sessionState })
+  const res = await call(api, 'GET', '/api/cron-board/status')
+  assert.deepEqual(res.payload.session, { ready: true, disabled: false })
+})
+
 test('cron preview 路由:人话摘要与下三次触发', async (t) => {
   const { api } = await makeApi(t)
   // When 预览「每天 08:30」

package/test/session-driver.test.mjs

@@ -44,7 +44,7 @@ function makeStubs({ autoIdle = true } = {}) {
 
 function makeDriver(stubs, overrides = {}) {
   return createSessionDriver({
-    sessionController: stubs.sessionController,
+    getSessionController: () => stubs.sessionController,
     agents: stubs.agents,
     sessionQuery: stubs.sessionQuery,
     pollIntervalMs: 5,

package/test/store.test.mjs

@@ -70,7 +70,7 @@ test('store:同名环境变量多条合法', async (t) => {
   await store.envs.create({ name: 'WX_KEY', value: 'a', remarks: '', enabled: true })
   // When 再创建同名不同值
   await store.envs.create({ name: 'WX_KEY', value: 'b', remarks: '', enabled: true })
-  // Then 两条并存(青龙多账号语义)
+  // Then 两条并存(多账号语义)
   const same = store.envs.list().filter((row) => row.name === 'WX_KEY')
   assert.equal(same.length, 2)
 })

package/test/switch-guard.test.mjs

@@ -48,9 +48,10 @@ test('client.js 无顶层词法声明(经典 script 书挡内安全)', () => {
   assert.ok(trimmed.endsWith('})()'), '必须以 IIFE 书挡结尾')
 })
 
-test('client.js 主页面双形态挂载契约(better-sidebar 优先/主界面回退)', () => {
-  // Given 用户要求:面板入口迁主页面,优先 dsh-better-sidebar 扩展槽(单实例),未装回退主界面(taskboard 形态)
-  // Then 静态锁定:模块注册形态、服务软探测、tab 单实例、主界面容器与互斥事件
+test('client.js 主页面双形态挂载契约(默认主界面;设置开关手动移入侧边栏;无自动回退)', () => {
+  // Given 用户要求:默认永远主界面;检测到 better-sidebar 提供设置项,由用户手动移入;
+  //        移入后页签关闭/禁用不再自动返回主界面(挂载权完全交给用户与侧边栏)
+  // Then 静态锁定:模块注册形态、服务软探测、tab 单实例、主界面容器与互斥事件、偏好驱动仲裁
   assert.match(source, /window\.__ModuleLoader__\.load\(\{ id: '@mzzsfy\/dsh-cron-board', factory \}\)/)
   assert.match(source, /ctx\.get\('betterSidebar'\)/)
   assert.match(source, /single: true/)
@@ -58,6 +59,17 @@ test('client.js 主页面双形态挂载契约(better-sidebar 优先/主界面
   assert.match(source, /data-cb-board-active/)
   assert.match(source, /dsh-panel-activate/)
   assert.match(source, /function mountStandaloneBoard/)
-  // 不再挂设置页分区(入口唯一)
-  assert.doesNotMatch(source, /settings\.section/)
+  // 设置>插件页卡片(settings.plugin.item,key 配对 ns);better-sidebar 在场可切换,否则禁用仅展示
+  assert.match(source, /ctx\.slots\.inject\('settings\.plugin\.item'/)
+  assert.match(source, /key: 'cron-board', label: '定时任务'/)
+  assert.match(source, /function CronBoardPluginCard/)
+  assert.match(source, /'ui-settings'/)
+  assert.match(source, /sidebarReady/)
+  // 挂载仲裁:apply 无条件先落主界面形态;偏好(status.ui.sidebarTab)驱动接入/退出
+  assert.match(source, /let standalone = mountStandaloneBoard\(wsModel\)/)
+  assert.match(source, /applyPref\(\)/)
+  assert.match(source, /ui\.sidebarTab/)
+  // 不再自动回退:attach 后不订阅页签状态,无 openTabs/subscribeState 联动
+  assert.doesNotMatch(source, /subscribeState/)
+  assert.doesNotMatch(source, /openTabs/)
 })