@twinsearth/fang-dsh-plugin 0.0.0-stage → 3.3.4

package/src/plugins/umbrella.mjs

@@ -0,0 +1,419 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+// dsh-Fang v2.7.6 fang-umbrella — 「保护伞」：一个证据管道，两个评分出口。
+//
+//   ├─ 插件评分：A/B/C/D/E（交给 fang-scorer 的 import 层扫描，按入口 mtime 缓存）
+//   └─ 动作评分：green/blue/yellow/red（每次动作重算）+ 等级下限抬高
+//
+// 这个插件自己**不扫源码**：静态证据的唯一来源是 `SERVICE.scorer`，缺它就失败往坏里判
+// （E + degraded），绝不假装安全。纯逻辑在 `src/lib/umbrella.mjs`，契约见 docs/UMBRELLA.md。
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { AUDIT, SERVICE, roleGate, z } from '../kernel/index.mjs'
+import {
+  DEFAULT_ACTION_RULES,
+  DEFAULT_FLOOR_TABLE,
+  DECISION,
+  GRADE_FLOOR,
+  GRADE_FLOOR_STRICT,
+  LIGHT,
+  SEVERITY,
+  createUmbrella,
+  normalizeGrade,
+  normalizeLight,
+} from '../lib/umbrella.mjs'
+import {
+  createRuleRegistry,
+  isLockedRule,
+  loadRuleConfigFile,
+  watchRuleConfigFiles,
+} from '../lib/rule-registry.mjs'
+
+export const name = 'fang-umbrella'
+export const inject = []
+
+export const Config = z.object({
+  bufferRoot: z.string().default('')
+    .description('沙箱缓冲区根目录（空 = 取 buffer-keeper 的实时 dir）'),
+  productionRoot: z.string().default('')
+    .description('生产区根目录；越界写命中它时单列为 write-production（仍是黄灯）'),
+  allowPaths: z.array(z.string()).default([])
+    .description('允许写入的路径前缀（相对路径按本实例 cwd 解析）'),
+  networkAllowlist: z.array(z.string()).default([])
+    .description('外连允许列表：host、host:port、*.suffix 或 URL 前缀'),
+  credentialPatterns: z.array(z.string()).default([])
+    .description('凭据路径正则（空 = 内置默认；传非空数组 = 完全替换）'),
+  destructivePatterns: z.array(z.string()).default([])
+    .description('破坏性命令正则（空 = 内置默认；传非空数组 = 完全替换）'),
+  lifecyclePatterns: z.array(z.string()).default([])
+    .description('DSH 生命周期命令正则（空 = 内置默认）'),
+  lifecycleTools: z.array(z.string()).default([])
+    .description('视为生命周期的工具名（空 = 内置默认）'),
+  gradeFloorTable: z.string().default(DEFAULT_FLOOR_TABLE)
+    .description('动作灯色下限表：umbrella（默认）| strict（与 GRADE_COLOR 对齐）；未知值回退 umbrella 并标记 degraded'),
+  cacheSize: z.natural().default(200)
+    .description('插件评分缓存容量（LRU，按入口文件 mtime 失效）'),
+  auditDecisions: z.boolean().default(true)
+    .description('每次 decideAction 落一条 umbrella-decision 审计'),
+  baselineFile: z.string().default('')
+    .description('推荐基线配置路径（空 = 随包 defaults/umbrella-rules.yaml；":none:" = 不加载基线）'),
+  envRulesFile: z.string().default('')
+    .description('环境级规则配置路径（空 = 读 UMBRELLA_RULES_PATH；CI/部署注入用）'),
+  rulesFile: z.string().default('')
+    .description('YAML 规则配置文件路径（空 = 只用内置规则；相对路径按本实例 cwd 解析）'),
+  rulesWatch: z.boolean().default(true)
+    .description('监听 rulesFile 变化并热加载（失败保留上一次有效规则）'),
+  rulesDebounceMs: z.natural().default(200)
+    .description('热加载防抖窗口（毫秒）'),
+})
+
+function safeGet(ctx, key) {
+  try { return ctx?.get?.(key) } catch { return undefined }
+}
+
+/** 空数组 = 用内置默认；非空数组 = 调用方完全接管。 */
+function patternsOrUndefined(value) {
+  return Array.isArray(value) && value.length > 0 ? value.map(String) : undefined
+}
+
+export function apply(ctx, config) {
+  const gate = roleGate('umbrella', { cfgRole: config?.role, logger: ctx.logger })
+  if (!gate.active) return
+
+  const cfg = Config(config ?? {})
+
+  /** 评分服务按需取：loader 行序不保证 scorer 先于 umbrella 完成注册。 */
+  const scorerAdapter = () => ({
+    scoreSource(source, pkg, opts) {
+      const scorer = safeGet(ctx, SERVICE.scorer)
+      if (typeof scorer?.scoreSource !== 'function') return unavailable()
+      return scorer.scoreSource(source, pkg, opts)
+    },
+    scoreDir(dir, manifest, opts) {
+      const scorer = safeGet(ctx, SERVICE.scorer)
+      if (typeof scorer?.scoreDir !== 'function') return unavailable()
+      return scorer.scoreDir(dir, manifest, opts)
+    },
+  })
+
+  /** buffer root 的实时来源：config → buffer-keeper.dir → buffer-keeper.config.root。 */
+  const policyNow = () => {
+    const configuredBuffer = String(cfg.bufferRoot ?? '').trim()
+    const buffer = safeGet(ctx, SERVICE.buffer)
+    const liveBuffer = typeof buffer?.dir === 'string' ? buffer.dir : ''
+    const configBuffer = typeof buffer?.config?.root === 'string' ? buffer.config.root : ''
+    return {
+      bufferRoot: configuredBuffer || liveBuffer || configBuffer,
+      productionRoot: String(cfg.productionRoot ?? '').trim(),
+      allowPaths: cfg.allowPaths,
+      networkAllowlist: cfg.networkAllowlist,
+      credentialPatterns: patternsOrUndefined(cfg.credentialPatterns),
+      destructivePatterns: patternsOrUndefined(cfg.destructivePatterns),
+      lifecyclePatterns: patternsOrUndefined(cfg.lifecyclePatterns),
+      lifecycleTools: Array.isArray(cfg.lifecycleTools) && cfg.lifecycleTools.length > 0
+        ? cfg.lifecycleTools.map(String)
+        : undefined,
+    }
+  }
+
+  // ── 规则配置层（分三层叠加）：包内基线 → 项目级 rulesFile → 环境级 UMBRELLA_RULES_PATH ──
+  // fail-safe：任一层的加载/应用失败都不影响已生效的层；事务化由 registry 负责。
+  const ruleRegistry = createRuleRegistry(DEFAULT_ACTION_RULES)
+  const baselinePath = (() => {
+    const configured = String(cfg.baselineFile ?? '').trim()
+    if (configured === ':none:') return ''
+    if (configured.length > 0) return path.resolve(configured)
+    try {
+      return fileURLToPath(new URL('../../defaults/umbrella-rules.yaml', import.meta.url))
+    } catch {
+      return ''
+    }
+  })()
+  const projectPath = String(cfg.rulesFile ?? '').trim()
+  const projectFilePath = projectPath.length > 0 ? path.resolve(projectPath) : ''
+  const envPath = String(cfg.envRulesFile ?? '').trim() || String(process.env.UMBRELLA_RULES_PATH ?? '').trim()
+  const envFilePath = envPath.length > 0 ? path.resolve(envPath) : ''
+
+  let ruleConfigStatus = {
+    source: 'builtin',
+    layers: [],
+    ruleCount: ruleRegistry.ids().length,
+    applied: false,
+    warnings: [],
+    errors: [],
+    appliedAt: null,
+    strictMode: null,
+  }
+  let lastStrictStamp = null
+
+  const layerCandidates = [
+    { name: 'baseline', file: baselinePath },
+    { name: 'project', file: projectFilePath },
+    { name: 'env', file: envFilePath },
+  ].filter((layer) => layer.file.length > 0)
+
+  const applyAllLayers = () => {
+    ruleRegistry.clearLayers()
+    const layerStatus = []
+    const warnings = []
+    const errors = []
+    for (const layer of layerCandidates) {
+      const loaded = loadRuleConfigFile(layer.file)
+      if (loaded.errors.length > 0) {
+        layerStatus.push({ name: layer.name, file: layer.file, applied: false, found: loaded.found, errors: loaded.errors })
+        errors.push(...loaded.errors.map((e) => `${layer.name}: ${e}`))
+        try { ctx.logger?.warn?.(`[umbrella] ${layer.name} rule config skipped: ${loaded.errors.join('; ')}`) } catch { /* ignore */ }
+        continue
+      }
+      if (loaded.config === null) {
+        layerStatus.push({ name: layer.name, file: layer.file, applied: false, found: loaded.found, errors: [] })
+        continue
+      }
+      const applied = ruleRegistry.applyLayer(loaded.config)
+      layerStatus.push({
+        name: layer.name,
+        file: layer.file,
+        applied: applied.applied,
+        found: true,
+        ruleCount: applied.ruleCount,
+        warnings: applied.warnings,
+        errors: applied.errors,
+        revertedToLayerIndex: applied.revertedToLayerIndex ?? null,
+      })
+      warnings.push(...applied.warnings)
+      errors.push(...applied.errors)
+      if (!applied.applied) {
+        try { ctx.logger?.warn?.(`[umbrella] ${layer.name} rule config rejected, keeping previous rules: ${applied.errors.join('; ')}`) } catch { /* ignore */ }
+      }
+    }
+    const registryStatus = ruleRegistry.status()
+    ruleConfigStatus = {
+      source: registryStatus.source,
+      layers: layerStatus,
+      ruleCount: ruleRegistry.ids().length,
+      applied: layerStatus.some((layer) => layer.applied === true),
+      warnings,
+      errors,
+      appliedAt: Date.now(),
+      strictMode: registryStatus.strictMode ?? null,
+    }
+    // 严格模式是重大配置行为：首次激活（或层/丢弃数变化）时落一条审计
+    const strict = ruleConfigStatus.strictMode
+    const stamp = strict === null ? null : `${strict.layerIndex}:${strict.discardedRuleCount}:${strict.preservedHardRules.join(',')}`
+    if (stamp !== null && stamp !== lastStrictStamp) {
+      lastStrictStamp = stamp
+      try {
+        safeGet(ctx, SERVICE.auditor)?.append?.(AUDIT.UMBRELLA_STRICT_MODE, {
+          component: name,
+          at: strict.activatedAt,
+          layerIndex: strict.layerIndex,
+          preservedHardRules: strict.preservedHardRules,
+          preservedFallback: strict.preservedFallback ?? [],
+          discardedRuleCount: strict.discardedRuleCount,
+          layers: ruleConfigStatus.layers.map((layer) => ({ name: layer.name, applied: layer.applied })),
+        })
+      } catch { /* 审计缺失不影响决策 */ }
+      try {
+        ctx.logger?.info?.(`[umbrella] strict mode (inherit:false) active at layer ${strict.layerIndex}: preserved ${strict.preservedHardRules.length} hard rules, discarded ${strict.discardedRuleCount} adjustable rules`)
+      } catch { /* logger 可选 */ }
+    } else if (stamp === null) {
+      lastStrictStamp = null
+    }
+    return ruleConfigStatus
+  }
+
+  applyAllLayers()
+
+  let ruleWatcher = null
+  const reloadRules = () => applyAllLayers()
+
+  const watchedFiles = layerCandidates.map((layer) => layer.file)
+  if (watchedFiles.length > 0 && cfg.rulesWatch) {
+    ruleWatcher = watchRuleConfigFiles(watchedFiles, () => {
+      // Re-read every layer, not just the file that changed: later layers override
+      // earlier ones by id, so a single-layer applyConfig would discard the stack.
+      applyAllLayers()
+    }, { debounceMs: cfg.rulesDebounceMs, logger: ctx.logger })
+    ctx.effect(() => () => { try { ruleWatcher?.stop?.() } catch { /* ignore */ } })
+  }
+
+  const umbrella = createUmbrella({
+    scorer: scorerAdapter(),
+    policy: policyNow,
+    floorTable: cfg.gradeFloorTable,
+    cacheSize: cfg.cacheSize,
+    registry: ruleRegistry,
+    decisionCenter: () => safeGet(ctx, SERVICE.decisionCenter),
+    audit(record) {
+      if (!cfg.auditDecisions) return { ok: true, skipped: true }
+      const auditor = safeGet(ctx, SERVICE.auditor)
+      if (!auditor || typeof auditor.append !== 'function') return { ok: false, reason: 'auditor-unavailable' }
+      try {
+        auditor.append(AUDIT.UMBRELLA_DECISION, record)
+        return { ok: true }
+      } catch (error) {
+        return { ok: false, reason: 'audit-failed', error: String(error?.message ?? error) }
+      }
+    },
+  })
+
+  if (umbrella.floorDegraded) {
+    try {
+      ctx.logger?.warn?.(`[umbrella] unknown gradeFloorTable=${JSON.stringify(cfg.gradeFloorTable)}; fell back to "${DEFAULT_FLOOR_TABLE}"`)
+    } catch { /* logger 可选 */ }
+  }
+
+  const service = {
+    /** 本实例部署环境（mother | fork）——插件评分按它选阈值。 */
+    environment: gate.role,
+
+    get policy() {
+      return umbrella.policy
+    },
+
+    floorTable: umbrella.floorTable,
+    floorDegraded: umbrella.floorDegraded,
+    floors: umbrella.grades,
+
+    /** YAML 规则配置状态（来源 / 文件 / 是否应用 / 警告与错误）。 */
+    ruleConfigStatus() {
+      return { ...ruleConfigStatus, rules: ruleRegistry.ids() }
+    },
+
+    /** 立即重读 rulesFile（热加载的手动入口）。 */
+    reloadRules() {
+      return reloadRules()
+    },
+
+    /** 直接应用一份已解析的配置对象（测试/嵌入用）；失败保留旧规则。 */
+    applyRuleConfig(config) {
+      const applied = ruleRegistry.applyConfig(config)
+      ruleConfigStatus = {
+        ...ruleConfigStatus,
+        applied: applied.applied,
+        source: applied.applied ? 'yaml' : ruleConfigStatus.source,
+        ruleCount: applied.ruleCount,
+        warnings: applied.warnings,
+        errors: applied.errors,
+        appliedAt: Date.now(),
+      }
+      return applied
+    },
+
+    /** 规则注册表（只读视图 + 运行时注册/覆盖）。 */
+    get ruleRegistry() {
+      return ruleRegistry
+    },
+
+    /**
+     * 插件评分（静态）。input: { pluginId?, dir?, manifest?, source?, pkg?, version?, environment?, refresh? }
+     * 无 scorer / 扫描失败 → grade 'E' + degraded（失败往坏里判）。
+     */
+    assessPlugin(input = {}) {
+      return umbrella.assessPlugin({ environment: gate.role, ...(input ?? {}) })
+    },
+
+    /** 动作评分（动态）：基础灯色 + 等级下限，返回 light/baseLight/gradeFloor/raised。 */
+    assessAction(evidence = {}, opts = {}) {
+      return umbrella.assessAction(evidence, opts ?? {})
+    },
+
+    /** 动作评分 + 决策矩阵 + 审计。 */
+    decideAction(evidence = {}, opts = {}) {
+      return umbrella.decideAction(evidence, opts ?? {})
+    },
+
+    /** 只算基础灯色（不考虑插件等级），带 matchedRule / category / tags / 结构化证据。 */
+    baseLight(evidence = {}) {
+      return umbrella.baseLight(evidence)
+    },
+
+    /** 面向 UI/审批的解释：规则 id、类别、tags、证据（为什么是这个灯色）。 */
+    explain(evidence = {}) {
+      const base = umbrella.baseLight(evidence)
+      return {
+        light: base.light,
+        matchedRule: base.matchedRule,
+        category: base.category,
+        tags: base.tags,
+        trusted: base.trusted === true,
+        reason: base.reason,
+        evidence: base.evidence,
+        target: base.target,
+      }
+    },
+
+    /** 规则表只读视图（数组顺序即优先级）。 */
+    get rules() {
+      return umbrella.rules
+    },
+
+    ruleIds() {
+      return umbrella.ruleIds()
+    },
+
+    /** 动态注册/覆盖：形状不合法或插入位置不存在会立刻抛错，不会被静默忽略。 */
+    registerRule(rule, opts) {
+      return umbrella.registerRule(rule, opts)
+    },
+
+    overrideRule(id, patch) {
+      return umbrella.overrideRule(id, patch)
+    },
+
+    removeRule(id) {
+      return umbrella.removeRule(id)
+    },
+
+    resetRules() {
+      return umbrella.resetRules()
+    },
+
+    gradeFloor(grade) {
+      return umbrella.gradeFloor(grade)
+    },
+
+    effectiveLight(baseLightValue, grade) {
+      return umbrella.effectiveLight(baseLightValue, grade)
+    },
+
+    cachedGrade(pluginId) {
+      return umbrella.cachedGrade(pluginId)
+    },
+
+    cacheStats() {
+      return umbrella.cacheStats()
+    },
+
+    invalidate(pluginId) {
+      return umbrella.invalidate(pluginId)
+    },
+
+    clearCache() {
+      return umbrella.clearCache()
+    },
+  }
+
+  ctx.effect(() => ctx.provide(SERVICE.umbrella, service))
+  return service
+}
+
+/** 评分服务不可用时给 createUmbrella 的失败形状（guard 见 lib 的 runScorer）。 */
+function unavailable() {
+  return {
+    grade: 'E', S: 100, color: LIGHT.RED, veto: false, degraded: true,
+    signals: [], reasons: ['scorer-unavailable'], basis: null,
+  }
+}
+
+export const _internals = {
+  DECISION,
+  SEVERITY,
+  LIGHT,
+  GRADE_FLOOR,
+  GRADE_FLOOR_STRICT,
+  patternsOrUndefined,
+  normalizeGrade,
+  normalizeLight,
+  unavailable,
+}

package/tools/boot-guard.mjs

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// tools/boot-guard.mjs — DSH 启动前/发布前插件树自检。
+//
+//   node tools/boot-guard.mjs --profile-dir <profile>              # dry-run：检查行/模块/import
+//   node tools/boot-guard.mjs --profile-dir <profile> --apply      # 禁用失败行（写 profile patch + 备份）
+//   node tools/boot-guard.mjs --profile-dir <profile> --safe-mode  # 禁用全部 fang 行（安全模式）
+//
+// 只处理 fang bundle 的行；不碰 DSH 核心/其他插件；写 profile 前备份 .bak-<ts>。
+import path from 'node:path'
+
+import {
+  applyDisabledRows,
+  checkBundleRows,
+  findFangPackageDir,
+  readBundleRows,
+  readPackageName,
+  smokePackage,
+} from '../src/lib/boot-guard.mjs'
+
+function parseArgs(argv = []) {
+  const out = { profileDir: '', pkgDir: '', candidateDir: '', apply: false, safeMode: false, json: false, timeoutMs: 8000 }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--apply') { out.apply = true; continue }
+    if (arg === '--safe-mode') { out.safeMode = true; continue }
+    if (arg === '--json') { out.json = true; continue }
+    if (arg === '--profile-dir') { out.profileDir = String(argv[++index] ?? ''); continue }
+    if (arg === '--pkg-dir') { out.pkgDir = String(argv[++index] ?? ''); continue }
+    if (arg === '--candidate-dir') { out.candidateDir = String(argv[++index] ?? ''); continue }
+    if (arg === '--timeout') { out.timeoutMs = Math.max(1000, Number(argv[++index]) || 8000); continue }
+    throw new Error(`unknown argument: ${arg}`)
+  }
+  return out
+}
+
+const args = parseArgs(process.argv.slice(2))
+// 更新器候选包冒烟：不读 profile、不写任何文件，只报告是否可转正。
+if (args.candidateDir) {
+  const candidateDir = path.resolve(args.candidateDir)
+  const smoke = smokePackage(candidateDir, { timeoutMs: args.timeoutMs })
+  const result = { candidateDir, ...smoke }
+  if (args.json) console.log(JSON.stringify(result, null, 2))
+  else console.log(`${smoke.ok ? 'PASS' : 'FAIL'}  candidate smoke ${candidateDir}${smoke.ok ? '' : ' — ' + (smoke.error ?? 'no apply()')}`)
+  process.exit(smoke.ok ? 0 : 1)
+}
+const profileDir = path.resolve(args.profileDir || '')
+if (!args.profileDir) {
+  console.error('usage: node tools/boot-guard.mjs --profile-dir <profile> [--apply|--safe-mode] [--json]')
+  process.exit(2)
+}
+const result = { profileDir, ok: false, checked: 0, findings: [], applied: null }
+try {
+  const pkgDir = args.pkgDir ? path.resolve(args.pkgDir) : findFangPackageDir(profileDir)
+  if (!pkgDir) {
+    result.findings = [{ code: 'fang-package-not-found', level: 'block', detail: profileDir }]
+  } else {
+    result.packageDir = pkgDir
+    const parsed = readBundleRows(pkgDir)
+    if (!parsed.ok) result.findings.push({ code: 'bundle-patch-invalid', level: 'block', detail: parsed.error })
+    result.rows = parsed.rows.length
+    if (parsed.rows.length > 0) {
+      const checked = checkBundleRows(parsed.rows, { profileDir, ownPackage: readPackageName(pkgDir), timeoutMs: args.timeoutMs })
+      result.ok = checked.ok
+      result.checked = checked.checked
+      result.findings = [...result.findings, ...checked.findings]
+    } else if (parsed.ok) {
+      result.ok = true
+    }
+    if (args.apply || args.safeMode) {
+      const ids = args.safeMode
+        ? parsed.rows.map((row) => row.id)
+        : [...new Set(result.findings.filter((finding) => finding.level === 'block' && finding.id).map((finding) => finding.id))]
+      if (!ids.length) {
+        result.applied = { tried: false, reason: 'nothing-to-disable' }
+      } else {
+        result.applied = applyDisabledRows(profileDir, ids)
+        // 失败行已写 disabled:true（profile 覆盖层会跳过它们）→ 本次 guard 视为已恢复。
+        if (result.applied.ok) result.ok = true
+      }
+    }
+  }
+} catch (error) {
+  result.findings = [{ code: 'boot-guard-threw', level: 'block', detail: String(error?.message ?? error) }]
+}
+if (args.json) {
+  console.log(JSON.stringify(result, null, 2))
+} else {
+  console.log(`${result.ok ? 'PASS' : 'FAIL'}  boot-guard ${result.profileDir}`)
+  for (const finding of result.findings) console.log(`  ${finding.level}: ${finding.code}${finding.id ? ' ' + finding.id : ''}${finding.detail ? ' — ' + finding.detail : ''}`)
+  if (result.applied) console.log(`  applied: ${JSON.stringify(result.applied)}`)
+  if (!result.ok && !args.apply && !args.safeMode) {
+    console.log('  hint: add --apply to disable failing rows (profile patch backup is written), or --safe-mode')
+  }
+}
+process.exit(result.ok ? 0 : 1)

package/tools/decision-ingest.mjs

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// decision-ingest CLI — 独立进程把 ticket 送进母体决策中心的最低成本方式：
+//   node tools/decision-ingest.mjs --outbox-dir <dir> --payload '{"producer":"PJM",...}'
+//   node tools/decision-ingest.mjs --outbox-dir <dir> --flush
+// 母体地址默认读 env DSH_FANG_MOTHER，也可 --mother-dir 显式指定。
+import fs from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+
+import { createForkIngestClient } from '../src/lib/decision-ingest-client.mjs'
+
+function parseArgs(argv = []) {
+  const out = { payload: '', payloadFile: '', outboxDir: '', motherDir: '', flush: false, json: false }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--flush') { out.flush = true; continue }
+    if (arg === '--json') { out.json = true; continue }
+    const next = () => argv[++i]
+    if (arg === '--payload') { out.payload = String(next() ?? ''); continue }
+    if (arg === '--payload-file') { out.payloadFile = String(next() ?? ''); continue }
+    if (arg === '--outbox-dir') { out.outboxDir = String(next() ?? ''); continue }
+    if (arg === '--mother-dir') { out.motherDir = String(next() ?? ''); continue }
+    throw new Error(`unknown argument: ${arg}`)
+  }
+  return out
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  const outboxDir = args.outboxDir || process.env.DSH_FANG_INGEST_OUTBOX || path.join(process.cwd(), '.fang-decision-outbox')
+  const motherDir = args.motherDir || process.env.DSH_FANG_MOTHER || ''
+  const client = createForkIngestClient({ dataDir: outboxDir, motherDataDir: motherDir })
+  let payload = null
+  if (args.payload) payload = JSON.parse(args.payload)
+  else if (args.payloadFile) payload = JSON.parse(fs.readFileSync(args.payloadFile, 'utf8'))
+  const result = {}
+  if (payload) result.submitted = await client.submit(payload)
+  if (args.flush || !payload) result.flushed = await client.flush()
+  result.pending = client.pending()
+  if (args.json) console.log(JSON.stringify(result))
+  else {
+    if (result.submitted) console.log(result.submitted.queued ? `queued: ${result.submitted.outboxId}` : `sent: ${result.submitted.ticket?.id ?? 'ok'}`)
+    if (result.flushed) console.log(`flush: sent=${result.flushed.sent} failed=${result.flushed.failed} remaining=${result.flushed.remaining}`)
+    console.log(`pending: ${result.pending}`)
+  }
+}
+
+main().catch((error) => {
+  console.error(`[decision-ingest] ${String(error?.message ?? error)}`)
+  process.exitCode = 1
+})

package/tools/desktop-launch.mjs

@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Fang contributors — see LICENSE-CORE.
+//
+// 启动 DSH Desktop 并把它的重启权交给 restart-supervisor（默认 dry-run）。
+//
+//   node tools/desktop-launch.mjs --exe "C:\\Path\\DSH Desktop.exe" --data-root <fang-data>
+//   node tools/desktop-launch.mjs --execute --exe ... --data-root ... --arg=--some-desktop-flag
+import { spawn } from 'node:child_process'
+import process from 'node:process'
+
+import { describeDesktopLaunch, detectDesktopProfileDir, resolveDesktopLaunch, runBootGuard } from '../src/lib/desktop-launch.mjs'
+
+function parseArgs(argv = []) {
+  const out = { exe: '', dataRoot: '', profileDir: '', execute: false, args: [], bootGuard: true, safeModeOnFailure: true }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--execute') { out.execute = true; continue }
+    if (arg === '--exe') { out.exe = String(argv[++i] ?? ''); continue }
+    if (arg === '--data-root') { out.dataRoot = String(argv[++i] ?? ''); continue }
+    if (arg === '--profile-dir') { out.profileDir = String(argv[++i] ?? ''); continue }
+    if (arg === '--no-boot-guard') { out.bootGuard = false; continue }
+    if (arg === '--no-safe-mode') { out.safeModeOnFailure = false; continue }
+    if (arg.startsWith('--arg=')) { out.args.push(arg.slice('--arg='.length)); continue }
+    if (arg === '--arg') { out.args.push(String(argv[++i] ?? '')); continue }
+    throw new Error(`unknown argument: ${arg}`)
+  }
+  return out
+}
+
+const args = parseArgs(process.argv.slice(2))
+// 未显式给 profile-dir 时，按 DSH_PROFILE_DIR / DSH_HOME/profiles/<profile> 自动探测；
+// 探测不到就跳过自检（不阻塞启动），但会打印提示。
+const detectedProfileDir = (args.profileDir || !args.bootGuard) ? '' : detectDesktopProfileDir({ env: process.env, args: args.args })
+const profileDir = args.profileDir || detectedProfileDir
+if (args.bootGuard && !args.profileDir && detectedProfileDir) console.log(`[boot-guard] auto-detected profile: ${detectedProfileDir}`)
+const plan = resolveDesktopLaunch({ exe: args.exe, dataRoot: args.dataRoot, profileDir, args: args.args, execute: args.execute })
+if (!plan.ok) {
+  console.error(`desktop-launch: ${plan.error}`)
+  process.exitCode = 2
+} else {
+  console.log(describeDesktopLaunch(plan))
+  // 启动前自检：失败时（--execute 且未 --no-safe-mode）自动安全模式禁用 fang 行。
+  let guard = null
+  if (args.bootGuard && plan.profileDir) {
+    guard = runBootGuard(plan.profileDir, { dataRoot: plan.dataRoot, safeModeOnFailure: args.execute && args.safeModeOnFailure })
+    if (guard.ok && guard.safeModeApplied) {
+      console.warn(`[boot-guard] safe-mode applied: disabled ${guard.applied?.added ?? 0} fang row(s); fix profile before re-enabling`)
+    } else if (!guard.ok) {
+      console.error(`[boot-guard] blocked: ${guard.error ?? 'boot-guard-blocked'}`)
+      for (const finding of (guard.blocked ?? guard.findings ?? []).slice(0, 10)) {
+        console.error(`  ${finding.level}: ${finding.code}${finding.id ? ' ' + finding.id : ''}${finding.detail ? ' — ' + finding.detail : ''}`)
+      }
+      if (!args.execute && args.safeModeOnFailure) console.error('[boot-guard] dry-run: would apply safe-mode on --execute')
+      console.error('[boot-guard] 不启动；先运行 tools/boot-guard.mjs --profile-dir <profile> --apply/--safe-mode 修复，或加 --no-boot-guard')
+      process.exitCode = 2
+    } else {
+      console.log(`[boot-guard] PASS checked=${guard.checked ?? 0} findings=${(guard.findings ?? []).length}`)
+    }
+  }
+  if (process.exitCode === 2) {
+    // fail-closed：自检失败绝不继续启动
+  } else if (plan.dryRun) {
+    console.log('dry-run：未启动。加 --execute 才会真正交给 supervisor。')
+  } else {
+    const child = spawn(plan.argv[0], plan.argv.slice(1), { stdio: 'inherit', windowsHide: false })
+    child.on('exit', (code, signal) => {
+      if (signal) process.kill(process.pid, signal)
+      else process.exitCode = code ?? 0
+    })
+  }
+}