@twinsearth/dsh-master 3.3.3 → 3.3.5

package/dist-host/dual/schema.js

@@ -0,0 +1,367 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐。
+/** PM/PJM 共享的结构化契约。纯函数，不读写文件、不调用模型。 */
+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') : [];
+const error = (code, message, detail) => ({ ok: false, code, error: message, ...(detail === undefined ? {} : { detail }) });
+const positiveMinutes = (value, fallback = 30) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.min(10_080, Math.round(n)) : fallback;
+};
+function normalizeModules(value) {
+    return records(value).map((item, index) => ({
+        id: text(item.id, `module-${index + 1}`),
+        name: text(item.name, `模块 ${index + 1}`),
+        result: text(item.result ?? item.outcome),
+        architecture: text(item.architecture),
+        status: text(item.status, 'planned'),
+    })).filter((item) => item.name);
+}
+export function normalizePrd(input = {}, { id, now = Date.now() } = {}) {
+    const title = text(input.title);
+    const goal = text(input.goal);
+    if (!title)
+        return error('title-required', 'title is required');
+    if (!goal)
+        return error('goal-required', 'goal is required');
+    const prd = Object.freeze({
+        id: String(id),
+        title,
+        goal,
+        why: text(input.why, goal),
+        what: list(input.what),
+        architecture: text(input.architecture),
+        outcomes: list(input.outcomes),
+        modules: Object.freeze(normalizeModules(input.modules)),
+        priority: ['low', 'normal', 'high', 'critical'].includes(text(input.priority, 'normal')) ? text(input.priority, 'normal') : 'normal',
+        constraints: Object.freeze(list(input.constraints)),
+        acceptance: Object.freeze(list(input.acceptance)),
+        nonGoals: Object.freeze(list(input.nonGoals)),
+        assumptions: Object.freeze(list(input.assumptions)),
+        openQuestions: Object.freeze(list(input.openQuestions)),
+        requester: text(input.requester, 'user'),
+        status: 'draft',
+        createdAt: now,
+    });
+    return { ok: true, prd };
+}
+function normalizeAssessmentItems(category, value) {
+    const items = [];
+    for (const [index, raw] of records(value).entries()) {
+        const title = text(raw.title ?? raw.name);
+        if (!title)
+            return error(`${category}[${index}].title-required`, `${category}[${index}].title is required`);
+        const base = { id: text(raw.id, `${category}-${index + 1}`), title, detail: text(raw.detail ?? raw.description) };
+        if (category === 'completed') {
+            const evidence = list(raw.evidence);
+            // “已完成”必须有可复核证据；否则只能放 planned/unfinished，不能写 100%。
+            if (evidence.length === 0)
+                return error(`completed[${index}].evidence-required`, `completed item "${title}" requires file/test/report evidence`);
+            const progress = Number(raw.progress ?? 100);
+            items.push({ ...base, progress: Number.isFinite(progress) ? Math.max(0, Math.min(100, progress)) : 100, evidence });
+        }
+        else if (category === 'unfinished') {
+            items.push({ ...base, reason: text(raw.reason, '未说明'), nextStep: text(raw.nextStep ?? raw.plan), progress: Math.max(0, Math.min(99, Number(raw.progress ?? 0) || 0)) });
+        }
+        else if (category === 'blocked') {
+            items.push({ ...base, reason: text(raw.reason, '未说明'), blocker: text(raw.blocker ?? raw.reason, '未说明'), nextStep: text(raw.nextStep) });
+        }
+        else if (category === 'planned') {
+            items.push({ ...base, plan: text(raw.plan ?? raw.nextStep), estimateMinutes: raw.estimateMinutes === undefined ? null : positiveMinutes(raw.estimateMinutes), priority: text(raw.priority, 'normal') });
+        }
+        else if (category === 'conflicts') {
+            const options = records(raw.options).map((option) => ({ value: text(option.value), label: text(option.label), consequence: text(option.consequence) })).filter((option) => option.value && option.label);
+            items.push({ ...base, question: text(raw.question, title), options, currentInterpretation: text(raw.currentInterpretation) });
+        }
+        else {
+            items.push({ ...base, question: text(raw.question, title), currentInterpretation: text(raw.currentInterpretation), needsConfirmation: raw.needsConfirmation !== false });
+        }
+    }
+    return items;
+}
+export function normalizeAssessment(input = {}, { id, now = Date.now() } = {}) {
+    const title = text(input.title);
+    if (!title)
+        return error('title-required', 'assessment title is required');
+    const assessment = { id: String(id), prdId: text(input.prdId) || null, title, why: text(input.why), what: list(input.what), createdAt: now };
+    for (const category of ASSESSMENT_CATEGORIES) {
+        const normalized = normalizeAssessmentItems(category, input[category]);
+        if (!Array.isArray(normalized))
+            return normalized;
+        assessment[category] = Object.freeze(normalized.map((item) => Object.freeze(item)));
+    }
+    return { ok: true, assessment: Object.freeze(assessment) };
+}
+function normalizeTeam(value) {
+    return records(value).map((item, index) => ({
+        id: text(item.id, `owner-${index + 1}`),
+        role: text(item.role, 'developer'),
+        owner: text(item.owner, 'unassigned'),
+        responsibility: text(item.responsibility ?? item.scope),
+    }));
+}
+function normalizeSteps(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return error('steps-required', 'steps is required');
+    const steps = [];
+    for (const [index, raw] of value.entries()) {
+        const title = text(raw?.title);
+        const prompt = text(raw?.prompt);
+        if (!title)
+            return error(`steps[${index}].title-required`, `steps[${index}].title is required`);
+        if (!prompt)
+            return error(`steps[${index}].prompt-required`, `steps[${index}].prompt is required`);
+        steps.push({
+            id: text(raw.id, `step-${index + 1}`),
+            title,
+            prompt,
+            kind: text(raw.kind, 'development'),
+            owner: text(raw.owner, 'unassigned'),
+            where: text(raw.where, 'fork'),
+            estimateMinutes: positiveMinutes(raw.estimateMinutes),
+            dependsOn: list(raw.dependsOn),
+            acceptance: list(raw.acceptance),
+            status: 'pending',
+            fork: null,
+            summary: '',
+            evidence: [],
+            actualMinutes: null,
+        });
+    }
+    return steps;
+}
+export function normalizePlan(prd, input = {}, { id, now = Date.now() } = {}) {
+    if (!prd)
+        return error('prd-not-found', 'PRD not found');
+    const steps = normalizeSteps(input.steps);
+    if (!Array.isArray(steps))
+        return steps;
+    const totalEstimateMinutes = steps.reduce((sum, step) => sum + step.estimateMinutes, 0);
+    const plan = {
+        id: String(id),
+        prdId: prd.id,
+        title: text(input.title, `${prd.title} 项目计划`),
+        status: 'planned',
+        how: text(input.how),
+        where: text(input.where, 'fang fork / DSH Web / workspace'),
+        projectReview: list(input.projectReview ?? input.review),
+        requirements: list(input.requirements),
+        steps,
+        schedule: {
+            startAt: input.schedule?.startAt ? text(input.schedule.startAt) : null,
+            totalEstimateMinutes,
+            milestones: records(input.schedule?.milestones ?? input.milestones).map((item, index) => ({
+                id: text(item.id, `milestone-${index + 1}`),
+                title: text(item.title, `里程碑 ${index + 1}`),
+                owner: text(item.owner, 'unassigned'),
+                estimateMinutes: positiveMinutes(item.estimateMinutes),
+                dependsOn: list(item.dependsOn),
+            })),
+        },
+        team: normalizeTeam(input.team ?? input.who),
+        quality: {
+            tests: list(input.quality?.tests ?? input.tests),
+            deployment: list(input.quality?.deployment ?? input.deployment),
+            acceptance: list(input.quality?.acceptance ?? input.acceptance),
+        },
+        closure: { status: 'pending', summary: '', reviewReport: '', artifacts: [], acceptance: [], closedAt: null },
+        createdAt: now,
+        updatedAt: now,
+    };
+    return { ok: true, plan };
+}
+export function planProgress(plan) {
+    const steps = Array.isArray(plan?.steps) ? plan.steps : [];
+    const count = (status) => steps.filter((step) => step.status === status).length;
+    const total = steps.length;
+    const done = count('done');
+    const estimatedMinutes = steps.reduce((sum, step) => sum + (Number(step.estimateMinutes) || 0), 0);
+    const actualMinutes = steps.reduce((sum, step) => sum + (Number(step.actualMinutes) || 0), 0);
+    return {
+        total,
+        done,
+        running: count('running'),
+        failed: count('failed'),
+        pending: count('pending') + count('dispatching'),
+        percent: total === 0 ? 0 : Math.round((done / total) * 100),
+        estimatedMinutes,
+        actualMinutes,
+        canClose: total > 0 && done === total,
+    };
+}
+export function closePlan(plan, input = {}, now = Date.now()) {
+    const progress = planProgress(plan);
+    if (!progress.canClose)
+        return error('plan-not-ready', 'all steps must be done before project closure', { progress });
+    const summary = text(input.summary);
+    if (!summary)
+        return error('summary-required', 'closure summary is required');
+    plan.status = 'closed';
+    plan.updatedAt = now;
+    plan.closure = {
+        status: 'closed',
+        summary,
+        reviewReport: text(input.reviewReport),
+        artifacts: list(input.artifacts),
+        acceptance: list(input.acceptance),
+        closedAt: 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/dist-host/engine/atomic-switch.js

@@ -0,0 +1,159 @@
+// 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/dist-host/engine/health-probe.js

@@ -0,0 +1,86 @@
+// 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;
+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;
+    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(intervalMs, 5_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);
+    if (lastError)
+        return { ok: false, code: 'probe-failed', error: lastError, status: lastStatus, attempts, elapsedMs, url };
+    if (lastStatus !== null)
+        return { ok: false, code: 'unhealthy-status', status: lastStatus, attempts, elapsedMs, url };
+    return { ok: false, code: 'probe-timeout', attempts, elapsedMs, url };
+}

package/dist-host/engine/index.js

@@ -0,0 +1,18 @@
+// 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.js";
+export { probeHealth } from "./health-probe.js";
+export { runSafeUpdate, switchAndVerify } from "./safe-update.js";
+export { createPluginUpdater, buildSmokeScript, shellArgv, UPDATE_PHASES } from "./plugin-updater.js";
+export { createLlmStreamer, llmStreamFn } from "./llm-stream.js";