@bolloon/bolloon-agent 0.4.24 → 0.4.26

package/dist/agents/supervisor-host.js

@@ -0,0 +1,249 @@
+/**
+ * supervisor-host.ts — Supervisor 的「宿主分离」层 (2026-09-16, 批次 2-C.1)
+ *
+ * 之前的问题: Supervisor 的**启动点**长在 web server 里, 执行器也直接引用 web 的 channel agent
+ * → 长期执行能力事实上依附于「web 进程还活着」。
+ *
+ * 这一层把两件事彻底分开:
+ *   执行器 (runner)   ← 由 RunnerResolver 在**每次执行前**解析 (web agent / CLI agent / 独立 agent / fake)
+ *   启动宿主 (host)   ← web server / CLI `/supervise` / 独立 `bolloon supervise` / 测试进程, 都只是 host
+ *
+ * 冻结的接口:
+ *   Supervisor { scheduler · lease · reducer · wake } + runnerResolver
+ *   resolver 解析不出来 → **只诊断不执行, 且不写任何 Goal 状态** (绝不假装跑过, 也绝不误判完成)
+ *
+ * 宿主身份与状态落盘 (~/.bolloon/supervisor.json): owner / workerId / pid / host / 启动时间 /
+ * 最近 tick / tick 次数 / runner 种类 / 优雅停止时间 —— 让"谁在跑、跑到哪、为什么停"可查。
+ */
+import * as os from 'os';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { acquireTickLock } from '../cron/tick-lock.js';
+export function supervisorDir(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'supervisor');
+}
+export function supervisorStatePath(home = os.homedir()) {
+    return path.join(home, '.bolloon', 'supervisor.json');
+}
+/** Supervisor tick 的跨进程锁 (与 cron 的 tick 锁同语义, 但不共用文件) */
+export function supervisorTickLockPath(home = os.homedir()) {
+    return path.join(supervisorDir(home), '.tick.lock');
+}
+export async function readSupervisorState(home = os.homedir()) {
+    try {
+        return JSON.parse(await fsp.readFile(supervisorStatePath(home), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeSupervisorState(state, home = os.homedir()) {
+    const p = supervisorStatePath(home);
+    await fsp.mkdir(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp`;
+    await fsp.writeFile(tmp, JSON.stringify(state, null, 2), 'utf8');
+    await fsp.rename(tmp, p); // 原子替换, 避免读到半截状态
+}
+export function newWorkerId() {
+    return `${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+/**
+ * 启动一个 Supervisor 宿主。
+ * 语义要点:
+ *   - **跨进程单 tick 互斥**: 拿不到 tick 锁的宿主本轮直接让路 (不阻塞不排队), 并如实记原因;
+ *   - **优雅停止**: stop() 会等当前 tick 跑完再退出 (不半路丢状态), 并落 stoppedAt/stopReason;
+ *   - 宿主身份与心跳落 `~/.bolloon/supervisor.json`, 谁在跑/跑到哪可查。
+ */
+export async function runSupervisorHost(opts) {
+    const home = opts.home ?? os.homedir();
+    const log = opts.log ?? (() => { });
+    const workerId = newWorkerId();
+    const state = {
+        owner: opts.supervisor.owner,
+        workerId,
+        pid: process.pid,
+        host: os.hostname(),
+        startedAt: new Date().toISOString(),
+        runnerKind: opts.runnerKind ?? 'injected',
+        dryRun: !!opts.dryRun,
+        tickIntervalMs: opts.tickIntervalMs ?? 30_000,
+        leaseTtlMs: opts.leaseTtlMs ?? 90_000,
+        ticks: 0,
+        v: 1,
+    };
+    await writeSupervisorState(state, home);
+    const persist = async () => {
+        if (opts.extraState)
+            Object.assign(state, opts.extraState());
+        await writeSupervisorState(state, home);
+    };
+    // 让调用方随时能把状态写下去 (解析阶段报告一确定就可查, 不必等 tick 结束)
+    opts.onStateReady?.(persist);
+    const acquire = opts.acquireLock ?? acquireTickLock;
+    const useLock = opts.crossProcessLock !== false;
+    let stopping = false;
+    let ticking = false;
+    let timer = null;
+    const tickWithLock = async () => {
+        if (stopping || ticking)
+            return; // 进程内互斥
+        ticking = true;
+        const tickNo = (state.ticks ?? 0) + 1;
+        const startedMs = Date.now();
+        // 卡住的 tick 必须可观测 (长期运行时"没日志"和"卡死"必须能区分)
+        const watchdog = setInterval(() => {
+            log(`[supervisor-host] ⚠ tick #${tickNo} 已运行 ${Math.round((Date.now() - startedMs) / 1000)}s 仍未结束 (可能卡在 runner/session 创建)`);
+        }, 30_000);
+        watchdog.unref?.();
+        let lockPath;
+        let release;
+        try {
+            if (useLock) {
+                const r = await acquire({ lockPath: supervisorTickLockPath(home), staleMs: 300_000, log: () => { } });
+                if (!r.acquired) {
+                    // 别的宿主在 tick → 本轮让路 (不阻塞), 原因写进状态, 可观测
+                    state.lastTickAt = new Date().toISOString();
+                    state.lastSummary = `本轮让路: tick 锁被 ${r.holder?.pid ?? '?'}@${r.holder?.host ?? '?'} 持有`;
+                    await persist();
+                    log(`[supervisor-host] ${state.lastSummary}`);
+                    return;
+                }
+                release = r.release;
+                lockPath = supervisorTickLockPath(home);
+            }
+            const rep = await opts.supervisor.tickOnce();
+            state.ticks = (state.ticks ?? 0) + 1;
+            state.lastTickAt = rep.at;
+            state.lastSummary = `#${rep.tick} 认领 ${rep.claimed.length} · 执行 ${rep.executed.length} · 跳过 ${rep.skipped.length}${rep.errors.length ? ` · 错误 ${rep.errors.length}` : ''}`;
+            await persist();
+            log(`[supervisor-host] ${state.lastSummary}`);
+        }
+        catch (err) {
+            state.lastTickAt = new Date().toISOString();
+            state.lastSummary = `tick 异常: ${String(err?.message || err).slice(0, 160)}`;
+            await persist().catch(() => { });
+            log(`[supervisor-host] ${state.lastSummary}`);
+        }
+        finally {
+            clearInterval(watchdog);
+            try {
+                await release?.();
+            }
+            catch { /* 锁释放失败: 陈旧回收兜底 */ }
+            void lockPath;
+            ticking = false;
+        }
+    };
+    if ((opts.mode ?? 'interval') === 'once') {
+        await tickWithLock();
+        state.stoppedAt = new Date().toISOString();
+        state.stopReason = 'once';
+        await writeSupervisorState(state, home);
+        return { stop: async () => { }, state };
+    }
+    // 宿主驱动 tick (不用 supervisor 自己的 interval, 避免两条 tick 循环重复推进同一个 Goal)
+    timer = setInterval(() => { void tickWithLock(); }, state.tickIntervalMs);
+    if (!opts.keepAlive)
+        timer.unref?.();
+    log(`[supervisor-host] 启动 owner=${state.owner} worker=${workerId} tick=${state.tickIntervalMs}ms`);
+    // 启动后**立刻**跑一轮: 重启/接管时不该白等一个 tick 间隔才开始推进 (ticking 标志同步置位, stop() 会等它收尾)
+    void tickWithLock();
+    const stop = async (reason = 'requested') => {
+        if (stopping)
+            return;
+        stopping = true;
+        if (timer) {
+            clearInterval(timer);
+            timer = null;
+        }
+        opts.supervisor.stop();
+        // 等当前 tick 收尾 (最多 30s), 保证不半路丢状态
+        for (let i = 0; i < 300 && ticking; i++)
+            await new Promise((r) => setTimeout(r, 100));
+        state.stoppedAt = new Date().toISOString();
+        state.stopReason = reason;
+        await persist().catch(() => { });
+        log(`[supervisor-host] 已优雅停止 (${reason})`);
+    };
+    return { stop, state };
+}
+/**
+ * 给独立宿主用的解析器: 按 Goal 的 channelId 建/复用**专用 agent session** 执行。
+ * 解析不出来 (没有 channelId / agent 不可用 / 显式关闭) → { ok:false }, Goal 只被诊断不被执行。
+ */
+/**
+ * 给独立宿主用的解析器: 委托给**分阶段** resolver (`runner-resolver.ts`)。
+ * 阶段报告通过 `onResolution` 交给宿主落盘 (lastResolution), 让 wakeReport/API/CLI 能回答
+ * "这个 Goal 为什么没被执行、卡在哪一阶段、耗时多少"。
+ */
+export function createLocalAgentResolver(opts) {
+    const cache = new Map();
+    return async (req) => {
+        const { resolveGoalRunner } = await import('./runner-resolver.js');
+        const res = await resolveGoalRunner(req, opts);
+        opts.onResolution?.(req.goal.goalId, res);
+        if (res.ok && res.runner)
+            cache.set(req.goal.goalId, res);
+        return res;
+    };
+}
+/**
+ * 起一个**独立**的 Supervisor 宿主。
+ * - 执行器由 `createLocalAgentResolver` 按 Goal 的 channelId 解析专用 agent session (懒建 + 复用);
+ * - `BOLLOON_SUPERVISE_AGENT=0` 或 dryRun → 解析器恒 ok:false → 只诊断不执行 (Goal 状态不动);
+ * - 常驻模式下进程保持存活, 收到 SIGINT/SIGTERM 优雅停止并落 stoppedAt。
+ */
+export async function runStandaloneSupervisorHost(opts = {}) {
+    const log = opts.log ?? ((m) => console.log(m));
+    const { ExecutionSupervisor } = await import('./execution-supervisor.js');
+    let lastResolution = null;
+    let persistNow = async () => { };
+    const resolver = opts.dryRun
+        ? async (req) => ({ ok: false, kind: 'none', reason: `dry-run: 不执行 (goal=${req.goal.goalId})` })
+        : createLocalAgentResolver({
+            allow: process.env.BOLLOON_SUPERVISE_AGENT !== '0',
+            log,
+            home: opts.home,
+            onResolution: (goalId, res) => {
+                lastResolution = {
+                    goalId, at: new Date().toISOString(), ok: !!res.ok,
+                    failedStage: res.failedStage, reason: res.reason,
+                    stages: (res.stages || []).map((x) => `${x.stage}${x.ok ? '✓' : '✗'}${x.ms}ms`).join(' → '),
+                    detail: (res.stages || []).map((x) => ({ stage: x.stage, ok: x.ok, ms: x.ms, note: x.note, error: x.error, errorClass: x.errorClass })),
+                };
+                log(`[supervisor-host] 解析 ${res.ok ? '✅ 可执行' : `⛔ 卡在 ${res.failedStage}`} — ${res.reason || ''}`);
+                void persistNow().catch(() => { }); // 阶段报告立刻落盘
+            },
+        });
+    const sup = new ExecutionSupervisor({
+        resolver: resolver,
+        maxPerTick: opts.maxPerTick ?? (Number(process.env.BOLLOON_SUPERVISOR_MAX_PER_TICK) || 1),
+        tickIntervalMs: opts.tickIntervalMs ?? (Number(process.env.BOLLOON_SUPERVISOR_TICK_MS) || 30_000),
+        leaseTtlMs: opts.leaseTtlMs ?? (Number(process.env.BOLLOON_SUPERVISOR_LEASE_MS) || 90_000),
+        log,
+    });
+    const host = await runSupervisorHost({
+        supervisor: sup,
+        mode: opts.once ? 'once' : 'interval',
+        keepAlive: !opts.once,
+        tickIntervalMs: sup.status().tickIntervalMs,
+        leaseTtlMs: sup.status().leaseTtlMs,
+        runnerKind: opts.dryRun ? 'none' : 'standalone',
+        dryRun: !!opts.dryRun,
+        home: opts.home,
+        log,
+        extraState: () => (lastResolution ? { lastResolution } : {}),
+        onStateReady: (write) => { persistNow = write; },
+    });
+    if (opts.once) {
+        log(`[supervisor-host] once 完成: ${host.state.lastSummary || '(空)'}`);
+        return { ticks: host.state.ticks ?? 0, state: host.state, lastReport: sup.status().lastReport };
+    }
+    const onSignal = (sig) => {
+        void host.stop(`signal:${sig}`).then(() => process.exit(0));
+    };
+    process.once('SIGINT', () => onSignal('SIGINT'));
+    process.once('SIGTERM', () => onSignal('SIGTERM'));
+    return { ticks: host.state.ticks ?? 0, state: host.state, lastReport: null };
+}

package/dist/cli/setup-wizard.js

@@ -12,10 +12,12 @@
  *   - io 可注入 → 单测不碰真实 stdin/stdout
  */
 import * as readline from 'readline';
+import { evaluateSetup, providerUsable, readConfigFacts, resolveBolloonHome, } from '../setup/setup-store.js';
+import { runOnboard } from '../setup/onboard.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
-import { llmConfigStore, PROVIDER_INFO, DEFAULT_PROVIDER_CONFIGS } from '../llm/config-store.js';
+import { llmConfigStore, PROVIDER_INFO } from '../llm/config-store.js';
 /** 向导推荐的供应商顺序 (第一个是最省事的国内直连) */
 export const RECOMMENDED_PROVIDERS = [
     'deepseek', 'minimax', 'openai', 'anthropic', 'openrouter', 'gemini',
@@ -108,149 +110,116 @@ export async function writeUserIdentity(name, home = os.homedir()) {
     return { identity, created, file };
 }
 // ---------------------------------------------------------------- 首次运行判断
-function providerUsable(p) {
-    if (!p?.enabled)
-        return false;
-    if (p.apiKey)
-        return true;
-    return p.requiresApiKey === false; // 本地模型 (ollama/local) 不需要 key
-}
+// providerUsable 只有一份实现 (setup-store)
 /** 首次运行: 没有可用供应商, 或还没有用户身份 */
 export async function isFirstRun(home = os.homedir()) {
+    // 2026-09-16 (Phase 1/3): 不再有独立判断 —— 是否"需要引导"由 setup-store 唯一决定。
+    //   fail-closed: 评估不出来 → 视为"需要引导"。
     try {
-        await llmConfigStore.initialize();
-        const cfg = await llmConfigStore.getConfig();
-        const usable = Object.values(cfg.providers || {}).some((p) => providerUsable(p));
-        if (!usable)
-            return true;
-        const user = await readUserIdentity(home);
-        return !user;
+        const ev = await evaluateSetup({ bolloonHome: resolveBolloonHome(process.env, home), light: true });
+        return ev.gate !== 'ready';
     }
-    catch {
-        return false; // 判断失败不阻塞启动
+    catch (e) {
+        console.warn('[setup] 初始化状态评估失败, 按"需要引导"处理 (fail-closed):', String(e?.message || e).slice(0, 160));
+        return true;
     }
 }
-/** 运行初始化向导 (交互式或参数式) */
+/** WizardIO → OnboardIO 适配 (select/confirm 用编号或值回答) */
+function onboardIO(io) {
+    return {
+        print: (m) => io.print(m),
+        ask: async (q, opts) => {
+            for (let i = 0; i < 3; i++) {
+                const v = await io.ask(q, opts?.defaultValue ? { default: opts.defaultValue } : undefined);
+                const val = String(v ?? '').trim() || String(opts?.defaultValue ?? '');
+                if (!opts?.validate)
+                    return val;
+                const r = opts.validate(val);
+                if (r.ok)
+                    return val;
+                io.print(`  ✗ ${r.error || '输入无效'}`);
+            }
+            return String(opts?.defaultValue ?? '');
+        },
+        askHidden: async (q) => {
+            const { askHiddenLine } = await import('./setup-wizard.js').catch(() => ({ askHiddenLine: null }));
+            return io.ask(q, { hidden: true }); // WizardIO 已支持 hidden (不回显)
+        },
+        confirm: async (q, d = true) => {
+            const a = String(await io.ask(`${q} (y/n)`, { default: d ? 'y' : 'n' })).trim().toLowerCase();
+            return a === '' ? d : /^(y|yes|1|true|是)$/.test(a);
+        },
+        select: async (q, choices) => {
+            io.print(q);
+            choices.forEach((c, i) => io.print(`  ${i + 1}) ${c.label}${c.hint ? ` — ${c.hint}` : ''}`));
+            const a = String(await io.ask(`选择 (序号或名称)`, { default: '1' })).trim();
+            if (!a)
+                return choices[0]?.value || '';
+            if (/^\d+$/.test(a) && choices[Number(a) - 1])
+                return choices[Number(a) - 1].value;
+            const hit = choices.find((c) => c.value === a) || choices.find((c) => a && c.value.startsWith(a)) || choices.find((c) => a && c.label.includes(a));
+            return hit?.value || a;
+        },
+    };
+}
+/**
+ * 运行初始化向导 —— 现在是**可恢复阶段执行器**的薄包装 (Phase 2):
+ *   load state → 显示已有 → 收集修改 → 校验 → 真实验证 → 原子提交阶段 → 推进
+ * 失败: 保留已完成步骤 · 不清配置 · 标失败分类 · 给重试/修改/回退入口 · **不显示配置完成**
+ */
 export async function runSetupWizard(opts = {}) {
     const io = opts.io ?? defaultWizardIO();
     const home = opts.home ?? os.homedir();
-    const interactive = opts.interactive !== false;
+    const bolloonHome = resolveBolloonHome(process.env, home);
     const P = (s) => io.print(s);
+    const mode = opts.mode || 'setup';
+    P('');
+    P('╭─ Bolloon 初始化 (可中断, 下次从失败阶段继续) ─────╮');
+    P('│ 身份 → 供应商 → 凭证 → 模型 → 连通性 → 运行时   │');
+    P('╰──────────────────────────────────────────────────╯');
+    // 参数式输入 (非交互/脚本): 先落盘再跑阶段, 保证"输入已保存"
     try {
-        await llmConfigStore.initialize();
+        if (opts.name)
+            await writeUserIdentity(opts.name, home);
+        const prov = opts.provider;
+        if (prov) {
+            const store = llmConfigStore;
+            await store.initialize();
+            await store.updateProvider(prov, { enabled: true });
+            if (opts.apiKey)
+                await store.updateProvider(prov, { apiKey: opts.apiKey });
+            if (opts.model)
+                await store.updateProvider(prov, { model: opts.model });
+            if (mode !== 'reconfigure')
+                await store.setActiveProvider(prov);
+        }
     }
     catch (e) {
-        return { ok: false, error: `读取配置失败: ${String(e?.message || e).slice(0, 200)}` };
-    }
-    P('');
-    P('╭─ Bolloon 初始化 ─────────────────────────────╮');
-    P('│ 三步: 你的称呼 → 模型供应商 → API key + 模型 │');
-    P('╰──────────────────────────────────────────────╯');
-    // ---- 1) 用户称呼 ----
-    const existingUser = await readUserIdentity(home);
-    let name = String(opts.name || '').trim();
-    if (!name && interactive) {
-        name = await io.ask('① 我该怎么称呼你?', { default: existingUser?.name || os.userInfo().username });
+        return { ok: false, error: `参数落盘失败: ${String(e?.message || e).slice(0, 160)}` };
     }
-    if (!name)
-        name = existingUser?.name || os.userInfo().username;
-    const idWrite = await writeUserIdentity(name, home);
-    P(`   身份: ${idWrite.identity.name}${idWrite.created ? ' (已生成新 DID)' : ' (复用已有 DID)'}`);
-    P(`   DID:  ${idWrite.identity.did.slice(0, 42)}...`);
-    P(`   文件: ${idWrite.file}`);
-    // ---- 2) 供应商 ----
-    const cfg = await llmConfigStore.getConfig();
-    const providers = cfg.providers;
-    let provider = String(opts.provider || '').toLowerCase().trim();
-    if (!provider && interactive) {
-        P('');
-        P('② 选一个模型供应商:');
-        RECOMMENDED_PROVIDERS.forEach((p, i) => {
-            const info = PROVIDER_INFO[p] || {};
-            const st = providers[p];
-            const mark = providerUsable(st) ? '🔑 已配置' : (st?.requiresApiKey === false ? '免 key' : '');
-            P(`   ${String(i + 1).padStart(2)}. ${p.padEnd(11)} ${String(info.name || '').padEnd(16)} ${mark}`);
-        });
-        const ans = await io.ask('   序号或名字', { default: cfg.activeProvider });
-        const idx = Number(ans);
-        provider = Number.isFinite(idx) && idx >= 1 && idx <= RECOMMENDED_PROVIDERS.length
-            ? RECOMMENDED_PROVIDERS[idx - 1]
-            : ans.trim().toLowerCase();
-    }
-    if (!provider)
-        provider = cfg.activeProvider;
-    if (!providers[provider]) {
-        return { ok: false, error: `未知供应商 '${provider}'. 可用: ${Object.keys(providers).join(', ')}` };
-    }
-    const info = PROVIDER_INFO[provider] || {};
-    const current = providers[provider];
-    const needsKey = current?.requiresApiKey !== false;
-    // ---- 3) API key ----
-    let apiKey = String(opts.apiKey || '').trim();
-    if (!apiKey)
-        apiKey = String(current?.apiKey || '').trim(); // 已配置的沿用
-    if (!apiKey && needsKey && interactive) {
-        P('');
-        P(`③ ${info.name || provider} 需要 API key (输入不回显, 只写本地 ~/.bolloon/bolloon-config.json)`);
-        apiKey = await io.ask(`   粘贴 ${provider} API key`, { hidden: true });
-        if (!apiKey)
-            P('   ⚠ 未输入 key — 该供应商会保持不可用 (可用 bolloon model key <provider> 之后再补)');
-    }
-    // ---- 4) 模型 ----
-    const models = Array.isArray(info.models) ? info.models : [];
-    let model = String(opts.model || '').trim();
-    if (!model && interactive) {
-        if (models.length > 0)
-            P(`   可选模型: ${models.slice(0, 8).join(' / ')}`);
-        model = await io.ask('④ 用哪个模型?', { default: current?.model || models[0] || '' });
-    }
-    if (!model)
-        model = current?.model || models[0] || '';
-    // ---- 5) 落盘 ----
-    const patch = { enabled: true };
-    if (apiKey)
-        patch.apiKey = apiKey;
-    if (model)
-        patch.model = model;
-    if (!current?.baseUrl)
-        patch.baseUrl = DEFAULT_PROVIDER_CONFIGS[provider]?.baseUrl;
-    await llmConfigStore.updateProvider(provider, patch);
-    const usableNow = apiKey || !needsKey;
-    if (usableNow) {
-        await llmConfigStore.setActiveProvider(provider);
-    }
-    // ---- 6) 连通性测试 ----
-    let test;
-    if (!opts.skipTest && usableNow) {
-        P('');
-        P('⑤ 测试连通性...');
-        try {
-            const r = await llmConfigStore.testProvider(provider);
-            test = { success: !!r.success, latency: r.latency, error: r.error };
-            P(r.success ? `   ✅ 连通 (${r.latency ?? '?'} ms)` : `   ⚠ 未通过: ${String(r.error || '').slice(0, 160)}`);
-        }
-        catch (e) {
-            test = { success: false, error: String(e?.message || e).slice(0, 200) };
-            P(`   ⚠ 测试失败: ${test.error}`);
-        }
-    }
-    P('');
-    P(`✅ 配置完成 — 当前供应商: ${provider}${model ? `, 模型: ${model}` : ''}`);
-    P(`   配置文件: ${path.join(home, '.bolloon', 'bolloon-config.json')}`);
-    P('   开始对话: bolloon --cli');
-    P('');
+    const res = await runOnboard({
+        mode,
+        io: onboardIO(io),
+        home,
+        bolloonHome,
+        targets: opts.targets,
+        skipSteps: opts.skipTest ? ['connectivity'] : undefined,
+        oneShot: opts.interactive === false,
+    });
+    const cfg = await readConfigFacts(bolloonHome).catch(() => null);
     return {
-        ok: true,
-        userName: idWrite.identity.name,
-        provider,
-        model,
-        identityFile: idWrite.file,
-        identityCreated: idWrite.created,
-        test,
+        ok: res.ok,
+        userName: res.state.inputs.name,
+        provider: res.state.inputs.provider,
+        model: res.state.inputs.model,
+        identityFile: getUserIdentityFile(home),
+        identityCreated: !!res.state.inputs.identityDid,
+        test: res.state.checks.connectivityOk ? { success: true } : { success: false, error: res.state.lastError?.message },
+        error: res.ok ? undefined : (res.message || res.actions[0]),
+        // 新增: 结构化状态 (旧调用方看不到也不影响)
+        ...{ gate: res.gate, stage: res.state.stage, summary: res.summary },
     };
 }
-// ---------------------------------------------------------------- /model 命令
-/** 配置状态一览 (供 CLI 会话内 /model 与 bolloon model 共用) */
 export async function formatProviderStatus() {
     await llmConfigStore.initialize();
     const cfg = await llmConfigStore.getConfig();

package/dist/cron/tick-lock.js

@@ -125,7 +125,7 @@ async function reclaim(lockPath, log, holder, reason) {
  */
 export async function acquireTickLock(opts = {}) {
     const home = opts.home ?? os.homedir();
-    const lockPath = tickLockPath(home);
+    const lockPath = opts.lockPath ?? tickLockPath(home);
     const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
     const now = (opts.now ?? (() => new Date()))();
     const log = opts.log ?? noopLogger;

package/dist/electron/first-run.js

@@ -6,6 +6,7 @@
  */
 import { BrowserWindow, app, ipcMain } from 'electron';
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { firstRunFlagPath, dataDir, logsDir } from './paths';
 import { log } from './logger';
@@ -64,6 +65,26 @@ const OVERLAY_HTML = `
 </body>
 </html>
 `;
+/**
+ * 2026-09-16 (Phase 3): 首启**事实**来自 SetupStore 的状态文件 (setup-state.json),
+ * first-run flag 只决定"要不要自动弹窗"。Electron 不能用 flag 当初始化事实。
+ */
+export function readSetupFact() {
+    try {
+        const p = path.join(os.homedir(), '.bolloon', 'setup-state.json');
+        const js = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const stage = String(js?.stage || 'uninitialized');
+        const ready = stage === 'ready';
+        return { ready, stage, gate: ready ? 'ready' : (stage === 'needs_repair' ? 'repair' : stage === 'blocked' ? 'blocked' : 'setup') };
+    }
+    catch {
+        return { ready: false, stage: 'uninitialized', gate: 'setup' };
+    }
+}
+/** 未 ready → 显示 Onboard (无论 flag 是否已看过) */
+export function shouldShowOnboard() {
+    return !readSetupFact().ready;
+}
 export function hasSeenFirstRun() {
     try {
         return fs.existsSync(firstRunFlagPath());
@@ -120,10 +141,20 @@ export function registerFirstRunIpc() {
     log('first-run IPC handlers registered');
 }
 /** 包装 — 决定要不要弹 overlay */
+/**
+ * 2026-09-16 (Phase 3): 是否弹引导 —— **事实来自 SetupStore** (setup-state.json), flag 只控制"已 ready 后是否还提示"。
+ * 未 ready 时无论 flag 有没有都弹 (初始化没完成的机器不能装作已配置)。
+ */
 export async function maybeShowFirstRun(parent) {
-    if (hasSeenFirstRun())
+    const fact = readSetupFact();
+    if (fact.ready && hasSeenFirstRun())
         return;
-    log('首启 — 弹出引导');
+    if (!fact.ready) {
+        log(`初始化未就绪 (stage=${fact.stage}, gate=${fact.gate}) — 弹出引导 (flag=${hasSeenFirstRun() ? '已看过' : '未看过'})`);
+    }
+    else {
+        log('首启 — 弹出引导');
+    }
     await showFirstRunOverlay(parent);
     app.addRecentDocument(firstRunFlagPath()); // 跟踪最近文档, 让 user 知道有这文件
 }

package/dist/electron-build/electron/first-run.js

@@ -33,6 +33,8 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSetupFact = readSetupFact;
+exports.shouldShowOnboard = shouldShowOnboard;
 exports.hasSeenFirstRun = hasSeenFirstRun;
 exports.markFirstRunSeen = markFirstRunSeen;
 exports.showFirstRunOverlay = showFirstRunOverlay;
@@ -46,6 +48,7 @@ exports.maybeShowFirstRun = maybeShowFirstRun;
  */
 const electron_1 = require("electron");
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const paths_1 = require("./paths");
 const logger_1 = require("./logger");
@@ -104,6 +107,26 @@ const OVERLAY_HTML = `
 </body>
 </html>
 `;
+/**
+ * 2026-09-16 (Phase 3): 首启**事实**来自 SetupStore 的状态文件 (setup-state.json),
+ * first-run flag 只决定"要不要自动弹窗"。Electron 不能用 flag 当初始化事实。
+ */
+function readSetupFact() {
+    try {
+        const p = path.join(os.homedir(), '.bolloon', 'setup-state.json');
+        const js = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const stage = String(js?.stage || 'uninitialized');
+        const ready = stage === 'ready';
+        return { ready, stage, gate: ready ? 'ready' : (stage === 'needs_repair' ? 'repair' : stage === 'blocked' ? 'blocked' : 'setup') };
+    }
+    catch {
+        return { ready: false, stage: 'uninitialized', gate: 'setup' };
+    }
+}
+/** 未 ready → 显示 Onboard (无论 flag 是否已看过) */
+function shouldShowOnboard() {
+    return !readSetupFact().ready;
+}
 function hasSeenFirstRun() {
     try {
         return fs.existsSync((0, paths_1.firstRunFlagPath)());
@@ -160,10 +183,20 @@ function registerFirstRunIpc() {
     (0, logger_1.log)('first-run IPC handlers registered');
 }
 /** 包装 — 决定要不要弹 overlay */
+/**
+ * 2026-09-16 (Phase 3): 是否弹引导 —— **事实来自 SetupStore** (setup-state.json), flag 只控制"已 ready 后是否还提示"。
+ * 未 ready 时无论 flag 有没有都弹 (初始化没完成的机器不能装作已配置)。
+ */
 async function maybeShowFirstRun(parent) {
-    if (hasSeenFirstRun())
+    const fact = readSetupFact();
+    if (fact.ready && hasSeenFirstRun())
         return;
-    (0, logger_1.log)('首启 — 弹出引导');
+    if (!fact.ready) {
+        (0, logger_1.log)(`初始化未就绪 (stage=${fact.stage}, gate=${fact.gate}) — 弹出引导 (flag=${hasSeenFirstRun() ? '已看过' : '未看过'})`);
+    }
+    else {
+        (0, logger_1.log)('首启 — 弹出引导');
+    }
     await showFirstRunOverlay(parent);
     electron_1.app.addRecentDocument((0, paths_1.firstRunFlagPath)()); // 跟踪最近文档, 让 user 知道有这文件
 }

package/dist/electron-build/electron/first-run.js.map

@@ -1 +1 @@
-{"version":3,"file":"first-run.js","sourceRoot":"","sources":["../../../src/electron/first-run.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"first-run.js","sourceRoot":"","sources":["../../../src/electron/first-run.ts"],"names":[],"mappings":"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"}