@twinsearth/dsh-master 3.3.4 → 3.3.6

package/src/dual/orchestrator.ts

@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * PM/PJM 编排策略（3.3.5）。
+ *
+ * 解决的问题：模型知道工具清单，但不知道“现在这一步该用哪个”。让它在 7 个工具里猜，
+ * 就会出现「PRD 还没写就交接」「还有未决问题就派发」这类错误。
+ *
+ * 这里把闭环状态机写成确定性函数：给定结构化状态，返回**唯一推荐动作**与理由。
+ * 模型仍然负责内容（写 PRD、拆 WBS、判定验收），编排不替它做判断，也不产生副作用。
+ *
+ * 约束：
+ *   * 纯函数，不读全局、不写数据；
+ *   * 每个 action 都必须对应真实存在的工具名（测试会校验，防止漂移）；
+ *   * 无法推进时返回 `blocked` + 具名原因，而不是编一个动作。
+ */
+
+export const PM_ACTIONS = Object.freeze([
+  'create_prd', 'create_assessment', 'clarify', 'handoff', 'review', 'done', 'blocked',
+])
+
+export const PJM_ACTIONS = Object.freeze([
+  'take_handoff', 'return_to_pm', 'create_plan', 'dispatch', 'report', 'complete_feedback', 'close', 'done', 'blocked',
+])
+
+/** action → 真实工具名（agent preset 里注册过；测试比对）。 */
+export const ACTION_TOOL = Object.freeze({
+  create_prd: 'pm_create_prd',
+  create_assessment: 'pm_create_assessment',
+  clarify: 'pm_create_prd',
+  handoff: 'pm_handoff_to_pjm',
+  review: 'pm_review_feedback',
+  take_handoff: 'pjm_take_handoff',
+  return_to_pm: 'pjm_take_handoff',
+  create_plan: 'pjm_create_plan',
+  dispatch: 'pjm_dispatch_step',
+  report: 'pjm_report',
+  complete_feedback: 'pjm_submit_feedback',
+  close: 'pjm_close_project',
+  done: null,
+  blocked: null,
+})
+
+/**
+ * PM 的下一步：PRD → 盘点 → 澄清 → 交接 → 复核。
+ * @param {{prd?: object|null, assessment?: object|null, handoff?: object|null, feedback?: object|null, review?: object|null}} state
+ */
+export function nextPmAction(state = {}) {
+  const prd = state.prd ?? null
+  const assessment = state.assessment ?? null
+  const handoff = state.handoff ?? null
+  const feedback = state.feedback ?? null
+  const review = state.review ?? null
+
+  if (!prd) {
+    return { action: 'create_prd', tool: ACTION_TOOL.create_prd, reason: 'no-prd-yet', detail: '先写结构化 PRD（title + goal）' }
+  }
+  if (!assessment) {
+    return { action: 'create_assessment', tool: ACTION_TOOL.create_assessment, reason: 'no-assessment-yet', detail: '六类盘点必须先落库，completed 项要有证据' }
+  }
+  const openQuestions = Array.isArray(prd.openQuestions) ? prd.openQuestions.length : 0
+  const conflicts = Array.isArray(assessment.conflicts) ? assessment.conflicts.length : 0
+  if (openQuestions > 0 || conflicts > 0) {
+    return {
+      action: 'clarify',
+      tool: null,
+      reason: openQuestions > 0 ? 'open-questions-unresolved' : 'conflicts-unresolved',
+      detail: openQuestions > 0
+        ? `PRD 还有 ${openQuestions} 个未决问题，必须用 ask_user_question 一次问一个决策点`
+        : `盘点里有 ${conflicts} 个冲突，必须让用户重新判断（回复：新需求新方案）`,
+      blocking: true,
+    }
+  }
+  if (!handoff) {
+    return {
+      action: 'handoff',
+      tool: ACTION_TOOL.handoff,
+      reason: 'ready-to-handoff',
+      detail: '验收标准齐全且无未决项，打交接包给 PJM',
+      argsHint: { prdId: prd.id, assessmentId: assessment.id },
+    }
+  }
+  if (handoff.status === 'needs-clarification') {
+    return {
+      action: 'blocked',
+      tool: null,
+      reason: handoff.reason || 'handoff-not-ready',
+      detail: '交接包未就绪，先解决未决问题再重新交接',
+      blocking: true,
+    }
+  }
+  if (feedback && !review) {
+    return {
+      action: 'review',
+      tool: ACTION_TOOL.review,
+      reason: 'feedback-awaiting-review',
+      detail: 'PJM 已交反馈：逐条核对验收（met + 证据），写复盘与总结；结论必须与验收一致',
+      argsHint: { feedbackId: feedback.id },
+    }
+  }
+  if (review) {
+    return {
+      action: 'done',
+      tool: null,
+      reason: review.verdict === 'accepted' ? 'loop-accepted' : 'loop-changes-requested',
+      detail: review.verdict === 'accepted' ? '本轮闭环已通过' : 'PJM 需按复核意见重做',
+    }
+  }
+  return {
+    action: 'blocked',
+    tool: null,
+    reason: 'waiting-for-pjm',
+    detail: '等 PJM 接单并提交反馈；PM 不替它派发',
+    blocking: false,
+  }
+}
+
+/**
+ * PJM 的下一步：接单 → 计划 → 派发 → 反馈 → 结案。
+ * @param {{handoff?: object|null, plan?: object|null, feedback?: object|null}} state
+ */
+export function nextPjmAction(state = {}) {
+  const handoff = state.handoff ?? null
+  const plan = state.plan ?? null
+  const feedback = state.feedback ?? null
+
+  if (handoff && handoff.status === 'needs-clarification') {
+    return {
+      action: 'return_to_pm',
+      tool: null,
+      reason: 'handoff-needs-clarification',
+      detail: '交接包未就绪：退回 PM 澄清，不得硬开工',
+      blocking: true,
+    }
+  }
+  if (handoff && handoff.status === 'ready' && !plan) {
+    return {
+      action: 'take_handoff',
+      tool: ACTION_TOOL.take_handoff,
+      reason: 'handoff-ready',
+      detail: '接单后再拆 WBS',
+      argsHint: { handoffId: handoff.id },
+    }
+  }
+  if (!plan) {
+    return {
+      action: 'create_plan',
+      tool: ACTION_TOOL.create_plan,
+      reason: 'no-plan-yet',
+      detail: '用 pjm_create_plan 写七类项目内容，步骤必须自己拆（交接包不含 WBS）',
+    }
+  }
+  const steps = Array.isArray(plan.steps) ? plan.steps : []
+  const failed = steps.filter((step) => step.status === 'failed')
+  const running = steps.filter((step) => step.status === 'running' || step.status === 'dispatching')
+  const pending = steps.filter((step) => step.status === 'pending')
+  const blockedReport = Array.isArray(plan.reports) ? [...plan.reports].reverse().find((report) => report.status === 'blocked') : null
+
+  if (blockedReport && (blockedReport.blocker || blockedReport.summary)) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'blocked-reported',
+      detail: `最近一次节点报告为阻塞：${blockedReport.blocker || blockedReport.summary}；需要 PM/用户决策后才能继续`,
+      blocking: true,
+    }
+  }
+  if (failed.length > 0) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'step-failed',
+      detail: `${failed.length} 个步骤失败：如实汇报失败原因，不得写成完成`,
+      argsHint: { planId: plan.id, status: 'blocked' },
+    }
+  }
+  if (running.length > 0) {
+    return {
+      action: 'report',
+      tool: ACTION_TOOL.report,
+      reason: 'step-running',
+      detail: '有步骤在隔离执行体中运行：等结果并汇报节点，不重复派发',
+      argsHint: { planId: plan.id, status: 'progress' },
+    }
+  }
+  if (pending.length > 0) {
+    const next = pending[0]
+    return {
+      action: 'dispatch',
+      tool: ACTION_TOOL.dispatch,
+      reason: 'step-pending',
+      detail: '派发下一个待办步骤（走 fangForker.spawn；不可用即 fail-closed）',
+      argsHint: { planId: plan.id, stepId: next.id },
+    }
+  }
+  if (feedback) {
+    if (plan.status === 'closed') {
+      return { action: 'done', tool: null, reason: 'project-closed', detail: '项目已结案，等 PM 复核结论' }
+    }
+    return {
+      action: 'close',
+      tool: ACTION_TOOL.close,
+      reason: 'all-steps-done',
+      detail: '全部步骤完成且已提交反馈：结案需要总结、评审报告、验收与资料清单',
+      argsHint: { planId: plan.id },
+    }
+  }
+  return {
+    action: 'complete_feedback',
+    tool: ACTION_TOOL.complete_feedback,
+    reason: 'all-steps-done-no-feedback',
+    detail: '全部步骤完成：提交交付、偏差、遗留问题与测试证据，交给 PM 复核',
+    argsHint: { planId: plan.id },
+  }
+}
+
+/** 给 UI/测试用的紧凑摘要。 */
+export function describeAction(result) {
+  if (!result || !result.action) return 'blocked: unknown state'
+  return [result.action, result.reason, result.detail].filter(Boolean).join(' · ')
+}

package/src/dual/schema.ts

@@ -6,7 +6,6 @@
 
 export const ASSESSMENT_CATEGORIES = Object.freeze(['completed', 'unfinished', 'blocked', 'planned', 'conflicts', 'ambiguities'])
 export const PROJECT_SECTIONS = Object.freeze(['projectReview', 'steps', 'requirements', 'schedule', 'team', 'quality', 'closure'])
-
 const text = (value, fallback = '') => String(value ?? fallback).trim()
 const list = (value) => Array.isArray(value) ? value.map((item) => text(item)).filter(Boolean) : (text(value) ? [text(value)] : [])
 const records = (value) => Array.isArray(value) ? value.filter((item) => item && typeof item === 'object') : []
@@ -206,3 +205,151 @@ export function closePlan(plan, input = {}, now = Date.now()) {
   }
   return { ok: true, plan, closure: plan.closure, progress }
 }
+
+// ── 闭环：PM 交接 → PJM 执行/反馈 → PM 复核/复盘/总结 ──────────────────────────
+
+export const HANDOFF_STATUS = Object.freeze(['needs-clarification', 'ready', 'accepted', 'withdrawn'])
+export const REVIEW_VERDICTS = Object.freeze(['accepted', 'changes-requested'])
+
+/**
+ * PM → PJM 交接包。`ready` 是硬门禁：
+ *   * 没有验收标准 → 不 ready（PJM 无法判定“做没做成”）；
+ *   * 还有未决问题/冲突 → 不 ready（PJM 不得替用户决定需求）。
+ */
+export function normalizeHandoff(prd, assessment, input = {}, { id, now = Date.now() } = {}) {
+  if (!prd) return error('prd-not-found', 'PRD not found', { id: String(input.prdId ?? '') })
+  const acceptance = [...(list(input.acceptance).length ? list(input.acceptance) : prd.acceptance)]
+  const openQuestions = [...prd.openQuestions, ...list(input.openQuestions)]
+  const conflicts = Array.isArray(assessment?.conflicts) ? assessment.conflicts.map((item) => text(item.question)).filter(Boolean) : []
+  const ready = acceptance.length > 0 && openQuestions.length === 0 && conflicts.length === 0
+  const reason = ready
+    ? null
+    : acceptance.length === 0
+      ? 'acceptance-required'
+      : openQuestions.length > 0
+        ? `open-questions-unresolved:${openQuestions.length}`
+        : `conflicts-unresolved:${conflicts.length}`
+  return {
+    ok: true,
+    handoff: ({
+      id: String(id),
+      prdId: prd.id,
+      assessmentId: String(input.assessmentId ?? '') || null,
+      title: text(input.title, prd.title),
+      priority: prd.priority,
+      acceptance: Object.freeze(acceptance),
+      constraints: prd.constraints,
+      openQuestions: Object.freeze(openQuestions),
+      conflicts: Object.freeze(conflicts),
+      status: ready ? 'ready' : 'needs-clarification',
+      reason,
+      planId: null,
+      preparedAt: now,
+      acceptedAt: null,
+    }),
+  }
+}
+
+/** PJM 接单：只有 ready 的交接包可以被接走，否则退回 PM 澄清。 */
+export function acceptHandoff(handoff, input = {}, now = Date.now()) {
+  if (!handoff) return error('handoff-not-found', 'Handoff not found')
+  if (handoff.status === 'accepted') return error('handoff-already-accepted', 'Handoff already accepted', { planId: handoff.planId })
+  if (handoff.status !== 'ready') {
+    return error('handoff-not-ready', 'Handoff is not ready; PM must resolve open questions or add acceptance criteria', {
+      status: handoff.status, reason: handoff.reason,
+    })
+  }
+  handoff.status = 'accepted'
+  handoff.acceptedAt = now
+  handoff.planId = String(input.planId ?? '') || null
+  return { ok: true, handoff }
+}
+
+/**
+ * PJM → PM 自反馈：必须在计划全部步骤完成后提交；只写实测结果，不写结论性评价。
+ */
+export function normalizeFeedback(plan, prd, input = {}, { id, now = Date.now() } = {}) {
+  if (!plan) return error('plan-not-found', 'Plan not found', { id: String(input.planId ?? '') })
+  const progress = planProgress(plan)
+  if (!progress.canClose) return error('plan-not-ready', 'feedback requires every step to be done', { progress })
+  const summary = text(input.summary)
+  if (!summary) return error('summary-required', 'feedback summary is required')
+  const delivered = plan.steps
+    .filter((step) => step.status === 'done')
+    .map((step) => Object.freeze({
+      stepId: step.id,
+      title: step.title,
+      owner: step.owner,
+      summary: step.summary,
+      evidence: Object.freeze([...(step.evidence ?? [])]),
+      actualMinutes: step.actualMinutes ?? null,
+    }))
+  return {
+    ok: true,
+    feedback: ({
+      id: String(id),
+      planId: plan.id,
+      prdId: plan.prdId ?? prd?.id ?? null,
+      handoffId: String(input.handoffId ?? '') || null,
+      status: plan.closure?.status === 'closed' ? 'closed' : 'reported',
+      summary,
+      delivered: Object.freeze(delivered),
+      deviations: Object.freeze(list(input.deviations)),
+      openIssues: Object.freeze(list(input.openIssues)),
+      tests: Object.freeze(list(input.tests ?? plan.quality?.tests)),
+      metrics: Object.freeze({
+        steps: progress.total,
+        done: progress.done,
+        estimatedMinutes: progress.estimatedMinutes,
+        actualMinutes: progress.actualMinutes,
+        percent: progress.percent,
+      }),
+      createdAt: now,
+    }),
+  }
+}
+
+/**
+ * PM 复核：逐条验收标准必须给出 met 布尔与证据；结论必须与验收结果一致，
+ * 不允许「有未达标却判 accepted」或「全达标却判 changes-requested」。
+ */
+export function normalizeReview(feedback, input = {}, { id, now = Date.now() } = {}) {
+  if (!feedback) return error('feedback-not-found', 'Feedback not found', { id: String(input.feedbackId ?? '') })
+  const checks = []
+  for (const [index, raw] of records(input.acceptanceChecks).entries()) {
+    const criterion = text(raw.criterion)
+    if (!criterion) return error(`acceptanceChecks[${index}].criterion-required`, `acceptanceChecks[${index}].criterion is required`)
+    if (typeof raw.met !== 'boolean') return error(`acceptanceChecks[${index}].met-required`, `acceptanceChecks[${index}].met must be boolean`)
+    checks.push(Object.freeze({ criterion, met: raw.met, evidence: Object.freeze(list(raw.evidence)), note: text(raw.note) }))
+  }
+  if (checks.length === 0) return error('acceptance-checks-required', 'at least one acceptance check is required')
+  const allMet = checks.every((check) => check.met === true)
+  const verdict = REVIEW_VERDICTS.includes(text(input.verdict)) ? text(input.verdict) : (allMet ? 'accepted' : 'changes-requested')
+  if (verdict === 'accepted' && !allMet) {
+    return error('verdict-inconsistent', 'cannot accept while an acceptance check is not met', { failed: checks.filter((check) => !check.met).map((check) => check.criterion) })
+  }
+  if (verdict === 'changes-requested' && allMet) {
+    return error('verdict-inconsistent', 'all checks are met; use accepted or explain with a new check')
+  }
+  const summary = text(input.summary)
+  if (!summary) return error('summary-required', 'review summary is required')
+  const retrospective = input.retrospective && typeof input.retrospective === 'object' ? input.retrospective : {}
+  return {
+    ok: true,
+    review: ({
+      id: String(id),
+      feedbackId: feedback.id,
+      planId: feedback.planId,
+      prdId: feedback.prdId ?? null,
+      verdict,
+      acceptanceChecks: Object.freeze(checks),
+      retrospective: Object.freeze({
+        kept: Object.freeze(list(retrospective.kept ?? input.kept)),
+        improve: Object.freeze(list(retrospective.improve ?? input.improve)),
+        lessons: Object.freeze(list(retrospective.lessons ?? input.lessons)),
+      }),
+      summary,
+      createdAt: now,
+    }),
+  }
+}

package/src/engine/atomic-switch.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐。
+
+/**
+ * 蓝绿指针切换（AtomicSwitcher 的可编译实现）。
+ *
+ * 只做一件事：把 `linkPath` 这个目录指针**原子地**指向 `targetDir`。
+ * 做法是「新链接写临时名 → rename 覆盖」，因为同文件系统内 rename 是原子的：
+ * 读者永远看到旧指针或新指针，不会看到中间态。
+ *
+ * 平台差异（不隐藏）：
+ *   * POSIX：`symlink(target, link, 'dir')`，rename 覆盖。
+ *   * Windows：`symlink(..., 'junction')`。**junction 只能指向目录、不能跨卷**，
+ *     且不需要管理员权限（symlink 需要）。因此这里对 Windows 明确用 junction。
+ *
+ * 不做什么：不删旧目录、不动进程、不看护端口 —— 那些属于调用方（或瓮城的 VM 层）。
+ */
+
+import fsDefault from 'node:fs/promises'
+import path from 'node:path'
+
+const noop = () => {}
+
+function asString(value) { return String(value ?? '').trim() }
+
+async function exists(fs, target) {
+  try { await fs.lstat(target); return true } catch { return false }
+}
+
+/**
+ * @param {{
+ *   linkPath: string, targetDir: string,
+ *   fs?: object, platform?: string,
+ *   now?: () => number,
+ * }} input
+ */
+export async function switchPointer(input = {}) {
+  const fs = input.fs ?? fsDefault
+  const platform = String(input.platform ?? process.platform)
+  const now = typeof input.now === 'function' ? input.now : () => Date.now()
+  const linkPath = path.resolve(asString(input.linkPath))
+  const targetDir = path.resolve(asString(input.targetDir))
+  if (!asString(input.linkPath)) return { ok: false, code: 'link-path-required', error: 'linkPath is required' }
+  if (!asString(input.targetDir)) return { ok: false, code: 'target-dir-required', error: 'targetDir is required' }
+  if (linkPath === targetDir) return { ok: false, code: 'self-reference', error: 'linkPath and targetDir must differ' }
+
+  // 目标必须是真实存在的目录：切换到一个不存在的绿槽比不切换更糟。
+  let targetStat = null
+  try { targetStat = await fs.stat(targetDir) } catch { /* handled below */ }
+  if (!targetStat || !targetStat.isDirectory()) {
+    return { ok: false, code: 'target-missing', error: `target directory does not exist: ${targetDir}` }
+  }
+
+  const parent = path.dirname(linkPath)
+  if (!(await exists(fs, parent))) return { ok: false, code: 'parent-missing', error: `parent directory does not exist: ${parent}` }
+
+  // 现有指针必须是链接（或不存在）；覆盖普通目录/文件会静默毁数据，直接拒绝。
+  if (await exists(fs, linkPath)) {
+    const current = await fs.lstat(linkPath)
+    if (!current.isSymbolicLink() && platform !== 'win32') {
+      return { ok: false, code: 'link-is-not-a-symlink', error: `${linkPath} exists and is not a symlink` }
+    }
+    if (!current.isSymbolicLink() && platform === 'win32') {
+      // Windows 上 junction 在 lstat 里呈现为 symlink；普通目录一律拒绝。
+      return { ok: false, code: 'link-is-not-a-junction', error: `${linkPath} exists and is not a junction` }
+    }
+  }
+
+  const tempLink = `${linkPath}.${process.pid}.${now()}.tmp`
+  const type = platform === 'win32' ? 'junction' : 'dir'
+  const startedAt = now()
+  try {
+    await fs.rm(tempLink, { force: true, recursive: true }).catch(noop)
+    await fs.symlink(targetDir, tempLink, type)
+    // rename 覆盖仅在同一文件系统内原子；跨卷时调用方必须自己保证同卷。
+    // Windows 上 rename 不能覆盖已存在的 junction（EPERM），退回“先移开再放”，
+    // 并如实标记 atomic=false —— 这个平台限制是真实存在的，不假装完美。
+    let replaced = 'rename'
+    let atomic = true
+    try {
+      await fs.rename(tempLink, linkPath)
+    } catch (error) {
+      if (platform !== 'win32' || error?.code !== 'EPERM') throw error
+      const backup = `${linkPath}.${process.pid}.${now()}.bak`
+      await fs.rename(linkPath, backup)
+      try {
+        await fs.rename(tempLink, linkPath)
+      } catch (inner) {
+        await fs.rename(backup, linkPath).catch(noop)
+        throw inner
+      }
+      await fs.rm(backup, { force: true, recursive: true }).catch(noop)
+      replaced = 'move-aside'
+      atomic = false
+    }
+    let resolved = null
+    try { resolved = await fs.realpath(linkPath) } catch { /* 读取失败不影响切换结论 */ }
+    return {
+      ok: true,
+      code: 'switched',
+      linkPath,
+      targetDir,
+      linkType: type,
+      replaced,
+      atomic,
+      resolved,
+      resolvedMatchesTarget: resolved ? path.resolve(resolved) === targetDir : null,
+      elapsedMs: Math.max(0, now() - startedAt),
+    }
+  } catch (error) {
+    await fs.rm(tempLink, { force: true, recursive: true }).catch(noop)
+    return { ok: false, code: 'switch-failed', error: String(error?.message ?? error), linkPath, targetDir }
+  }
+}
+
+/**
+ * 读指针当前指向（只读）。不存在 / 不是链接时给出具名原因，不抛。
+ */
+export async function readPointer(input = {}) {
+  const fs = input.fs ?? fsDefault
+  const linkPath = path.resolve(asString(input.linkPath))
+  if (!asString(input.linkPath)) return { ok: false, code: 'link-path-required', error: 'linkPath is required' }
+  if (!(await exists(fs, linkPath))) return { ok: false, code: 'link-missing', error: `${linkPath} does not exist` }
+  try {
+    const stat = await fs.lstat(linkPath)
+    const target = await fs.readlink(linkPath).catch(() => null)
+    const resolved = await fs.realpath(linkPath).catch(() => null)
+    return { ok: true, linkPath, isSymlink: stat.isSymbolicLink(), target, resolved }
+  } catch (error) {
+    return { ok: false, code: 'read-failed', error: String(error?.message ?? error) }
+  }
+}
+
+/**
+ * 用「先切到新槽、失败切回旧槽」的方式包装一次切换，失败时保证指针回到原目标。
+ */
+export async function switchWithRollback(input = {}) {
+  const fs = input.fs ?? fsDefault
+  const previous = await readPointer({ fs, linkPath: input.linkPath })
+  const switched = await switchPointer(input)
+  if (switched.ok) return { ...switched, rollback: null }
+  if (!previous.ok || !previous.resolved) return { ...switched, rollback: null }
+  const restore = await switchPointer({ ...input, targetDir: previous.resolved })
+  return { ...switched, rollback: restore }
+}

package/src/engine/health-probe.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 健康检查探针（HealthProbe 的可编译实现）。
+ *
+ * 只做「有界轮询 + 明确结论」：
+ *   * 有总超时和最大尝试次数，不会无限等；
+ *   * 任何一次拿到期望状态码即成功（默认 200–299）；
+ *   * 超时/连接失败返回具名原因，**不**把“没连上”当成“健康”。
+ */
+
+const DEFAULT_INTERVAL_MS = 1_000
+const DEFAULT_TIMEOUT_MS = 30_000
+const DEFAULT_MAX_ATTEMPTS = 30
+const DEFAULT_REQUEST_TIMEOUT_MS = 5_000
+
+function positiveInt(value, fallback) {
+  const n = Number(value)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(1, ms)))
+}
+
+/**
+ * @param {{
+ *   url: string,
+ *   fetchImpl?: typeof fetch,
+ *   timeoutMs?: number, intervalMs?: number, maxAttempts?: number,
+ *   expectStatus?: (status: number) => boolean,
+ *   now?: () => number, sleepImpl?: (ms: number) => Promise<void>,
+ * }} input
+ */
+export async function probeHealth(input = {}) {
+  const url = String(input.url ?? '').trim()
+  if (!url) return { ok: false, code: 'url-required', error: 'url is required', attempts: 0 }
+  const fetchImpl = input.fetchImpl ?? fetch
+  const timeoutMs = positiveInt(input.timeoutMs, DEFAULT_TIMEOUT_MS)
+  const intervalMs = positiveInt(input.intervalMs, DEFAULT_INTERVAL_MS)
+  const maxAttempts = positiveInt(input.maxAttempts, DEFAULT_MAX_ATTEMPTS)
+  const now = typeof input.now === 'function' ? input.now : () => Date.now()
+  const wait = typeof input.sleepImpl === 'function' ? input.sleepImpl : sleep
+  const expectStatus = typeof input.expectStatus === 'function'
+    ? input.expectStatus
+    : (status) => status >= 200 && status < 300
+
+  const startedAt = now()
+  const deadline = startedAt + timeoutMs
+  // 单次请求超时必须与轮询间隔分开：拿 intervalMs 当请求超时会把「慢但有响应」误判成 probe-failed
+  const requestTimeoutMs = positiveInt(input.requestTimeoutMs, DEFAULT_REQUEST_TIMEOUT_MS)
+  let attempts = 0
+  let lastStatus = null
+  let lastError = null
+
+  while (attempts < maxAttempts) {
+    if (attempts > 0 && now() >= deadline) break
+    attempts += 1
+    try {
+      const controller = typeof AbortController === 'function' ? new AbortController() : null
+      const timer = controller ? setTimeout(() => controller.abort(), Math.max(1, Math.min(requestTimeoutMs, 30_000))) : null
+      if (timer && typeof timer.unref === 'function') timer.unref()
+      let response = null
+      try {
+        response = await fetchImpl(url, { method: 'GET', signal: controller ? controller.signal : undefined })
+      } finally {
+        if (timer) clearTimeout(timer)
+      }
+      lastStatus = Number(response?.status ?? 0) || null
+      lastError = null
+      if (lastStatus !== null && expectStatus(lastStatus)) {
+        return { ok: true, code: 'healthy', status: lastStatus, attempts, elapsedMs: Math.max(0, now() - startedAt), url }
+      }
+    } catch (error) {
+      lastError = String(error?.message ?? error)
+    }
+    if (now() >= deadline) break
+    if (attempts < maxAttempts) await wait(intervalMs)
+  }
+
+  const elapsedMs = Math.max(0, now() - startedAt)
+  // 只要拿到过响应，就以状态码为准——不能因为某次连接失败把「服务返回 503」改写成 probe-failed
+  if (lastStatus !== null) return { ok: false, code: 'unhealthy-status', status: lastStatus, attempts, elapsedMs, url }
+  if (lastError) return { ok: false, code: 'probe-failed', error: lastError, status: lastStatus, attempts, elapsedMs, url }
+  return { ok: false, code: 'probe-timeout', attempts, elapsedMs, url }
+}

package/src/engine/index.ts

@@ -0,0 +1,20 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+
+/**
+ * 3.3.5 · 宿主侧引擎原语（不依赖任何 VM / 瓮城代码）。
+ *
+ * 这三个原语回答的是「切换/验证/回滚」的正确性，而不是「怎么管 VM」：
+ *   * `switchPointer` / `switchWithRollback` —— 蓝绿指针原子切换，失败回到旧目标；
+ *   * `probeHealth` —— 有界健康检查，不会把“连不上”当健康；
+ *   * `runSafeUpdate` —— 快照 → 更新 → 冒烟 → 失败回滚，执行能力由调用方注入。
+ *
+ * 没有 `vm_create`/`vm_exec` 这类假设：房主不持有 VM；需要时由宿主或瓮城提供 executor。
+ */
+
+export { switchPointer, readPointer, switchWithRollback } from './atomic-switch.ts'
+export { probeHealth } from './health-probe.ts'
+export { runSafeUpdate, switchAndVerify } from './safe-update.ts'
+export { createPluginUpdater, buildSmokeScript, shellArgv, UPDATE_PHASES } from './plugin-updater.ts'
+export { createLlmStreamer, llmStreamFn } from './llm-stream.ts'