dsh-my-guardian 0.3.6 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-09-07
+
+### 变更
+
+- feat(observability): #155 插件状态查询聚合——统一 status-query 事件 + /plugin-status API (#170)
+- chore(plugins): #165 清理失效的 dsh.client.inject 声明（13 插件） (#167)
+- feat(guard): #144 启动名册静态预检——startup-issues.json + 面板置顶 + 不阻断启动 (#151)
+
 ## [0.3.6] - 2026-09-04
 
 ### 变更

package/README.md

@@ -86,6 +86,16 @@ dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian
 
 失败条目额外带**失败类型徽标**（依赖缺失 / 代码错误 / 其他），依赖缺失时并展示安装建议命令（如 `dsh plugin add dsh-shared`）。
 
+### 启动名册静态预检（issue #144）
+
+候选区只兜住"走候选区"的插件；**直接写进启动名册（`cordis.patch.yml` / profile / bundles）的插件仍由 DSH 启动时 all-or-nothing 加载**。守护在每次启动时对名册做静态预检（不实际加载插件）：
+
+- **包可解析**：名册中 `dsh-*` 插件的包必须在 profile node_modules 中存在
+- **peerDependencies 满足**：复用候选挂载的依赖预检
+- **无重复 entry id**：名册中同一 id 出现多次（加载时 `EntryGroup.update` 会抛 `duplicate loader entry id`）
+
+发现的问题写入 `$DSH_HOME/guardian/startup-issues.json`（原子写，名册健康也写空报告 + 检查时间），面板「最近事件」顶部**置顶**展示启动区问题，每条给出修复命令（`dsh plugin add ...`）与移除提示。**预检失败不阻断启动**——只记录、只告警，最坏情况是为启动失败留下排查记录。
+
 ### 效果截图（真实 DSH 实例验证）
 
 侧边栏"插件守护"诊断面板（独立 3081 端口隔离 DSH 实例实测）：

package/lib/api.js

@@ -191,5 +191,8 @@ function snapshot(shared) {
     staged: stagedList,
     promoted: promotedList,
     events: shared.state.events.slice(-10),
+    // startup-roster pre-check report (issue #144): empty array = healthy
+    startupIssues: Array.isArray(shared.startupIssues) ? shared.startupIssues : [],
+    startupCheckedAt: typeof shared.startupCheckedAt === 'number' ? shared.startupCheckedAt : null,
   }
 }

package/lib/client.js

@@ -182,6 +182,33 @@ const STYLES = `
 .dsh-my-guardian-event-message { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
   font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); }
 .dsh-my-guardian-event-time { flex:none; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); white-space:nowrap; }
+/* ── startup-roster issues (issue #144): pinned block above the list ────── */
+.dsh-my-guardian-startup-issues { display:flex; flex-direction:column; gap:2px; margin-top:4px; padding:6px 8px; border-radius:8px;
+  border:1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 6%, transparent);
+  animation:dsh-my-guardian-row-in 150ms var(--ds-ease-in-out); }
+.dsh-my-guardian-startup-issues-title { display:flex; align-items:center; gap:5px; padding:0 2px 3px;
+  font:var(--dsw-font-xxs-strong-12); color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-title svg { display:block; flex:none; }
+.dsh-my-guardian-startup-issues-count { display:inline-flex; align-items:center; justify-content:center; min-width:17px; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); color:var(--dsw-alias-label-primary-foreground); background:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-time { flex:1; text-align:right; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue { display:flex; flex-direction:column; gap:2px; padding:5px 6px; border-radius:6px;
+  border:1px solid var(--dsw-alias-border-l1); background:transparent; }
+.dsh-my-guardian-startup-issue:hover { background:var(--dsw-alias-interactive-bg-hover); }
+.dsh-my-guardian-startup-issue-head { display:flex; align-items:center; gap:6px; min-width:0; }
+.dsh-my-guardian-startup-issue-name { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
+  font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dsh-my-guardian-startup-issue-badge-unresolvable { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-duplicate-id { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-startup-issue-message { font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); line-height:1.6; }
+.dsh-my-guardian-startup-issue-line { display:flex; align-items:flex-start; gap:5px; padding:2px 0;
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); line-height:1.6; min-width:0; }
+.dsh-my-guardian-startup-issue-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue-line code { font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size:var(--dsw-font-xxxs-11);
+  color:var(--dsw-alias-state-success-primary); word-break:break-all; }
+.dsh-my-guardian-startup-issue-remove { min-width:0; word-break:break-all; }
 @keyframes dsh-my-guardian-row-in { from { opacity:0; transform:translateY(1px); } to { opacity:1; transform:none; } }
 @keyframes dsh-my-guardian-spin { to { transform:rotate(360deg); } }
 `
@@ -237,6 +264,13 @@ const strings = {
   failureCode: () => (isZh() ? '代码错误' : 'Code error'),
   failureOther: () => (isZh() ? '其他' : 'Other'),
   installHint: () => (isZh() ? '安装建议' : 'Install'),
+  // ── startup-roster issues (issue #144) ─────────────────────────────────
+  startupIssues: () => (isZh() ? '启动区问题' : 'Startup roster issues'),
+  startupIssueFix: () => (isZh() ? '修复' : 'Fix'),
+  startupIssueRemove: () => (isZh() ? '移除' : 'Remove'),
+  startupIssueUnresolvable: () => (isZh() ? '包不可解析' : 'Unresolvable'),
+  startupIssueDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  startupIssueDuplicate: () => (isZh() ? '重复 id' : 'Duplicate id'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -304,6 +338,7 @@ const EVENT_LABELS = {
   safe: () => (isZh() ? '安全模式' : 'Safe mode'),
   'safe-mode': () => (isZh() ? '安全模式' : 'Safe mode'),
   skip: () => (isZh() ? '跳过' : 'Skipped'),
+  'startup-issue': () => (isZh() ? '启动区问题' : 'Startup issue'),
 }
 
 /** Badge color variant for an event type; unknown types fall back to the
@@ -316,6 +351,7 @@ function eventVariant(type) {
       return 'accent'
     case 'quarantine':
     case 'update-failed':
+    case 'startup-issue':
       return 'danger'
     case 'freeze':
     case 'safe':
@@ -326,6 +362,20 @@ function eventVariant(type) {
   }
 }
 
+/** Startup-issue badge label (issue #144): unresolvable / dependency / dup. */
+function startupIssueLabel(type) {
+  switch (type) {
+    case 'unresolvable':
+      return strings.startupIssueUnresolvable()
+    case 'dependency':
+      return strings.startupIssueDependency()
+    case 'duplicate-id':
+      return strings.startupIssueDuplicate()
+    default:
+      return type
+  }
+}
+
 function eventLabel(type) {
   return (EVENT_LABELS[type] ?? (() => type))()
 }
@@ -1007,6 +1057,62 @@ function EventList({ events }) {
   )
 }
 
+/** 启动区问题（issue #144）：启动名册静态预检发现的问题条目，置顶展示
+ *  修复命令与移除提示——名册中的坏条目是 all-or-nothing 启动失败的源头。 */
+function StartupIssuesBlock({ issues, checkedAt }) {
+  if (!Array.isArray(issues) || issues.length === 0) return null
+  return createElement(
+    'div',
+    { className: 'dsh-my-guardian-startup-issues' },
+    createElement(
+      'div',
+      { className: 'dsh-my-guardian-startup-issues-title' },
+      icon.alert(14),
+      strings.startupIssues(),
+      createElement('span', { className: 'dsh-my-guardian-startup-issues-count' }, String(issues.length)),
+      typeof checkedAt === 'number' && Number.isFinite(checkedAt)
+        ? createElement('span', { className: 'dsh-my-guardian-startup-issues-time' }, formatTime(checkedAt))
+        : null,
+    ),
+    issues.map((issue, index) =>
+      createElement(
+        'div',
+        { className: 'dsh-my-guardian-startup-issue', key: index },
+        createElement(
+          'div',
+          { className: 'dsh-my-guardian-startup-issue-head' },
+          createElement(
+            'span',
+            {
+              className: `dsh-my-guardian-event-badge dsh-my-guardian-startup-issue-badge-${issue.type}`,
+              title: issue.entryId,
+            },
+            startupIssueLabel(issue.type),
+          ),
+          createElement('span', { className: 'dsh-my-guardian-startup-issue-name' }, issue.name),
+        ),
+        createElement('div', { className: 'dsh-my-guardian-startup-issue-message' }, issue.message),
+        typeof issue.fix === 'string' && issue.fix !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueFix()),
+              createElement('code', null, issue.fix),
+            )
+          : null,
+        typeof issue.remove === 'string' && issue.remove !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueRemove()),
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-remove' }, issue.remove),
+            )
+          : null,
+      ),
+    ),
+  )
+}
+
 function GuardianView({ visible }) {
   const { state, loadFailed, reload, onAction, onSafeMode } = useGuardianState(visible)
 
@@ -1028,6 +1134,10 @@ function GuardianView({ visible }) {
     'div',
     { className: 'dsh-my-guardian-root' },
     createElement(SafeModeBar, { safeMode: state.safeMode, onSafeMode }),
+    createElement(StartupIssuesBlock, {
+      issues: state.startupIssues,
+      checkedAt: state.startupCheckedAt,
+    }),
     loadFailed
       ? createElement(
           'div',

package/lib/dep-precheck.js

@@ -14,7 +14,9 @@ import { satisfies } from './dep-version.js'
 
 // Locate a package directory below a node_modules root, following symlinks
 // (pnpm store / npm link both expose package.json through the mirrored dir).
-function findModuleDir(nmRoot, packageName) {
+// Exported for the startup-roster pre-check (issue #144): resolvability of a
+// roster plugin's own package is verified before peer dependencies.
+export function findModuleDir(nmRoot, packageName) {
   const dir = join(nmRoot, packageName)
   return existsSync(join(dir, 'package.json')) ? dir : null
 }

package/lib/index.js

@@ -37,6 +37,7 @@ import { createPersister, createState } from './state.js'
 import { findRootTree, createMountOps, initialScan } from './mount.js'
 import { createApi } from './api.js'
 import { attachEventListeners, logEvent } from './events.js'
+import { runStartupCheck } from './startup-check.js'
 
 export const name = 'dsh-my-guardian'
 
@@ -69,6 +70,7 @@ function applyInner(ctx) {
   scheduleInitialScan(ctx, shared)
   startWatchers(ctx, shared)
   registerTeardown(ctx, shared)
+  registerStatusQuery(ctx, shared)
 }
 
 /** Mutable per-instance runtime context shared by every sub-module. */
@@ -84,6 +86,9 @@ function createShared({ tree, profileDir }) {
     tree,
     profileDir,
     stagedFile: join(profileDir, 'cordis.staged.json'),
+    // startup-roster pre-check (issue #144): filled by runStartupCheck
+    startupIssues: [],
+    startupCheckedAt: null,
   }
 }
 
@@ -99,7 +104,14 @@ function wireServices(ctx, shared) {
 // ── run after boot settles ──────────────────────────────────────────────
 function scheduleInitialScan(ctx, shared) {
   void Promise.resolve().then(() => {
-    initialScan(shared).catch((error) => {
+    // Startup-roster static pre-check (issue #144): best-effort, MUST never
+    // block or break the boot — a pre-check failure only records a report.
+    void runStartupCheck(ctx, shared).catch((error) => {
+      ctx.logger?.warn(
+        `[dsh-my-guardian] startup pre-check failed (recorded only): ${error instanceof Error ? error.message : String(error)}`,
+      )
+    })
+    void initialScan(shared).catch((error) => {
       // the scan must never take the process down
       ctx.logger?.warn(
         `[dsh-my-guardian] initial scan failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -126,6 +138,28 @@ function startWatchers(ctx, shared) {
   }, POLL_MS)
 }
 
+/** 插件状态查询（#155 聚合层）：返回 guardian 加载状态 + 最近事件。 */
+function registerStatusQuery(ctx, shared) {
+  ctx.on('plugin:status-query', ({ plugin }) => {
+    if (plugin !== 'dsh-my-guardian') return undefined
+    const lastActions = (shared.state.events ?? []).slice(-5).map((e) => ({
+      time: e.time ?? e.timestamp ?? Date.now(),
+      type: e.type ?? 'event',
+      detail: e.message ?? e.detail ?? '',
+    }))
+    return {
+      ok: true,
+      value: {
+        plugin: 'dsh-my-guardian',
+        config: { keys: ['safeMode', 'stagedFile'] },
+        running: shared.ready,
+        stats: { mounted: shared.mounted.size, safeMode: shared.state.safeMode === true },
+        lastActions,
+      },
+    }
+  })
+}
+
 /** teardown: unmount everything the guardian mounted, then persist. */
 function registerTeardown(ctx, shared) {
   ctx.effect(

package/lib/parts/styles.part.js

@@ -148,6 +148,33 @@ const STYLES = `
 .dsh-my-guardian-event-message { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
   font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); }
 .dsh-my-guardian-event-time { flex:none; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); white-space:nowrap; }
+/* ── startup-roster issues (issue #144): pinned block above the list ────── */
+.dsh-my-guardian-startup-issues { display:flex; flex-direction:column; gap:2px; margin-top:4px; padding:6px 8px; border-radius:8px;
+  border:1px solid color-mix(in srgb, var(--dsw-alias-state-error-primary) 45%, transparent);
+  background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 6%, transparent);
+  animation:dsh-my-guardian-row-in 150ms var(--ds-ease-in-out); }
+.dsh-my-guardian-startup-issues-title { display:flex; align-items:center; gap:5px; padding:0 2px 3px;
+  font:var(--dsw-font-xxs-strong-12); color:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-title svg { display:block; flex:none; }
+.dsh-my-guardian-startup-issues-count { display:inline-flex; align-items:center; justify-content:center; min-width:17px; height:17px; padding:0 5px; border-radius:4px;
+  font:var(--dsw-font-xxxs-strong-11); color:var(--dsw-alias-label-primary-foreground); background:var(--dsw-alias-state-error-primary); }
+.dsh-my-guardian-startup-issues-time { flex:1; text-align:right; font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue { display:flex; flex-direction:column; gap:2px; padding:5px 6px; border-radius:6px;
+  border:1px solid var(--dsw-alias-border-l1); background:transparent; }
+.dsh-my-guardian-startup-issue:hover { background:var(--dsw-alias-interactive-bg-hover); }
+.dsh-my-guardian-startup-issue-head { display:flex; align-items:center; gap:6px; min-width:0; }
+.dsh-my-guardian-startup-issue-name { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap;
+  font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dsh-my-guardian-startup-issue-badge-unresolvable { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-duplicate-id { color:var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 14%, transparent); }
+.dsh-my-guardian-startup-issue-badge-dependency { color:var(--dsw-alias-state-warn-primary); background:color-mix(in srgb, var(--dsw-alias-state-warn-primary) 16%, transparent); }
+.dsh-my-guardian-startup-issue-message { font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-secondary); line-height:1.6; }
+.dsh-my-guardian-startup-issue-line { display:flex; align-items:flex-start; gap:5px; padding:2px 0;
+  font:var(--dsw-font-xxxs-11); color:var(--dsw-alias-label-tertiary); line-height:1.6; min-width:0; }
+.dsh-my-guardian-startup-issue-label { flex:none; color:var(--dsw-alias-label-tertiary); }
+.dsh-my-guardian-startup-issue-line code { font-family:ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size:var(--dsw-font-xxxs-11);
+  color:var(--dsw-alias-state-success-primary); word-break:break-all; }
+.dsh-my-guardian-startup-issue-remove { min-width:0; word-break:break-all; }
 @keyframes dsh-my-guardian-row-in { from { opacity:0; transform:translateY(1px); } to { opacity:1; transform:none; } }
 @keyframes dsh-my-guardian-spin { to { transform:rotate(360deg); } }
 `

package/lib/parts/util.part.js

@@ -49,6 +49,13 @@ const strings = {
   failureCode: () => (isZh() ? '代码错误' : 'Code error'),
   failureOther: () => (isZh() ? '其他' : 'Other'),
   installHint: () => (isZh() ? '安装建议' : 'Install'),
+  // ── startup-roster issues (issue #144) ─────────────────────────────────
+  startupIssues: () => (isZh() ? '启动区问题' : 'Startup roster issues'),
+  startupIssueFix: () => (isZh() ? '修复' : 'Fix'),
+  startupIssueRemove: () => (isZh() ? '移除' : 'Remove'),
+  startupIssueUnresolvable: () => (isZh() ? '包不可解析' : 'Unresolvable'),
+  startupIssueDependency: () => (isZh() ? '依赖缺失' : 'Dependency'),
+  startupIssueDuplicate: () => (isZh() ? '重复 id' : 'Duplicate id'),
 }
 
 // ── api ───────────────────────────────────────────────────────────────
@@ -116,6 +123,7 @@ const EVENT_LABELS = {
   safe: () => (isZh() ? '安全模式' : 'Safe mode'),
   'safe-mode': () => (isZh() ? '安全模式' : 'Safe mode'),
   skip: () => (isZh() ? '跳过' : 'Skipped'),
+  'startup-issue': () => (isZh() ? '启动区问题' : 'Startup issue'),
 }
 
 /** Badge color variant for an event type; unknown types fall back to the
@@ -128,6 +136,7 @@ function eventVariant(type) {
       return 'accent'
     case 'quarantine':
     case 'update-failed':
+    case 'startup-issue':
       return 'danger'
     case 'freeze':
     case 'safe':
@@ -138,6 +147,20 @@ function eventVariant(type) {
   }
 }
 
+/** Startup-issue badge label (issue #144): unresolvable / dependency / dup. */
+function startupIssueLabel(type) {
+  switch (type) {
+    case 'unresolvable':
+      return strings.startupIssueUnresolvable()
+    case 'dependency':
+      return strings.startupIssueDependency()
+    case 'duplicate-id':
+      return strings.startupIssueDuplicate()
+    default:
+      return type
+  }
+}
+
 function eventLabel(type) {
   return (EVENT_LABELS[type] ?? (() => type))()
 }

package/lib/parts/view.part.js

@@ -155,6 +155,62 @@ function EventList({ events }) {
   )
 }
 
+/** 启动区问题（issue #144）：启动名册静态预检发现的问题条目，置顶展示
+ *  修复命令与移除提示——名册中的坏条目是 all-or-nothing 启动失败的源头。 */
+function StartupIssuesBlock({ issues, checkedAt }) {
+  if (!Array.isArray(issues) || issues.length === 0) return null
+  return createElement(
+    'div',
+    { className: 'dsh-my-guardian-startup-issues' },
+    createElement(
+      'div',
+      { className: 'dsh-my-guardian-startup-issues-title' },
+      icon.alert(14),
+      strings.startupIssues(),
+      createElement('span', { className: 'dsh-my-guardian-startup-issues-count' }, String(issues.length)),
+      typeof checkedAt === 'number' && Number.isFinite(checkedAt)
+        ? createElement('span', { className: 'dsh-my-guardian-startup-issues-time' }, formatTime(checkedAt))
+        : null,
+    ),
+    issues.map((issue, index) =>
+      createElement(
+        'div',
+        { className: 'dsh-my-guardian-startup-issue', key: index },
+        createElement(
+          'div',
+          { className: 'dsh-my-guardian-startup-issue-head' },
+          createElement(
+            'span',
+            {
+              className: `dsh-my-guardian-event-badge dsh-my-guardian-startup-issue-badge-${issue.type}`,
+              title: issue.entryId,
+            },
+            startupIssueLabel(issue.type),
+          ),
+          createElement('span', { className: 'dsh-my-guardian-startup-issue-name' }, issue.name),
+        ),
+        createElement('div', { className: 'dsh-my-guardian-startup-issue-message' }, issue.message),
+        typeof issue.fix === 'string' && issue.fix !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueFix()),
+              createElement('code', null, issue.fix),
+            )
+          : null,
+        typeof issue.remove === 'string' && issue.remove !== ''
+          ? createElement(
+              'div',
+              { className: 'dsh-my-guardian-startup-issue-line' },
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-label' }, strings.startupIssueRemove()),
+              createElement('span', { className: 'dsh-my-guardian-startup-issue-remove' }, issue.remove),
+            )
+          : null,
+      ),
+    ),
+  )
+}
+
 function GuardianView({ visible }) {
   const { state, loadFailed, reload, onAction, onSafeMode } = useGuardianState(visible)
 
@@ -176,6 +232,10 @@ function GuardianView({ visible }) {
     'div',
     { className: 'dsh-my-guardian-root' },
     createElement(SafeModeBar, { safeMode: state.safeMode, onSafeMode }),
+    createElement(StartupIssuesBlock, {
+      issues: state.startupIssues,
+      checkedAt: state.startupCheckedAt,
+    }),
     loadFailed
       ? createElement(
           'div',

package/lib/startup-check.js

@@ -0,0 +1,228 @@
+/**
+ * dsh-my-guardian — startup-roster static pre-check (issue #144).
+ *
+ * DSH boots its plugin roster all-or-nothing: any roster row (cordis.patch.yml /
+ * profile / bundles — everything merged into the loader's include tree) that
+ * fails to import, throws during apply, or stays pending takes the whole
+ * `dsh web` process down, and the guardian (itself a roster row) has no
+ * chance to quarantine anything after the fact. This module closes that gap
+ * with a STATIC, best-effort pre-flight that runs right after the guardian's
+ * own apply:
+ *
+ *   - package resolvability: every dsh-* roster entry's package must exist
+ *     under the profile node_modules — an unresolvable package always fails
+ *     the import stage (assertEntriesLoaded throws in dsh-app-boot)
+ *   - peer dependencies: reuse the staged-mount pre-check (dep-precheck.js)
+ *     — missing/out-of-range peers surface at boot as module-resolution
+ *     failures, so they are flagged before the next restart hits them
+ *   - duplicate entry ids: EntryGroup.update in cordis-plugin-loader throws
+ *     "duplicate loader entry id" when a group config lists the same id
+ *     twice — a guaranteed boot failure worth flagging up front
+ *
+ * The report is written to $DSH_HOME/guardian/startup-issues.json so it
+ * survives a broken boot: applies run in parallel with roster imports, so the
+ * guardian can usually record the report before assertEntriesActivated
+ * rejects the boot.
+ *
+ * Guardrails (watchdog self-protection, R15): the pre-check itself NEVER
+ * fails the boot — every step is wrapped, failures only log; a broken loader
+ * tree simply yields no roster and an empty report.
+ */
+import { join } from 'node:path'
+import { findModuleDir, checkPeerDependencies, buildDependencyMessage } from './dep-precheck.js'
+import { writeStartupIssuesFile } from './state.js'
+import { logEvent } from './events.js'
+
+/** Profile-node_modules root used for roster resolvability checks. */
+function profileNodeModules(profileDir) {
+  return join(profileDir, 'node_modules')
+}
+
+/** Collect every entry of a tree, tolerantly: entries() when present (real
+ *  IncludeTree includes nested subtrees), otherwise a plain store walk
+ *  (mocked trees in tests). Never throws — a broken tree yields []. */
+export function collectTreeEntries(tree) {
+  if (tree === null || typeof tree !== 'object') return []
+  if (typeof tree.entries === 'function') {
+    try {
+      const out = []
+      for (const entry of tree.entries()) {
+        if (entry !== null && typeof entry === 'object') out.push(entry)
+      }
+      return out
+    } catch {
+      // fall through to the store walk
+    }
+  }
+  const store = tree.store
+  if (store === null || typeof store !== 'object') return []
+  return Object.values(store).filter((entry) => entry !== null && typeof entry === 'object')
+}
+
+/** Read one string field from an entry's options (tolerant of odd shapes). */
+function readOptionString(options, key) {
+  return options !== null && typeof options === 'object' && typeof options[key] === 'string' && options[key] !== ''
+    ? options[key]
+    : ''
+}
+
+/** Extract { id, name } from an entry, with safe fallbacks (entry.id getter
+ *  may throw on partially-constructed entries — never let it break the boot). */
+export function entryLabels(entry) {
+  const options = entry !== null && typeof entry === 'object' ? entry.options : null
+  let id = readOptionString(options, 'id')
+  if (id === '') id = entryIdGetterOf(entry)
+  const name = readOptionString(options, 'name')
+  return { id, name: name !== '' ? name : id !== '' ? id : '?' }
+}
+
+/** entry.id getter fallback (wrapped: it may throw on partial entries). */
+function entryIdGetterOf(entry) {
+  try {
+    const entryId = entry?.id
+    return typeof entryId === 'string' && entryId !== '' ? entryId : ''
+  } catch {
+    return ''
+  }
+}
+
+/** True when an entry is disabled (explicit row or via options) — disabled
+ *  rows are exempt from the boot audits and from this pre-check. */
+export function isDisabledEntry(entry) {
+  if (entry === null || typeof entry !== 'object') return false
+  if (entry.disabled === true) return true
+  const options = entry.options
+  return options !== null && typeof options === 'object' && options.disabled === true
+}
+
+/** Removal hint shared by every issue kind (guardian never rewrites YAML). */
+const REMOVE_HINT = '从启动名册（cordis.patch.yml / profile）中删除该条目行，或标记 disabled: true 暂缓加载'
+
+/** Build an unresolvable-package issue (import stage would fail). */
+function unresolvedIssue(id, name) {
+  return {
+    type: 'unresolvable',
+    entryId: id,
+    name,
+    message: `插件包 ${name} 无法解析（profile node_modules 中不存在），启动 import 将失败`,
+    fix: `dsh plugin add ${name}`,
+    remove: REMOVE_HINT,
+  }
+}
+
+/** Build a dependency issue reusing the staged-mount pre-check result. */
+function dependencyIssue(id, name, precheck) {
+  return {
+    type: 'dependency',
+    entryId: id,
+    name,
+    message: buildDependencyMessage(precheck),
+    missingDeps: [...precheck.missing, ...precheck.mismatched.map((item) => item.name)],
+    installHint: precheck.suggestions[0] ?? null,
+    fix: precheck.suggestions[0] ?? `dsh plugin add ${name}`,
+    remove: REMOVE_HINT,
+  }
+}
+
+/** Build a duplicate-id issue for one id seen more than once. */
+function duplicateIssue(id, names) {
+  return {
+    type: 'duplicate-id',
+    entryId: id,
+    name: names[0] ?? id,
+    message: `名册存在重复条目 id "${id}"（${names.length} 处：${names.join('、')}），加载时将抛 duplicate loader entry id`,
+    fix: null,
+    remove: '从名册中删除重复的条目行（每个 id 保留一条）',
+  }
+}
+
+/** Record an entry under its id for the duplicate-id sweep. */
+function addSeen(map, id, item) {
+  const group = map.get(id)
+  if (group === undefined) map.set(id, [item])
+  else group.push(item)
+}
+
+/** Static checks for one roster row: resolvability + peers (dsh-* only). */
+function checkPluginItem(issues, item, nmRoot, profileDir) {
+  const id = typeof item.id === 'string' ? item.id : ''
+  const name = typeof item.name === 'string' ? item.name : ''
+  const label = name !== '' ? name : id
+  if (label === '' || !label.startsWith('dsh-')) return
+  const pluginDir = findModuleDir(nmRoot, label)
+  if (pluginDir === null) {
+    issues.push(unresolvedIssue(id, label))
+    return
+  }
+  const precheck = checkPeerDependencies({ profileDir, pluginName: label })
+  if (!precheck.ok) issues.push(dependencyIssue(id, label, precheck))
+}
+
+/** Append one duplicate-id issue per id seen in more than one roster row. */
+function collectDuplicateIssues(issues, byId) {
+  for (const [id, group] of byId) {
+    if (group.length < 2) continue
+    issues.push(
+      duplicateIssue(
+        id,
+        group.map((item) => item.name ?? item.id ?? '?'),
+      ),
+    )
+  }
+}
+
+/**
+ * Core static pre-check over one roster's normalized entries.
+ * entries: [{ id, name, disabled }] (see normalizeRoster). Checks dsh-*
+ * plugins for package resolvability + peer deps, and the whole roster for
+ * duplicate ids. Never throws — returns { issues }.
+ */
+export function checkStartupRoster({ entries, profileDir }) {
+  const issues = []
+  const roster = Array.isArray(entries) ? entries : []
+  const nmRoot = profileNodeModules(profileDir)
+  const byId = new Map()
+  for (const item of roster) {
+    if (item === null || typeof item !== 'object') continue
+    const id = typeof item.id === 'string' ? item.id : ''
+    if (id !== '') addSeen(byId, id, item)
+    checkPluginItem(issues, item, nmRoot, profileDir)
+  }
+  collectDuplicateIssues(issues, byId)
+  return { issues }
+}
+
+/** Normalize raw tree entries into { id, name, disabled } roster rows. */
+export function normalizeRoster(entries) {
+  return entries.map((entry) => {
+    const labels = entryLabels(entry)
+    return { id: labels.id, name: labels.name, disabled: isDisabledEntry(entry) }
+  })
+}
+
+/**
+ * Full startup pre-flight for one guardian instance: collect the roster from
+ * the include tree, statically check it, persist the report and log an event.
+ * Never throws — every failure degrades to a warn log (boot must continue).
+ */
+export async function runStartupCheck(ctx, shared) {
+  const entries = collectTreeEntries(shared.tree)
+  const roster = normalizeRoster(entries).filter((item) => !item.disabled)
+  const { issues } = checkStartupRoster({ entries: roster, profileDir: shared.profileDir })
+  const checkedAt = Date.now()
+  await writeStartupIssuesFile({ version: 1, checkedAt, profileDir: shared.profileDir, issues })
+  shared.startupIssues = issues
+  shared.startupCheckedAt = checkedAt
+  if (issues.length > 0) {
+    const names = [...new Set(issues.map((issue) => issue.name))].slice(0, 3).join('、')
+    logEvent(
+      shared,
+      'startup-issue',
+      `启动名册静态预检发现 ${issues.length} 个问题（${names}…）— 详见 guardian/startup-issues.json`,
+    )
+    shared.persistSoon()
+    ctx.logger?.warn(
+      `[dsh-my-guardian] startup roster pre-check: ${issues.length} issue(s) — see $DSH_HOME/guardian/startup-issues.json`,
+    )
+  }
+}

package/lib/state.js

@@ -32,6 +32,26 @@ function guardianDir() {
   return join(homedir(), '.dsh', 'guardian')
 }
 
+/**
+ * Persist the startup-roster pre-check report (issue #144) atomically at
+ * $DSH_HOME/guardian/startup-issues.json. The report is written even when
+ * the roster is healthy (empty issues + checkedAt) so the file doubles as a
+ * "last checked" marker; missing/corrupt file only means "never written".
+ * Never throws to callers — the guardian must not take the process down.
+ */
+export async function writeStartupIssuesFile(payload) {
+  const dir = guardianDir()
+  const file = join(dir, 'startup-issues.json')
+  const tmp = `${file}.tmp-${uniqueSuffix()}`
+  try {
+    await mkdir(dir, { recursive: true })
+    await writeFile(tmp, JSON.stringify(payload), 'utf8')
+    await rename(tmp, file)
+  } catch {
+    // the report is diagnostic-only: a write failure must not break boot
+  }
+}
+
 /** Empty state document. */
 export function createState() {
   return { version: 1, safeMode: false, staged: {}, promoted: {}, events: [] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-my-guardian",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "description": "DSH 插件治理守护：新装/更新插件先进候选区，启动后热挂载——成功转正、失败自动禁用、连续失败冻结，一键安全模式，侧边栏诊断面板。DSH web plugin: staged plugin loading with auto-disable on failure, freeze, safe mode and a sidebar panel.",
   "type": "module",
   "main": "lib/index.js",
@@ -36,10 +36,7 @@
       "patch": "./cordis.patch.yml"
     },
     "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime"
-      ]
+      "platform": "web"
     }
   },
   "peerDependencies": {