@bolloon/bolloon-agent 0.4.33 → 0.5.0

package/dist/utils/update-manager.js

@@ -24,8 +24,10 @@ import * as fsp from 'fs/promises';
 import * as https from 'https';
 import * as http from 'http';
 import { spawnSync } from 'child_process';
-import { PKG_NAME, CONSTRAINT_PKG_NAME, NPM_REGISTRY_BASE, resolveUpdateChannel, distTagForChannel, detectInstallation, readPackageAt, } from './version-info.js';
+import { PKG_NAME, CONSTRAINT_PKG_NAME, NPM_REGISTRY_BASE, resolveUpdateChannel, distTagForChannel, detectInstallation, readPackageAt, channelKindOf, isDevIdentity, devShaFromIdentity, devIdentity, baseVersionOf, DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT, } from './version-info.js';
+import { fetchGithubFacts, toGithubReport, crossCheckStable, compareDevSnapshots, prepareDevSnapshot, renderGithubReportLine, } from './dual-source.js';
 import { readUpdateState, writeUpdateState, appendUpdateHistory, readUpdateHistory, acquireUpdateLock, releaseUpdateLock, readUpdateLock, lockIsStale, readUpdatePrefs, } from './update-state.js';
+export { DEV_CHANNEL_WARNING, DEV_BACK_TO_STABLE_HINT };
 // ── 版本比较 (唯一一份) ─────────────────────────────────────────────────────
 /**
  * 从子进程 stdout 里取 JSON —— **不要**按"行首是否 { "过滤:
@@ -133,31 +135,66 @@ export async function queryRegistryDoc(pkg = PKG_NAME, timeoutMs = 10000) {
         return { ok: false, ...classifyRegistryError(e) };
     }
 }
+/**
+ * 检查结论 → 退出码 (稳定约定, §2): 0 正常 / 2 检查不可用。
+ *
+ * §12.5 的核心就是这一句: **源不可达 / 版本不存在 → 拒绝并说清 (退出码 2)**,
+ * 不许静默装回旧版, 也不许打印"✅ 已是最新"。
+ */
+export function checkExitCode(status) {
+    switch (status) {
+        case 'offline':
+        case 'registry_unavailable':
+        case 'local_version_unknown':
+        case 'github_unavailable':
+        case 'cross_check_mismatch':
+            return 2;
+        default:
+            return 0;
+    }
+}
+/**
+ * "源不可达 / 版本不存在" 这一组结论 —— 它们必须**拒绝执行并说清**。
+ * 这是 §12.5 那一条的代码落点: 不许静默装回旧版, 也不许打印"已是最新"。
+ */
+export const REFUSED_STATUSES = ['offline', 'registry_unavailable', 'local_version_unknown', 'github_unavailable', 'cross_check_mismatch'];
 /**
  * 检查更新。**这是唯一的检查入口** —— CLI / 启动后台 / Python 检查器 / 安装脚本都走它。
  *
- * 结论优先级 (刻意定死, 防"模糊行为"):
+ * 结论优先级 (刻意定死, 防"模糊行为"; §12.3 在 stable 序列里插入两个双源结论):
  *   1. 读不到本地版本               → local_version_unknown (绝不默认 0.0.0 后继续)
  *   2. 安装方式不支持自动更新       → unsupported_installation (仍会带出 latestVersion)
  *   3. 显式跳过 / 节流              → check_skipped (结论来自缓存)
  *   4. 网络不可达                   → offline  (绝不显示"已是最新")
- *   5. registry 不可用 / 包不存在   → registry_unavailable
- *   6. latest > current             → update_available
- *   7. 否则                         → up_to_date
+ *   5. GitHub 不可达 (**dev 通道**) → github_unavailable (dev 只有这一个源, 拒绝)
+ *   6. registry 不可用 / 包不存在   → registry_unavailable
+ *   7. 两个源指向不同版本           → cross_check_mismatch (stable, 拒绝)
+ *   8. 有新版 (semver / dev 比 sha) → update_available
+ *   9. 否则                         → up_to_date
+ *
+ * 两套比较语义**显式分开** (§12.1): stable 比 semver; dev 比 commit sha (不碰 semver)。
  */
 export async function checkForUpdate(opts = {}) {
     const home = opts.home ?? (await import('../setup/setup-store.js')).resolveBolloonHome();
     const prefs = await readUpdatePrefs({ home, env: opts.env });
     const channel = resolveUpdateChannel(opts.channel || prefs.channel);
+    const channelKind = channelKindOf(channel);
     const install = opts.installation || detectInstallation({ home });
     const pkg = readPackageAt(install.packageRoot);
     const current = isKnownVersion(pkg?.version) ? String(pkg?.version) : 'unknown';
+    const currentBase = baseVersionOf(current);
+    /** 磁盘身份里就是 dev 快照的 sha —— 不从状态文件猜 */
+    const installedDevSha = devShaFromIdentity(current);
+    const installedChannel = installedDevSha ? 'dev' : 'stable';
     const now = new Date().toISOString();
     const state = await readUpdateState(home);
     const persist = opts.persist !== false;
+    /** 注入 registry = 受控检查 (GitHub 事实同样只认注入, 不打真网) */
+    const controlled = !!opts.registry;
     const base = {
         currentVersion: current,
         channel,
+        channelKind,
         source: install.updateSource,
         installMethod: install.method,
         checkedAt: now,
@@ -178,13 +215,22 @@ export async function checkForUpdate(opts = {}) {
                 lastCheckAt: r.checkedAt,
                 lastCheckStatus: r.status,
                 lastCheckReason: r.reason,
+                // 双源 (§12): 谁装的 / 哪个 sha / 能切回哪 / 两个源各给了什么
+                installedChannel: r.installedChannel ?? installedChannel,
+                installedDevSha: r.installedDevSha ?? null,
+                sourceFacts: r.sourceFacts ?? null,
+                switchableTo: r.switchableTo ?? null,
             }, home);
         }
         return r;
     };
     // 1. 本地版本读不到 —— 不猜
     if (!isKnownVersion(current)) {
-        return commit({ ...base, status: 'local_version_unknown', latestVersion: null, reason: `读不到 ${install.packageRoot}/package.json 的版本` });
+        return commit({
+            ...base, status: 'local_version_unknown', latestVersion: null,
+            installedChannel: null, installedDevSha: null,
+            reason: `读不到 ${install.packageRoot}/package.json 的版本`,
+        });
     }
     // 3. 显式跳过 / 节流
     const throttled = !opts.force && state.lastCheckAt
@@ -200,6 +246,9 @@ export async function checkForUpdate(opts = {}) {
             status: 'check_skipped',
             cachedStatus: cached,
             latestVersion: state.latestVersion,
+            installedChannel, installedDevSha,
+            switchableTo: state.switchableTo ?? null,
+            sourceFacts: state.sourceFacts ?? null,
             reason: opts.offline
                 ? `离线模式: 使用缓存结论 (${cached})`
                 : `距上次检查不足 ${prefs.checkIntervalHours}h, 使用缓存结论 (${cached})`,
@@ -209,38 +258,124 @@ export async function checkForUpdate(opts = {}) {
             await writeUpdateState({ lastCheckReason: r.reason }, home);
         return r;
     }
-    // 2. 安装方式不支持自动更新 —— 仍把 latest / 可回滚性带出来, 但结论就是"不支持"
-    const registry = opts.registry || await queryRegistryDoc(PKG_NAME);
+    // 两个源并行查 (受控检查里 GitHub 事实只认注入)
+    const [registry, githubRes] = await Promise.all([
+        opts.registry ? Promise.resolve(opts.registry) : queryRegistryDoc(PKG_NAME),
+        opts.github
+            ? Promise.resolve(opts.github)
+            : (controlled || opts.offline ? Promise.resolve(null) : fetchGithubFacts()),
+    ]);
     const latest = registry.ok ? (registry.doc.distTags[distTagForChannel(channel)] || registry.doc.latest) : null;
-    const targetPublishedOf = (v) => v && registry.ok ? registry.doc.versions.includes(v) : undefined;
-    const rollbackSupportedOf = registry.ok ? registry.doc.versions.includes(current) : undefined;
+    const githubReport = githubRes ? toGithubReport(githubRes) : null;
+    const sourceFacts = {
+        npm: registry.ok
+            ? { reachable: true, latest }
+            : { reachable: false, latest: null, detail: registry.detail },
+        github: githubReport
+            ? {
+                reachable: githubReport.reachable,
+                reason: githubReport.reason, detail: githubReport.detail, retryAt: githubReport.retryAt ?? null,
+                ref: githubReport.ref, headSha: githubReport.headSha, newestVersion: githubReport.newestVersion,
+                releases: githubReport.releases, tags: githubReport.tags,
+            }
+            : null,
+        crossCheck: null,
+    };
+    const targetPublishedOf = (v) => v && registry.ok ? registry.doc.versions.includes(baseVersionOf(v)) : undefined;
+    const rollbackSupportedOf = registry.ok ? registry.doc.versions.includes(currentBase) : undefined;
+    // 2. 安装方式不支持自动更新 —— 仍把 latest / 可回滚性带出来, 但结论就是"不支持"
     if (install.method === 'development' || install.method === 'unknown' || install.method === 'release-binary') {
         return commit({
             ...base, status: 'unsupported_installation', latestVersion: latest,
+            installedChannel, installedDevSha, github: githubReport, sourceFacts,
+            switchableTo: state.switchableTo ?? null,
             reason: `${install.reason}; 这种安装方式不支持自动更新`,
             targetPublished: targetPublishedOf(latest),
             rollbackSupported: rollbackSupportedOf,
         });
     }
-    // 4/5. registry 拿不到 —— 绝不显示"已是最新"
+    // ── dev 通道: git ref + commit sha (不碰 semver) ─────────────────────────
+    if (channelKind === 'git-ref') {
+        /** dev 的"一键回 stable"目标 = registry 上的 latest (§12.4 硬约束 3) */
+        const backToStable = { channel: 'stable', source: 'npm', target: latest };
+        const devBase = {
+            ...base, installedChannel, installedDevSha, github: githubReport,
+            switchableTo: backToStable, sourceFacts,
+        };
+        // dev 只有 GitHub 一个源 → 不可达就是**直接拒** (没有第二个源可退, §12.3)
+        if (!githubReport || !githubReport.reachable) {
+            const reason = githubReport?.reason || (opts.offline ? 'offline' : 'http_error');
+            const detail = githubReport?.detail
+                || (opts.offline ? '离线模式: 未查询 GitHub 源' : '本次未查询 GitHub 源 (受控检查未注入 GitHub 事实)');
+            return commit({
+                ...devBase, status: 'github_unavailable', latestVersion: null, dev: null, targetIdentity: null,
+                reason: `github_unavailable(${reason}): ${detail} — dev 通道只有 GitHub 一个源, 拒绝安装 (不回落到 stable 装一个 npm 版本)`,
+            });
+        }
+        if (!githubReport.headSha) {
+            return commit({
+                ...devBase, status: 'github_unavailable', latestVersion: null, dev: null, targetIdentity: null,
+                reason: `github_unavailable(not_found): GitHub 上没有 refs/heads/master 或读不到 HEAD — 拒绝安装一个身份不明的快照`,
+            });
+        }
+        const dev = compareDevSnapshots(installedDevSha, githubReport.headSha, githubReport.ref);
+        const targetIdentity = devIdentity(currentBase, githubReport.headSha);
+        const common = {
+            ...devBase, dev, targetIdentity, latestVersion: targetIdentity, targetPublished: true,
+            rollbackSupported: rollbackSupportedOf,
+        };
+        if (dev.same)
+            return commit({ ...common, status: 'up_to_date', reason: dev.detail });
+        return commit({
+            ...common, status: 'update_available',
+            reason: `${dev.detail}${registry.ok ? '' : ` · 注意: registry 不可达 (${registry.detail}) — 回 stable 会需要它`}`,
+        });
+    }
+    // ── stable 通道: npm 是权威, GitHub 是交叉校验 (§12.1) ───────────────────
+    // 4/5. registry 拿不到 —— 绝不显示"已是最新" (GitHub 的事实一并摆出来, 方便判断是哪一源的问题)
     if (!registry.ok) {
         return commit({
             ...base,
             status: registry.kind === 'offline' ? 'offline' : 'registry_unavailable',
             latestVersion: null,
-            reason: registry.detail,
+            installedChannel, installedDevSha, github: githubReport, sourceFacts,
+            switchableTo: state.switchableTo ?? null,
+            reason: `${registry.detail}${githubReport ? ` · ${renderGithubReportLine(githubReport)}` : ''}`,
         });
     }
+    const crossCheck = githubRes && githubRes.ok ? crossCheckStable(latest, githubRes.facts) : null;
+    sourceFacts.crossCheck = crossCheck ? { kind: crossCheck.kind, blocking: crossCheck.blocking, detail: crossCheck.detail } : null;
+    const switchableTo = installedDevSha
+        ? { channel: 'stable', source: 'npm', target: latest }
+        : { channel: 'dev', source: 'github', target: githubReport?.headSha ? githubReport.headSha.slice(0, 7) : null };
+    const stableBase = {
+        ...base, installedChannel, installedDevSha, github: githubReport, crossCheck, sourceFacts, switchableTo,
+    };
     const targetPublished = !!latest && registry.doc.versions.includes(latest);
     const rollbackSupported = rollbackSupportedOf === true;
-    // 6/7. 比较
-    if (latest && compareVersions(current, latest) < 0) {
+    // 7. 两个源指向不同版本 → 拒绝 (不许按 GitHub 的记录去装)
+    if (crossCheck?.kind === 'mismatch') {
         return commit({
-            ...base, status: 'update_available', latestVersion: latest, targetPublished, rollbackSupported,
-            reason: `当前 ${current} → 目标 ${latest}`,
+            ...stableBase, status: 'cross_check_mismatch', latestVersion: latest,
+            targetPublished, rollbackSupported,
+            reason: `cross_check_mismatch: ${crossCheck.detail} (npm latest=${latest} / GitHub ${crossCheck.githubVersion || '无记录'})`,
         });
     }
-    return commit({ ...base, status: 'up_to_date', latestVersion: latest, targetPublished, rollbackSupported });
+    // 8/9. 比较: 当前是 dev 快照时**显式**判"切回 stable", 而不是拿 semver 硬比
+    if (isDevIdentity(current)) {
+        return commit({
+            ...stableBase, status: 'update_available', latestVersion: latest,
+            targetPublished, rollbackSupported,
+            reason: `当前装的是 dev 快照 ${current} → 切回 stable 的 ${latest || '未知'} (一键: ${DEV_BACK_TO_STABLE_HINT})`,
+        });
+    }
+    if (latest && compareVersions(currentBase, latest) < 0) {
+        return commit({
+            ...stableBase, status: 'update_available', latestVersion: latest, targetPublished, rollbackSupported,
+            reason: `当前 ${current} → 目标 ${latest}${crossCheck ? ` · 交叉校验: ${crossCheck.kind}` : ''}`,
+        });
+    }
+    return commit({ ...stableBase, status: 'up_to_date', latestVersion: latest, targetPublished, rollbackSupported });
 }
 const WILL_NOT_TOUCH = [
     '~/.bolloon/config.json',
@@ -362,6 +497,7 @@ export async function buildUpdatePlan(opts = {}) {
     const home = opts.home ?? (await import('../setup/setup-store.js')).resolveBolloonHome();
     const install = opts.installation || detectInstallation({ home });
     const check = await checkForUpdate({ ...opts, home, persist: false, installation: install });
+    const isDev = check.channelKind === 'git-ref';
     const risk = [
         ...await collectInstallRisk(install),
         ...(opts.workloadRiskOverride || await collectWorkloadRisk()),
@@ -376,6 +512,33 @@ export async function buildUpdatePlan(opts = {}) {
             : check.status === 'registry_unavailable' ? `registry 不可用: ${check.reason}`
                 : 'npm registry 可达',
     });
+    /**
+     * GitHub 侧风险 (§12.3) —— **dev 通道阻塞, stable 通道只提醒**:
+     * dev 只有 GitHub 一个源, 不可达就没有"退回哪去"这件事; stable 的权威是 npm, GitHub 只是交叉校验源。
+     */
+    const gh = check.github;
+    risk.push({
+        id: 'github_reachable',
+        label: 'GitHub 源可达 (dev 通道的源 / stable 的交叉校验源)',
+        ok: !gh ? true : gh.reachable,
+        blocking: isDev && (!gh || !gh.reachable),
+        advisory: !isDev,
+        detail: !gh
+            ? '未查询 GitHub 源 (离线或受控检查未注入)'
+            : gh.reachable
+                ? `可达 · master HEAD ${gh.headSha ? gh.headSha.slice(0, 7) : '未知'} · Release ${gh.releases ?? 0} 个 · Tag ${gh.tags ?? 0} 个`
+                : `github_unavailable(${gh.reason}): ${gh.detail || ''}${gh.retryAt ? ` (限流重试 ${gh.retryAt})` : ''}`,
+    });
+    risk.push({
+        id: 'cross_check',
+        label: '两个源指向同一版本 (npm ↔ GitHub)',
+        ok: check.crossCheck ? check.crossCheck.kind !== 'mismatch' : true,
+        blocking: !!check.crossCheck?.blocking,
+        advisory: check.crossCheck?.kind === 'missing_record' || check.crossCheck?.kind === 'no_record_at_all',
+        detail: !check.crossCheck
+            ? (isDev ? 'dev 通道不看 npm (GitHub 是唯一源)' : '未做交叉校验 (GitHub 源未查)')
+            : check.crossCheck.detail,
+    });
     risk.push({
         id: 'target_published',
         label: '目标版本真实存在',
@@ -391,24 +554,36 @@ export async function buildUpdatePlan(opts = {}) {
         ok: check.rollbackSupported !== false,
         blocking: false,
         detail: check.rollbackSupported === false
-            ? `registry 上找不到当前版本 ${check.currentVersion} — 更新失败将无法用 npm 回滚`
-            : check.rollbackSupported === true ? `registry 上存在 ${check.currentVersion} (可回滚)` : '未检查 (离线)',
+            ? `registry 上找不到当前版本 ${baseVersionOf(check.currentVersion)} — 更新失败将无法用 npm 回滚`
+            : check.rollbackSupported === true ? `registry 上存在 ${baseVersionOf(check.currentVersion)} (可回滚)` : '未检查 (离线)',
     });
     const blockers = risk.filter((r) => !r.ok && r.blocking).map((r) => `${r.label}: ${r.detail}`);
     const advisories = risk.filter((r) => !r.ok && !r.blocking).map((r) => `${r.label}: ${r.detail}`);
-    const target = check.latestVersion && compareVersions(check.currentVersion, check.latestVersion) < 0
-        ? check.latestVersion
+    const target = check.status === 'update_available'
+        ? (check.targetIdentity || check.latestVersion || null)
         : null;
+    const warnings = [];
+    if (isDev) {
+        warnings.push(DEV_CHANNEL_WARNING);
+        warnings.push(DEV_BACK_TO_STABLE_HINT);
+    }
+    if (check.installedDevSha && !isDev)
+        warnings.push(`当前装的是 dev 快照 (commit ${check.installedDevSha}), 本次要切回 stable: 会把 GitHub master 快照换成 registry 上的 latest`);
     return {
         ok: blockers.length === 0 && !!target,
         currentVersion: check.currentVersion,
         targetVersion: target,
         channel: check.channel,
+        channelKind: check.channelKind || channelKindOf(check.channel),
+        targetIdentity: check.targetIdentity ?? null,
+        warnings,
         installMethod: check.installMethod,
         source: check.source,
         installDir: install.installDir,
         needsRestart: !!target,
-        willUpdate: target && install.method === 'npm-global' ? [PKG_NAME, CONSTRAINT_PKG_NAME] : [],
+        willUpdate: target && install.method === 'npm-global'
+            ? (isDev ? [`GitHub master 快照 ${check.github?.headSha?.slice(0, 7) || ''} (身份 ${target})`, PKG_NAME] : [PKG_NAME, CONSTRAINT_PKG_NAME])
+            : [],
         willNotTouch: WILL_NOT_TOUCH,
         risk, blockers, advisories,
         strategies: ['now', 'wait', 'cancel'],
@@ -418,10 +593,18 @@ export async function buildUpdatePlan(opts = {}) {
 }
 export function renderUpdatePlan(plan) {
     const L = [];
-    L.push(`当前版本: ${plan.currentVersion}`);
+    L.push(`当前版本: ${plan.currentVersion}${plan.check.installedDevSha ? ` (dev 快照 commit ${plan.check.installedDevSha})` : ''}`);
     L.push(`目标版本: ${plan.targetVersion || '(无可用更新)'}`);
     L.push(`安装方式: ${plan.installMethod}`);
-    L.push(`更新通道: ${plan.channel} (来源: ${plan.source})`);
+    L.push(`更新通道: ${plan.channel} (比较语义: ${plan.channelKind})`);
+    L.push(`更新来源: ${plan.source}${plan.channelKind === 'git-ref' ? ' · GitHub master (唯一源)' : ' · npm registry (权威) + GitHub (交叉校验)'}`);
+    L.push(renderGithubReportLine(plan.check.github));
+    if (plan.check.crossCheck)
+        L.push(`交叉校验: ${plan.check.crossCheck.kind}${plan.check.crossCheck.blocking ? ' (阻塞)' : ''} — ${plan.check.crossCheck.detail}`);
+    if (plan.check.dev)
+        L.push(`dev 快照: ${plan.check.dev.detail}`);
+    for (const w of plan.warnings)
+        L.push(w);
     L.push(`安装目录: ${plan.installDir}`);
     L.push('');
     L.push('将更新:');
@@ -452,7 +635,9 @@ export function renderUpdatePlan(plan) {
         L.push(`  建议策略: 等当前 Run 结束后更新 (bolloon update --now --wait)`);
     }
     L.push('');
-    L.push('可选: 立即更新 (bolloon update --now) / 等当前 Run 结束 (bolloon update --now --wait) / 取消');
+    L.push(`可选: 立即更新 (bolloon update --now --channel ${plan.channel}) / 等当前 Run 结束 (bolloon update --now --wait --channel ${plan.channel}) / 取消`);
+    if (plan.channelKind === 'git-ref')
+        L.push(`一键回稳定版: bolloon update now --channel stable`);
     L.push(`默认: ${plan.defaultStrategy === 'wait' ? '等待当前 Run 结束后更新' : '立即更新'}`);
     return L.join('\n');
 }
@@ -517,21 +702,44 @@ export async function applyUpdate(opts = {}) {
     };
     const plan = await buildUpdatePlan({
         home, env: opts.env, force: true, installation: install, registry: opts.registry,
+        github: opts.github, channel: opts.channel,
         workloadRiskOverride: opts.workloadRiskOverride,
     });
     const from = plan.currentVersion;
     const to = plan.targetVersion || plan.currentVersion;
+    const isDev = plan.channelKind === 'git-ref';
+    /** dev 的目标 commit (身份就是它, 不是版本号) */
+    const devSha = plan.check.dev?.headSha || plan.check.github?.headSha || null;
     const record = async (r, historyStatus) => {
         const rec = { at: new Date().toISOString(), from: r.from, to: r.to, status: historyStatus, durationMs: r.durationMs, reason: r.reason };
         // 记账失败**不能**把"更新其实成功了"变成向上抛异常 (真被测试 teardown 竞态抓到过:
         // HOME 在写到一半时消失 → rename ENOENT)。失败就如实记进 reason, 结果照常返回。
         try {
             await appendUpdateHistory(rec, home);
+            /**
+             * 双源落盘 (§12.4 硬约束 2): 装成 dev 时记下 `{channel, devSha, devRef, checkedAt}`;
+             * 切回 stable 时把安装通道改回 stable 并把 dev 记录保留成"上次那个 dev 快照"。
+             */
+            const dualSource = isDev && r.ok
+                ? {
+                    installedChannel: 'dev',
+                    installedDevSha: devSha ? devSha.slice(0, 7) : devShaFromIdentity(r.to),
+                    devSha: devSha || null,
+                    devRef: `refs/heads/master`,
+                    devCheckedAt: rec.at,
+                    switchableTo: { channel: 'stable', source: 'npm', target: baseVersionOf(r.from) },
+                }
+                : {};
+            const backToStable = !isDev && r.ok
+                ? { installedChannel: 'stable', installedDevSha: null, switchableTo: { channel: 'dev', source: 'github', target: devSha ? devSha.slice(0, 7) : null } }
+                : {};
             await writeUpdateState({
                 lastUpdate: rec,
                 lastFailure: r.ok ? null : { at: rec.at, stage: r.failedAt || r.stage, reason: r.reason || '未知原因' },
                 needsRestart: r.ok ? r.needsRestart : false,
                 currentVersion: r.from,
+                ...dualSource,
+                ...backToStable,
             }, home);
         }
         catch (e) {
@@ -541,8 +749,16 @@ export async function applyUpdate(opts = {}) {
         return r;
     };
     if (!plan.targetVersion) {
-        await stage('blocked', '没有可执行的更新');
-        return record({ stage: 'blocked', ok: false, from, to, durationMs: Date.now() - started, reason: plan.blockers[0] || '已是最新, 无需更新', needsRestart: false }, 'blocked');
+        /**
+         * §12.5 的核心分流: **源不可达 / 版本不存在 → 拒绝并说清**,
+         * 绝不把"没查到"说成"已是最新"。
+         */
+        const refused = REFUSED_STATUSES.includes(plan.check.status);
+        await stage('blocked', refused ? `拒绝更新 (${plan.check.status})` : '没有可执行的更新');
+        const reason = refused
+            ? `拒绝更新 (${plan.check.status}): ${plan.check.reason || plan.blockers[0] || '源不可达 / 版本不存在'}`
+            : (plan.blockers[0] || '已是最新, 无需更新');
+        return record({ stage: 'blocked', ok: false, from, to, durationMs: Date.now() - started, reason, needsRestart: false }, 'blocked');
     }
     if (plan.blockers.length > 0) {
         await stage('blocked', plan.blockers.join('; '));
@@ -564,42 +780,79 @@ export async function applyUpdate(opts = {}) {
     const tmpRoot = await fsp.mkdtemp(path.join(os.tmpdir(), 'bolloon-update-'));
     const runNpm = opts.runNpm || defaultRunNpm;
     let stagedTarball = null;
+    /** 切换时交给 npm 的安装目标: stable = `<包>@<semver>`; dev = 本地 dev 快照 tarball */
+    let switchSpec = `${PKG_NAME}@${to}`;
+    /**
+     * 实际装入的身份。dev 的身份来自**源码树的 package.json + master sha**, 可能与检查阶段的预测
+     * 略有差别 (源码树的版本号才是真的) → 以产物为准, 校验/验证/记账都用它, 不用预测值糊过去。
+     */
+    let effectiveTo = to;
     try {
-        // 1. 下载 tarball 到临时目录 (不动现有安装)
-        await stage('downloading', `npm pack ${PKG_NAME}@${to}`);
-        const packed = runNpm(['pack', `${PKG_NAME}@${to}`, '--pack-destination', tmpRoot, '--loglevel=error'], tmpRoot);
-        if (packed.code !== 0) {
-            throw Object.assign(new Error(`下载 ${PKG_NAME}@${to} 失败: ${(packed.stderr || packed.stdout).trim().slice(0, 400)}`), { stage: 'downloading' });
+        // 1. 取产物到临时目录 (不动现有安装)
+        if (isDev) {
+            // dev: 源是 GitHub master 的 git ref, 身份是 commit sha (§12.1)
+            if (!devSha) {
+                throw Object.assign(new Error('dev 通道没有拿到 master HEAD 的 commit sha — 拒绝安装一个身份不明的快照'), { stage: 'downloading' });
+            }
+            await stage('downloading', `取 GitHub master @ ${devSha.slice(0, 7)} (${DEV_BACK_TO_STABLE_HINT})`);
+            const snap = opts.devSnapshot
+                ? { ok: true, tarball: opts.devSnapshot.tarball, identity: opts.devSnapshot.identity, sha: opts.devSnapshot.sha, source: 'injected', built: false, dir: '' }
+                : await prepareDevSnapshot({
+                    sha: devSha, workDir: tmpRoot, env: opts.env,
+                    runNpm,
+                    onStage: (s, d) => { try {
+                        opts.onStage?.(s, d);
+                    }
+                    catch { /* 回调失败不影响流程 */ } },
+                });
+            if (!snap.ok) {
+                const kind = 'kind' in snap ? String(snap.kind) : 'dev_source_failed';
+                const reason = 'reason' in snap ? String(snap.reason) : '';
+                const detail = 'detail' in snap ? String(snap.detail) : '未知原因';
+                throw Object.assign(new Error(`${kind}/${reason}: ${detail}`), { stage: 'downloading' });
+            }
+            stagedTarball = snap.tarball;
+            switchSpec = snap.tarball;
+            effectiveTo = snap.identity;
+            await stage('staged', `dev 快照身份 ${snap.identity} (来源 ${snap.source}${snap.built ? ', 已现场构建' : ''})`);
         }
-        const tarballs = (await fsp.readdir(tmpRoot)).filter((f) => f.endsWith('.tgz'));
-        if (tarballs.length === 0)
-            throw Object.assign(new Error('npm pack 没有产出 tarball'), { stage: 'downloading' });
-        stagedTarball = path.join(tmpRoot, tarballs[0]);
-        // 2. 解压 + 校验包内容 (版本 + 入口)
-        await stage('staged', `解压并校验 ${path.basename(stagedTarball)}`);
+        else {
+            await stage('downloading', `npm pack ${PKG_NAME}@${to}`);
+            const packed = runNpm(['pack', `${PKG_NAME}@${to}`, '--pack-destination', tmpRoot, '--loglevel=error'], tmpRoot);
+            if (packed.code !== 0) {
+                throw Object.assign(new Error(`下载 ${PKG_NAME}@${to} 失败: ${(packed.stderr || packed.stdout).trim().slice(0, 400)}`), { stage: 'downloading' });
+            }
+            const tarballs = (await fsp.readdir(tmpRoot)).filter((f) => f.endsWith('.tgz'));
+            if (tarballs.length === 0)
+                throw Object.assign(new Error('npm pack 没有产出 tarball'), { stage: 'downloading' });
+            stagedTarball = path.join(tmpRoot, tarballs[0]);
+        }
+        // 2. 解压 + 校验包内容 (版本 + 入口) —— 两个源共用同一条校验
+        if (!isDev)
+            await stage('staged', `解压并校验 ${path.basename(stagedTarball)}`);
         const extractDir = path.join(tmpRoot, 'extract');
         await fsp.mkdir(extractDir, { recursive: true });
         const tar = spawnSync('tar', ['-xzf', stagedTarball, '-C', extractDir], { encoding: 'utf-8', timeout: 120_000 });
         if (tar.status !== 0)
             throw Object.assign(new Error(`解压失败: ${(tar.stderr || '').slice(0, 300)}`), { stage: 'staged' });
-        const stagedCheck = validateStagedPackage(path.join(extractDir, 'package'), to);
+        const stagedCheck = validateStagedPackage(path.join(extractDir, 'package'), effectiveTo);
         if (!stagedCheck.ok)
             throw Object.assign(new Error(`目标包校验失败: ${stagedCheck.detail}`), { stage: 'staged' });
-        // 3. 切换 (npm 完成替换; 旧版本在替换成功前不会消失)
-        await stage('switching', `npm install -g ${PKG_NAME}@${to}`);
-        const installed = runNpm(['install', '-g', `${PKG_NAME}@${to}`, '--no-fund', '--no-audit', '--loglevel=error'], os.tmpdir());
+        // 3. 切换 (npm 完成替换; 旧版本在替换成功前不会消失) —— 两个源共用同一条替换路径
+        await stage('switching', isDev ? `npm install -g <dev 快照 ${path.basename(switchSpec)}>` : `npm install -g ${PKG_NAME}@${to}`);
+        const installed = runNpm(['install', '-g', switchSpec, '--no-fund', '--no-audit', '--loglevel=error'], os.tmpdir());
         if (installed.code !== 0) {
             throw Object.assign(new Error(`npm 安装失败: ${(installed.stderr || installed.stdout).trim().slice(0, 400)}`), { stage: 'switching' });
         }
         // 4. 验证: 磁盘版本 + 新入口真能启动 + 健康检查
         await stage('verifying', '核对磁盘版本并试启新入口');
         const verify = opts.verifyInstall || defaultVerifyInstall;
-        const ok = await verify(to, home);
+        const ok = await verify(effectiveTo, home);
         if (!ok)
-            throw Object.assign(new Error(`切换后验证失败: 新版本 ${to} 未能正确启动`), { stage: 'verifying' });
-        await stage('succeeded', `已更新到 ${to}`);
+            throw Object.assign(new Error(`切换后验证失败: 新版本 ${effectiveTo} 未能正确启动`), { stage: 'verifying' });
+        await stage('succeeded', `已更新到 ${effectiveTo}`);
         const out = {
-            stage: 'succeeded', ok: true, from, to, durationMs: Date.now() - started, needsRestart: true, stagedTarball,
+            stage: 'succeeded', ok: true, from, to: effectiveTo, durationMs: Date.now() - started, needsRestart: true, stagedTarball,
         };
         await record(out, 'succeeded');
         return out;
@@ -609,25 +862,26 @@ export async function applyUpdate(opts = {}) {
         const reason = e?.message || String(e);
         await stage(failureStage, reason);
         // 失败处理: 保留旧版本 → 能回滚就回滚 → 写原因 → 释放锁
+        const fromBase = baseVersionOf(from);
         let finalStage = 'failed';
         let finalReason = reason;
         try {
             const nowVersion = installedVersionOnDisk(install.packageRoot);
-            if (install.method === 'npm-global' && nowVersion && nowVersion !== from && nowVersion !== to) {
-                await stage('rolled_back', `检测到半更新 (磁盘版本 ${nowVersion}), 回滚到 ${from}`);
-                const rb = runNpm(['install', '-g', `${PKG_NAME}@${from}`, '--no-fund', '--no-audit', '--loglevel=error'], os.tmpdir());
+            if (install.method === 'npm-global' && nowVersion && nowVersion !== from && nowVersion !== effectiveTo) {
+                await stage('rolled_back', `检测到半更新 (磁盘版本 ${nowVersion}), 回滚到 ${fromBase}`);
+                const rb = runNpm(['install', '-g', `${PKG_NAME}@${fromBase}`, '--no-fund', '--no-audit', '--loglevel=error'], os.tmpdir());
                 const after = installedVersionOnDisk(install.packageRoot);
-                if (rb.code === 0 && after === from) {
+                if (rb.code === 0 && after === fromBase) {
                     finalStage = 'rolled_back';
-                    finalReason = `${reason}; 已回滚到 ${from}`;
+                    finalReason = `${reason}; 已回滚到 ${fromBase}`;
                 }
                 else {
-                    finalReason = `${reason}; 回滚也未成功 (磁盘版本 ${after || 'unknown'}) — 请手动: npm install -g ${PKG_NAME}@${from}`;
+                    finalReason = `${reason}; 回滚也未成功 (磁盘版本 ${after || 'unknown'}) — 请手动: npm install -g ${PKG_NAME}@${fromBase}`;
                 }
             }
-            else if (nowVersion === to && failureStage === 'verifying') {
+            else if (nowVersion === effectiveTo && failureStage === 'verifying') {
                 // 装上了但验证没过: 保留新版本但如实报失败, 并给出回滚指令
-                finalReason = `${reason}; 磁盘版本已是 ${to}, 如需回退: npm install -g ${PKG_NAME}@${from}`;
+                finalReason = `${reason}; 磁盘版本已是 ${effectiveTo}, 如需回退: npm install -g ${PKG_NAME}@${fromBase}`;
             }
         }
         catch (e2) {
@@ -668,12 +922,26 @@ export async function readUpdateStatus(opts = {}) {
     const st = await readUpdateState(home);
     const prefs = await readUpdatePrefs({ home, env: opts.env });
     const lock = readUpdateLock(home);
-    const install = detectInstallation({ home });
+    const install = opts.installation || detectInstallation({ home });
     const pkg = readPackageAt(install.packageRoot);
+    const currentVersion = isKnownVersion(pkg?.version) ? String(pkg?.version) : st.currentVersion;
+    const installedDevSha = devShaFromIdentity(currentVersion);
+    const channel = resolveUpdateChannel(opts.channel || prefs.channel);
     return {
-        currentVersion: isKnownVersion(pkg?.version) ? String(pkg?.version) : st.currentVersion,
+        currentVersion,
+        // 安装通道从**磁盘身份**判定 (不从状态文件猜); 状态里的 dev 记录另外带出来做历史
+        installedChannel: installedDevSha ? 'dev' : 'stable',
+        installedDevSha,
+        switchableTo: st.switchableTo ?? (installedDevSha
+            ? { channel: 'stable', source: 'npm', target: st.latestVersion }
+            : { channel: 'dev', source: 'github', target: null }),
+        lastDevSha: st.devSha ?? null,
+        devRef: st.devRef ?? null,
+        devCheckedAt: st.devCheckedAt ?? null,
+        sourceFacts: st.sourceFacts ?? null,
         latestVersion: st.latestVersion,
-        channel: prefs.channel,
+        channel,
+        channelKind: channelKindOf(channel),
         installMethod: install.method,
         installDir: install.installDir,
         entryPath: install.entryPath,
@@ -712,5 +980,9 @@ export async function updateSummaryFor(home) {
         latestVersion: st.latestVersion,
         lastUpdate: st.lastUpdate ? { at: st.lastUpdate.at, from: st.lastUpdate.from, to: st.lastUpdate.to, status: st.lastUpdate.status, reason: st.lastUpdate.reason } : null,
         needsRestart: st.needsRestart,
+        // 双源 (§12.5): "我装的是哪个源 / 哪个 commit / 能切回哪" 从同一份状态读
+        installedChannel: st.installedChannel ?? null,
+        installedDevSha: st.installedChannel === 'dev' ? (st.installedDevSha ?? null) : null,
+        switchableTo: st.switchableTo ?? null,
     };
 }

package/dist/utils/update-state.js

@@ -18,7 +18,13 @@ import * as fs from 'fs';
 import * as fsp from 'fs/promises';
 import { resolveBolloonHome } from '../setup/setup-store.js';
 // ── 枚举 (冻结: 出口/状态都不许临时造词) ────────────────────────────────────
-/** 一次"检查"的结论。7 个值就是全部, 不认识的一律落进 registry_unavailable 并带原因。 */
+/**
+ * 一次"检查"的结论。**9 个值就是全部**, 不认识的一律落进 registry_unavailable 并带原因。
+ *
+ * 2026-09-25 (update-protocol §12.3, 双源): **只增不改** —— 新增 2 个, 错误分类**不合并**:
+ *   github_unavailable     GitHub 不可达 / 403·429 限流 / 没有 Release / 没有 master
+ *   cross_check_mismatch   stable 下 npm 与 GitHub 指向不同版本 (两个源的事实都摆出来)
+ */
 export const CHECK_STATUSES = [
     'up_to_date', // 确认最新
     'update_available', // 有新版本
@@ -27,6 +33,8 @@ export const CHECK_STATUSES = [
     'registry_unavailable', // 可达但拿不到有效数据 (5xx / 包不存在 / 无 dist-tags)
     'local_version_unknown', // 读不到本地版本 (不猜 0.0.0)
     'unsupported_installation', // 认得出本地版本, 但这种安装方式不支持自动更新
+    'github_unavailable', // GitHub 源不可用 (offline / rate_limited / not_found / http_error)
+    'cross_check_mismatch', // npm 与 GitHub 两个源不一致 → 拒绝更新
 ];
 /** 一次"更新执行"的流水线状态。 */
 export const UPDATE_RUN_STATUSES = [
@@ -72,6 +80,13 @@ export function emptyUpdateState(now = new Date()) {
         autoRestart: false,
         needsRestart: false,
         updatedAt: now.toISOString(),
+        installedChannel: null,
+        installedDevSha: null,
+        devSha: null,
+        devRef: null,
+        devCheckedAt: null,
+        sourceFacts: null,
+        switchableTo: null,
     };
 }
 // ── 读写 (原子) ─────────────────────────────────────────────────────────────