@twinsearth/dsh-master 3.3.4 → 3.3.5

package/dist-host/engine/plugin-updater.js

@@ -0,0 +1,392 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 插件安全更新流水线（房主版 PluginUpdater · 3.3.5 增强）。
+ *
+ * 语义：快照 → 后台更新（可轮询）→ 冒烟 → 成功清理 / 失败物理回滚。
+ * 不假设存在 VM：执行能力由调用方注入 `executor`。
+ *
+ * 本版新增（相对上一版）：
+ *   1. **生命周期中断**：`dispose()`（宿主侧挂在 ctx.effect 里）会中止所有进行中的更新；
+ *   2. **信号合并**：外部 `signal` + 内部整体超时 + job 超时，三者任一触发都能打断轮询；
+ *   3. **进度节流**：`minProgressIntervalMs` 限制 onProgress 频率，终态与阶段切换必发；
+ *   4. **致命告警钩子**：回滚失败时 `onFatal()` 必被调用（宿主可据此弹全局告警）；
+ *   5. **命令构造辅助**：`shellArgv()` 以 argv 形式传脚本，避免手写引号导致的注入/截断。
+ *
+ * executor 契约：
+ *   snapshot(name) → {ok}
+ *   restore(name) → {ok}
+ *   run(argv, {phase, signal?}) → {ok, jobId?}
+ *   jobStatus(jobId) → {status:'running'|'completed'|'failed', exitCode?, stdout?, stderr?}
+ *   deleteSnapshot?(name)
+ */
+export const UPDATE_PHASES = Object.freeze([
+    'idle', 'snapshotting', 'updating', 'smoke-testing', 'rolling-back', 'success', 'failed',
+]);
+const DEFAULTS = Object.freeze({
+    timeoutMs: 10 * 60 * 1000,
+    smokeTimeoutMs: 60 * 1000,
+    pollIntervalMs: 2_000,
+    minProgressIntervalMs: 0,
+});
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(1, ms)));
+const ABORTED = Symbol('aborted');
+/**
+ * 把 AbortSignal 变成可 race 的 promise：即使适配器的某个调用永不 resolve，
+ * 中止也能立刻打断等待（这是“不留僵尸轮询”的关键）。
+ */
+function watchAbort(signal) {
+    if (!signal)
+        return { promise: new Promise(() => { }), cancel: () => { } };
+    let listener = null;
+    const promise = new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(ABORTED);
+            return;
+        }
+        listener = () => resolve(ABORTED);
+        signal.addEventListener('abort', listener, { once: true });
+    });
+    return {
+        promise,
+        cancel: () => { try {
+            if (listener)
+                signal.removeEventListener('abort', listener);
+        }
+        catch { /* ignore */ } },
+    };
+}
+function requiredExecutor(executor) {
+    if (!executor || typeof executor.snapshot !== 'function' || typeof executor.restore !== 'function' || typeof executor.run !== 'function') {
+        return null;
+    }
+    return executor;
+}
+function positiveInt(value, fallback) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
+}
+/**
+ * 把一段 shell 脚本包成 argv，**不拼接引号**：脚本始终是单个参数。
+ * 这是避免“引号地狱 / 注入”的正解——不要手写 `'${script.replace(/'/g, ...)}'`。
+ */
+export function shellArgv(script, { shell = 'bash', login = true } = {}) {
+    const text = String(script ?? '');
+    if (!text.trim())
+        return [];
+    return [shell, login ? '-lc' : '-c', text];
+}
+/** 默认冒烟脚本：set -e + 有限次健康探测（端口由调用方传入，别硬编码 3000）。 */
+export function buildSmokeScript({ port = 3000, path = '/api/health', attempts = 10, intervalSeconds = 2 } = {}) {
+    const safePath = String(path).startsWith('/') ? String(path) : `/${path}`;
+    const tries = Math.max(1, Math.min(60, Number(attempts) || 10));
+    const wait = Math.max(1, Math.min(30, Number(intervalSeconds) || 2));
+    return [
+        'set -eu',
+        'dsh stop >/dev/null 2>&1 || true',
+        'dsh start --daemon',
+        `for i in $(seq 1 ${tries}); do`,
+        `  if curl -fsS "http://127.0.0.1:${Number(port) || 3000}${safePath}" >/dev/null; then exit 0; fi`,
+        `  sleep ${wait}`,
+        'done',
+        'echo "health check timeout" >&2',
+        'exit 1',
+    ].join('\n');
+}
+/**
+ * @param {{
+ *   executor?: object,
+ *   logger?: { info?: Function, warn?: Function, error?: Function },
+ *   onProgress?: (progress: {phase:string, message:string, percent:number, at:number}) => void,
+ *   onFatal?: (failure: {code:string, message:string, snapshotId:string, steps:object[]}) => void,
+ *   minProgressIntervalMs?: number,
+ *   now?: () => number,
+ *   sleepImpl?: (ms:number) => Promise<void>,
+ * }} deps
+ */
+export function createPluginUpdater(deps = {}) {
+    const logger = deps.logger ?? {};
+    const now = typeof deps.now === 'function' ? deps.now : () => Date.now();
+    const sleep = typeof deps.sleepImpl === 'function' ? deps.sleepImpl : sleepDefault;
+    const progressInterval = Number(deps.minProgressIntervalMs) > 0 ? Number(deps.minProgressIntervalMs) : DEFAULTS.minProgressIntervalMs;
+    const running = new Map();
+    const lifecycle = new AbortController();
+    let disposed = false;
+    const log = (level, message) => { try {
+        logger[level]?.(message);
+    }
+    catch { /* ignore */ } };
+    function makeReporter() {
+        let lastEmitAt = -Infinity;
+        let lastPhase = null;
+        const emit = (progress, force = false) => {
+            if (!force && progress.percent < 100 && progressInterval > 0 && now() - lastEmitAt < progressInterval)
+                return;
+            lastEmitAt = now();
+            lastPhase = progress.phase;
+            try {
+                deps.onProgress?.(progress);
+            }
+            catch { /* 回调异常不影响事务 */ }
+        };
+        return {
+            report: (phase, message, percent) => {
+                const terminal = percent >= 100 || phase === 'success' || phase === 'failed';
+                const phaseChanged = phase !== lastPhase;
+                emit({ phase, message, percent, at: now() }, terminal || phaseChanged);
+            },
+        };
+    }
+    /**
+     * 轮询异步作业直到终态；支持外部信号与超时，超时给具名 code。
+     * `jobStatus` 与 `sleep` 都与中止信号 race，因此卡死的适配器也能被打断。
+     */
+    async function waitForJob(executor, jobId, timeoutMs, signal, onPoll) {
+        const startedAt = now();
+        const deadline = startedAt + timeoutMs;
+        const watch = watchAbort(signal);
+        let polls = 0;
+        try {
+            while (true) {
+                if (signal?.aborted)
+                    return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) };
+                polls += 1;
+                const status = await Promise.race([executor.jobStatus(jobId), watch.promise]);
+                if (status === ABORTED)
+                    return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) };
+                const state = String(status?.status ?? '');
+                if (state === 'completed' || state === 'failed') {
+                    return { ok: state === 'completed' && Number(status?.exitCode ?? 0) === 0, status, polls, elapsedMs: Math.max(0, now() - startedAt) };
+                }
+                try {
+                    onPoll?.(polls);
+                }
+                catch { /* ignore */ }
+                if (now() >= deadline)
+                    return { ok: false, code: 'job-timeout', status, polls, elapsedMs: Math.max(0, now() - startedAt) };
+                const remaining = deadline - now();
+                const slept = await Promise.race([sleep(Math.min(DEFAULTS.pollIntervalMs, Math.max(1, remaining))), watch.promise]);
+                if (slept === ABORTED)
+                    return { ok: false, code: 'aborted', polls, elapsedMs: Math.max(0, now() - startedAt) };
+            }
+        }
+        finally {
+            watch.cancel();
+        }
+    }
+    async function safeUpdate(input = {}) {
+        if (disposed) {
+            return { success: false, code: 'updater-disposed', message: 'updater was disposed', rolledBack: false, fatal: false, steps: [] };
+        }
+        const executor = requiredExecutor(deps.executor);
+        if (!executor)
+            return { success: false, code: 'executor-required', message: 'an executor with snapshot/restore/run is required; no VM is assumed', rolledBack: false, fatal: false, steps: [] };
+        const update = Array.isArray(input.update) && input.update.length > 0 ? input.update : null;
+        if (!update)
+            return { success: false, code: 'update-command-required', message: 'update argv is required', rolledBack: false, fatal: false, steps: [] };
+        const key = String(input.key ?? input.target ?? 'default');
+        if (running.has(key))
+            return { success: false, code: 'update-in-progress', message: `another update is already running for ${key}`, rolledBack: false, fatal: false, steps: [] };
+        const timeoutMs = positiveInt(input.timeoutMs, DEFAULTS.timeoutMs);
+        const smokeTimeoutMs = positiveInt(input.smokeTimeoutMs, DEFAULTS.smokeTimeoutMs);
+        const snapshotName = String(input.snapshotName ?? '').trim() || `pre-update-${now()}`;
+        const steps = [];
+        const record = (step, detail = {}) => { steps.push({ step, at: now(), ...detail }); };
+        const { report } = makeReporter();
+        // 三个中断源合并成一个内部控制器：外部 signal、整体超时、dispose()
+        const controller = new AbortController();
+        const signal = controller.signal;
+        const onExternalAbort = () => controller.abort(String(input.signal?.reason ?? 'external-abort'));
+        if (input.signal) {
+            if (input.signal.aborted)
+                controller.abort('external-abort');
+            else
+                input.signal.addEventListener('abort', onExternalAbort, { once: true });
+        }
+        const onLifecycleAbort = () => controller.abort('disposed');
+        lifecycle.signal.addEventListener('abort', onLifecycleAbort, { once: true });
+        const deadline = now() + timeoutMs;
+        const remaining = () => Math.max(1, deadline - now());
+        const timeoutTimer = setTimeout(() => controller.abort('timeout'), timeoutMs);
+        if (typeof timeoutTimer.unref === 'function')
+            timeoutTimer.unref();
+        const cleanupSignals = () => {
+            clearTimeout(timeoutTimer);
+            try {
+                input.signal?.removeEventListener?.('abort', onExternalAbort);
+            }
+            catch { /* ignore */ }
+            try {
+                lifecycle.signal.removeEventListener('abort', onLifecycleAbort);
+            }
+            catch { /* ignore */ }
+        };
+        const run = async () => {
+            const abortResult = (code, extra = {}) => ({
+                success: false, code, message: `update ${code}`, rolledBack: false, fatal: false, snapshotId: snapshotName, steps, ...extra,
+            });
+            if (signal.aborted)
+                return abortResult('aborted', { abortedBeforeSnapshot: true });
+            // ── Phase 1: snapshot ────────────────────────────────────────────────
+            report('snapshotting', '正在创建快照…', 5);
+            try {
+                const snapshot = await executor.snapshot(snapshotName);
+                if (snapshot && snapshot.ok === false) {
+                    record('snapshot', { ok: false, detail: snapshot });
+                    report('failed', '快照失败，已中止更新（环境未改动）', 100);
+                    return { success: false, code: 'snapshot-failed', message: 'snapshot failed; update aborted before any change', rolledBack: false, fatal: false, snapshotId: snapshotName, steps };
+                }
+                record('snapshot', { ok: true });
+                log('info', `[plugin-updater] snapshot ready: ${snapshotName}`);
+            }
+            catch (error) {
+                record('snapshot', { ok: false, error: String(error?.message ?? error) });
+                report('failed', '快照异常，已中止更新（环境未改动）', 100);
+                return { success: false, code: 'snapshot-threw', message: String(error?.message ?? error), rolledBack: false, fatal: false, snapshotId: snapshotName, steps };
+            }
+            const rollback = async (reason, message) => {
+                report('rolling-back', '更新失败，正在回滚…', 85);
+                let restored = null;
+                try {
+                    restored = await executor.restore(snapshotName);
+                }
+                catch (error) {
+                    restored = { ok: false, error: String(error?.message ?? error) };
+                }
+                const restoredOk = restored?.ok !== false;
+                record('restore', { ok: restoredOk, detail: restored });
+                if (!restoredOk) {
+                    const failure = { code: 'rollback-failed', message: `${reason}: rollback failed, manual intervention required`, snapshotId: snapshotName, steps };
+                    log('error', `[plugin-updater] FATAL rollback failed for ${snapshotName}: ${JSON.stringify(restored)}`);
+                    report('failed', '回滚失败，需要人工介入！', 100);
+                    try {
+                        deps.onFatal?.(failure);
+                    }
+                    catch { /* 告警钩子异常不改变结论 */ }
+                    return { success: false, ...failure, rolledBack: false, fatal: true };
+                }
+                if (Array.isArray(input.restart) && input.restart.length > 0) {
+                    try {
+                        const restarted = await executor.run(input.restart, { phase: 'restart' });
+                        record('restart', { ok: restarted?.ok !== false, detail: restarted });
+                    }
+                    catch (error) {
+                        record('restart', { ok: false, error: String(error?.message ?? error) });
+                    }
+                }
+                report('failed', '已回滚到更新前状态', 100);
+                log('warn', `[plugin-updater] rolled back after ${reason}`);
+                return { success: false, code: reason, message, rolledBack: true, fatal: false, snapshotId: snapshotName, steps };
+            };
+            if (signal.aborted)
+                return await rollback('aborted', 'update aborted before applying changes; snapshot discarded');
+            // ── Phase 2: update ─────────────────────────────────────────────────
+            report('updating', '正在执行更新…', 20);
+            try {
+                const updated = await executor.run(update, { phase: 'update', signal });
+                if (updated && updated.ok === false) {
+                    record('update', { ok: false, detail: updated });
+                    return await rollback('update-failed', 'update command failed; environment rolled back');
+                }
+                if (signal.aborted)
+                    return await rollback('aborted', 'update aborted by caller; environment rolled back');
+                if (updated && typeof updated.jobId === 'string' && updated.jobId) {
+                    const job = await waitForJob(executor, updated.jobId, Math.min(remaining(), timeoutMs), signal, (polls) => {
+                        report('updating', `等待更新作业…（第 ${polls} 次轮询）`, 20 + Math.min(45, polls * 2));
+                    });
+                    if (!job.ok) {
+                        record('update-job', { ok: false, code: job.code ?? 'job-failed', polls: job.polls, detail: job.status });
+                        if (job.code === 'aborted')
+                            return await rollback('aborted', 'update job aborted; environment rolled back');
+                        return await rollback(job.code === 'job-timeout' ? 'job-timeout' : 'update-job-failed', job.code === 'job-timeout' ? `update job timed out after ${timeoutMs}ms` : 'update job failed; environment rolled back');
+                    }
+                    record('update-job', { ok: true, polls: job.polls, elapsedMs: job.elapsedMs });
+                }
+                record('update', { ok: true, async: Boolean(updated?.jobId) });
+            }
+            catch (error) {
+                record('update', { ok: false, error: String(error?.message ?? error) });
+                return await rollback('update-threw', String(error?.message ?? error));
+            }
+            // ── Phase 3: smoke ──────────────────────────────────────────────────
+            if (Array.isArray(input.smoke) && input.smoke.length > 0) {
+                report('smoke-testing', '正在做冒烟测试…', 70);
+                try {
+                    const smoke = await executor.run(input.smoke, { phase: 'smoke', signal });
+                    if (smoke && smoke.ok === false) {
+                        record('smoke', { ok: false, detail: smoke });
+                        return await rollback('smoke-failed', 'smoke test failed after update; environment rolled back');
+                    }
+                    if (smoke && typeof smoke.jobId === 'string' && smoke.jobId) {
+                        const job = await waitForJob(executor, smoke.jobId, Math.min(remaining(), smokeTimeoutMs), signal, (polls) => {
+                            report('smoke-testing', `等待冒烟作业…（第 ${polls} 次轮询）`, 70 + Math.min(20, polls));
+                        });
+                        if (!job.ok) {
+                            record('smoke-job', { ok: false, code: job.code ?? 'job-failed', polls: job.polls });
+                            if (job.code === 'aborted')
+                                return await rollback('aborted', 'smoke test aborted; environment rolled back');
+                            return await rollback('smoke-failed', 'smoke test job failed; environment rolled back');
+                        }
+                        record('smoke-job', { ok: true, polls: job.polls });
+                    }
+                    record('smoke', { ok: true });
+                }
+                catch (error) {
+                    record('smoke', { ok: false, error: String(error?.message ?? error) });
+                    return await rollback('smoke-threw', String(error?.message ?? error));
+                }
+                // 冒烟期间被中止：不能把“刚好跑完”当成成功
+                if (signal.aborted)
+                    return await rollback('aborted', 'update aborted during smoke test; environment rolled back');
+            }
+            // ── Phase 4: success ────────────────────────────────────────────────
+            report('success', '更新完成，系统运行正常', 100);
+            if (input.keepSnapshotOnSuccess !== true && typeof executor.deleteSnapshot === 'function') {
+                try {
+                    await executor.deleteSnapshot(snapshotName);
+                    record('cleanup', { ok: true });
+                }
+                catch (error) {
+                    record('cleanup', { ok: false, error: String(error?.message ?? error) });
+                    log('warn', `[plugin-updater] snapshot cleanup failed: ${String(error?.message ?? error)}`);
+                }
+            }
+            log('info', '[plugin-updater] update succeeded');
+            return { success: true, code: 'updated', message: 'all plugins updated and verified', rolledBack: false, fatal: false, snapshotId: snapshotName, steps };
+        };
+        running.set(key, true);
+        try {
+            const result = await run();
+            return { ...result, phase: result.success ? 'success' : 'failed' };
+        }
+        finally {
+            running.delete(key);
+            cleanupSignals();
+        }
+    }
+    /** 宿主卸载时调用（通常包在 ctx.effect 里）：中止所有在跑的更新。 */
+    function dispose() {
+        if (disposed)
+            return { aborted: 0 };
+        disposed = true;
+        let aborted = 0;
+        try {
+            lifecycle.abort('disposed');
+        }
+        catch { /* ignore */ }
+        for (const key of running.keys()) {
+            running.delete(key);
+            aborted += 1;
+        }
+        log('info', `[plugin-updater] disposed; ${aborted} update(s) signalled to stop`);
+        return { aborted };
+    }
+    return {
+        safeUpdate,
+        isRunning: (key = 'default') => running.has(String(key)),
+        activeCount: () => running.size,
+        phases: UPDATE_PHASES,
+        dispose,
+    };
+}

package/dist-host/engine/safe-update.js

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck
+/**
+ * 快照 → 更新 → 冒烟 → 失败回滚（PluginSafeUpdater 的可编译实现）。
+ *
+ * 关键设计：**不假装有 VM**。执行能力由调用方注入一个 `executor`：
+ *
+ *   executor.snapshot(name)            → 建快照
+ *   executor.restore(name)             → 回滚到快照
+ *   executor.run(argv, options)        → 跑一条命令，返回 { ok, stdout, stderr, code }
+ *
+ * 房主本身没有 vm-sandbox；真实接入要么由瓮城的 VM 层提供 executor，
+ * 要么由宿主进程管理器提供。这里只保证**顺序、门禁与回滚语义**正确。
+ */
+function asString(value) { return String(value ?? '').trim(); }
+function executorOf(input) {
+    const executor = input && typeof input === 'object' ? input.executor : null;
+    if (!executor || typeof executor.snapshot !== 'function' || typeof executor.restore !== 'function' || typeof executor.run !== 'function') {
+        return null;
+    }
+    return executor;
+}
+/**
+ * @param {{
+ *   executor?: {snapshot:Function, restore:Function, run:Function},
+ *   snapshotName?: string,
+ *   update?: string[],        // 更新命令 argv
+ *   smoke?: string[],         // 冒烟命令 argv（可选）
+ *   restart?: string[],       // 回滚后重启命令 argv（可选）
+ *   now?: () => number,
+ * }} input
+ */
+export async function runSafeUpdate(input = {}) {
+    const executor = executorOf(input);
+    if (!executor) {
+        return { ok: false, code: 'executor-required', error: 'an executor with snapshot/restore/run is required; no VM is assumed' };
+    }
+    const now = typeof input.now === 'function' ? input.now : () => Date.now();
+    const snapshotName = asString(input.snapshotName) || `pre-update-${now()}`;
+    const steps = [];
+    const record = (step, detail) => { steps.push({ step, at: now(), ...detail }); };
+    // 1. 快照是硬前置：拿不到快照就不允许更新，否则失败时无法回滚。
+    try {
+        const snapshot = await executor.snapshot(snapshotName);
+        if (snapshot && snapshot.ok === false) {
+            record('snapshot', { ok: false, detail: snapshot });
+            return { ok: false, code: 'snapshot-failed', error: 'snapshot failed; refusing to update', snapshotName, steps };
+        }
+        record('snapshot', { ok: true });
+    }
+    catch (error) {
+        record('snapshot', { ok: false, error: String(error?.message ?? error) });
+        return { ok: false, code: 'snapshot-threw', error: String(error?.message ?? error), snapshotName, steps };
+    }
+    const rollback = async (reason, detail) => {
+        record('rollback-start', { reason });
+        let restored = null;
+        try {
+            restored = await executor.restore(snapshotName);
+        }
+        catch (error) {
+            restored = { ok: false, error: String(error?.message ?? error) };
+        }
+        record('restore', { ok: restored?.ok !== false, detail: restored });
+        if (Array.isArray(input.restart) && input.restart.length > 0) {
+            try {
+                const restarted = await executor.run(input.restart, { phase: 'restart' });
+                record('restart', { ok: restarted?.ok !== false, detail: restarted });
+            }
+            catch (error) {
+                record('restart', { ok: false, error: String(error?.message ?? error) });
+            }
+        }
+        return { ok: false, code: reason, error: detail, snapshotName, steps, rolledBack: restored?.ok !== false };
+    };
+    // 2. 更新
+    const update = Array.isArray(input.update) && input.update.length > 0 ? input.update : null;
+    if (!update)
+        return await rollback('update-command-required', 'update argv is required');
+    try {
+        const updated = await executor.run(update, { phase: 'update' });
+        if (updated && updated.ok === false) {
+            record('update', { ok: false, detail: updated });
+            return await rollback('update-failed', 'update command failed');
+        }
+        record('update', { ok: true });
+    }
+    catch (error) {
+        record('update', { ok: false, error: String(error?.message ?? error) });
+        return await rollback('update-threw', String(error?.message ?? error));
+    }
+    // 3. 冒烟（可选但推荐）：不通过同样回滚，绝不“更新成功但起不来”。
+    if (Array.isArray(input.smoke) && input.smoke.length > 0) {
+        try {
+            const smoke = await executor.run(input.smoke, { phase: 'smoke' });
+            if (smoke && smoke.ok === false) {
+                record('smoke', { ok: false, detail: smoke });
+                return await rollback('smoke-failed', 'smoke test failed after update');
+            }
+            record('smoke', { ok: true });
+        }
+        catch (error) {
+            record('smoke', { ok: false, error: String(error?.message ?? error) });
+            return await rollback('smoke-threw', String(error?.message ?? error));
+        }
+    }
+    return { ok: true, code: 'updated', snapshotName, steps, rolledBack: false };
+}
+/**
+ * 组合使用：切指针 + 健康检查 + 失败回滚。适合蓝绿切换后的验证。
+ * 指针切换成功但健康检查失败时，把指针切回旧目标。
+ */
+export async function switchAndVerify(input = {}) {
+    const { readPointer, switchWithRollback } = await import("./atomic-switch.js");
+    const { probeHealth } = await import("./health-probe.js");
+    // 先记住旧目标：健康检查失败时要切回它，而不是切到“刚切过去的新目标”。
+    const previous = await readPointer({ linkPath: input.linkPath, fs: input.fs });
+    const switched = await switchWithRollback({
+        linkPath: input.linkPath,
+        targetDir: input.targetDir,
+        fs: input.fs,
+        platform: input.platform,
+        now: input.now,
+    });
+    if (!switched.ok)
+        return { ok: false, code: switched.code, error: switched.error, switch: switched, health: null, previous };
+    const health = await probeHealth({
+        url: input.healthUrl,
+        fetchImpl: input.fetchImpl,
+        timeoutMs: input.timeoutMs,
+        intervalMs: input.intervalMs,
+        maxAttempts: input.maxAttempts,
+        now: input.now,
+        sleepImpl: input.sleepImpl,
+    });
+    if (health.ok)
+        return { ok: true, code: 'switched-and-healthy', switch: switched, health, previous };
+    if (!previous.ok || !previous.resolved) {
+        return { ok: false, code: 'health-failed-after-switch', switch: switched, health, previous, rollback: null };
+    }
+    const back = await switchWithRollback({
+        linkPath: input.linkPath,
+        targetDir: previous.resolved,
+        fs: input.fs,
+        platform: input.platform,
+        now: input.now,
+    }).catch((error) => ({ ok: false, error: String(error?.message ?? error) }));
+    return { ok: false, code: 'health-failed-after-switch', switch: switched, health, previous, rollback: back };
+}