@bolloon/bolloon-agent 0.4.24 → 0.4.26

package/dist/agents/goal-criteria.js

@@ -0,0 +1,124 @@
+/**
+ * goal-criteria.ts — 判据生成 / 确认 / 跨 Run 证据汇总 (批次 2-F, 2026-09-16)
+ *
+ * 规则 (与 leo 的规格一致):
+ *   · 用户明确给出完成条件 → 直接使用 (criteriaSource = 'user', 已确认);
+ *   · 用户没给 → **agent 提候选判据** (criteriaSource = 'agent_proposed', 未确认);
+ *     候选判据**不能**直接成为最终完成条件 —— 未确认就永不自动完成;
+ *   · 目标过于模糊 / 候选生成失败 → **不自动完成**, 交人 (needs_human);
+ *   · 证据跨 Run 汇总 (Run 证据 → Goal 证据, 去重), unresolvedItems 跨 Run 保留。
+ */
+import { readGoal, setCriteria, addEvidence, updateGoal, } from './goal-store.js';
+import { readRun } from './run-store.js';
+/** 太模糊的目标: 判据无从谈起 (短且没有可核验的动作词) */
+export function looksVague(objective) {
+    const o = String(objective || '').trim();
+    if (!o)
+        return { vague: true, reason: '目标为空' };
+    const hasVerb = /(写|改|建|加|删|修|跑|测|验证|发布|提交|导出|生成|读|查|部署|完成|实现|接入|更新|安装|配置|整理|对比|汇总)/.test(o);
+    if (o.length <= 4 && !hasVerb)
+        return { vague: true, reason: `目标太短且没有可核验动作: "${o}"` };
+    if (/^(优化|改进|提升|完善|处理|搞|弄|看看|研究一下)/.test(o) && o.length < 12) {
+        return { vague: true, reason: `目标过于笼统: "${o}" (缺可核验的产出)` };
+    }
+    return { vague: false };
+}
+/**
+ * 从目标推导候选判据 (确定性启发式, 不依赖 LLM —— 生成失败也不会伪造成功)。
+ * 候选**必须**经人确认才能用作完成条件。
+ */
+export function proposeCriteria(objective) {
+    const v = looksVague(objective);
+    if (v.vague)
+        return { ok: false, criteria: [], needsHuman: true, reason: `无法生成可核验判据: ${v.reason} → 请补一句"做完的样子"` };
+    const o = String(objective).trim();
+    const out = [];
+    // 动作拆解: 目标里出现的"动作 + 对象"直接成为候选
+    const actions = ['写出', '创建', '修改', '删除', '跑通', '验证', '发布', '提交', '导出', '生成', '读入', '部署', '安装', '配置', '整理', '汇总', '对比'];
+    const hits = actions.filter((a) => o.includes(a));
+    for (const h of hits.slice(0, 3))
+        out.push(`完成"${h}"这一步并留下可核验产物`);
+    if (!out.length)
+        out.push(`产出与目标一致的结果: ${o.slice(0, 60)}`);
+    out.push('有证据可复现 (命令/文件/输出留痕)');
+    out.push('没有遗留未解决项');
+    return { ok: true, criteria: out.slice(0, 5) };
+}
+/** 给 Goal 提候选判据 (不确认; 留痕) */
+export async function proposeForGoal(goalId) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { ok: false, criteria: [], needsHuman: true, reason: 'Goal 不存在' };
+    if (goal.successCriteria.length && goal.criteriaSource === 'user') {
+        return { ok: true, criteria: goal.successCriteria, reason: '用户已给出判据 (不改)' };
+    }
+    const p = proposeCriteria(goal.objective);
+    if (!p.ok) {
+        // 太模糊 → 明确交人, 不写假判据
+        await addEvidence(goalId, [`判据生成失败: ${p.reason}`]).catch(() => { });
+        await updateGoal(goalId, { status: 'needs_human' }).catch(() => { });
+        return p;
+    }
+    await setCriteria(goalId, { criteria: p.criteria, source: 'agent_proposed', confirm: false });
+    await addEvidence(goalId, [`agent 提出候选判据 (待确认): ${p.criteria.join(' / ')}`]).catch(() => { });
+    return p;
+}
+/** 人确认判据 (可同时改内容) */
+export async function confirmCriteria(goalId, opts = {}) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { ok: false, reason: 'Goal 不存在' };
+    const criteria = opts.criteria?.length ? opts.criteria : goal.successCriteria;
+    if (!criteria.length)
+        return { ok: false, reason: '没有可确认的判据 (先给判据或让 agent 提候选)' };
+    const next = await setCriteria(goalId, { criteria, source: opts.criteria?.length ? 'user' : (goal.criteriaSource || 'user'), confirm: true, by: opts.by || 'human' });
+    await addEvidence(goalId, [`判据已确认 (v${next?.criteriaVersion}): ${criteria.join(' / ')}`]).catch(() => { });
+    return { ok: true, goal: next };
+}
+/** 把 Goal 名下所有 Run 的证据汇总进 Goal.evidence (去重, 保留跨 Run 历史) */
+export async function aggregateEvidence(goalId) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { runs: 0, runEvidence: [], goalEvidence: [], unresolved: [] };
+    const runEvidence = [];
+    let lastRunStatus;
+    for (const rid of goal.runs || []) {
+        const run = await readRun(rid).catch(() => null);
+        if (!run)
+            continue;
+        lastRunStatus = run.status;
+        for (const ev of (run.evidence || []))
+            runEvidence.push(`[${rid.slice(0, 8)} ${run.status}] ${String(ev).slice(0, 200)}`);
+    }
+    const merged = [...new Set([...(goal.evidence || []), ...runEvidence])].slice(-50);
+    if (merged.length !== (goal.evidence || []).length) {
+        await updateGoal(goalId, { evidence: merged }).catch(() => { });
+    }
+    return { runs: (goal.runs || []).length, runEvidence, goalEvidence: merged, unresolved: goal.unresolvedItems || [], lastRunStatus };
+}
+/** 长期完成的整体判据 (给 CLI/Web/Supervisor 一个统一解释) */
+export async function longTermStatus(goalId) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { canComplete: false, reason: 'Goal 不存在', checks: {} };
+    const sum = await aggregateEvidence(goalId);
+    const checks = {
+        hasCriteria: goal.successCriteria.length > 0,
+        criteriaConfirmed: goal.criteriaConfirmed === true && goal.criteriaSource !== undefined,
+        allSatisfied: goal.successCriteria.length > 0 && goal.successCriteria.every((_, i) => goal.completedCriteria.includes(i)),
+        hasEvidence: (sum.goalEvidence || []).length > 0,
+        noUnresolved: (goal.unresolvedItems || []).length === 0,
+        lastRunHealthy: !sum.lastRunStatus || !['failed', 'interrupted', 'stalled'].includes(String(sum.lastRunStatus)),
+    };
+    const canComplete = Object.values(checks).every(Boolean);
+    const firstFail = Object.entries(checks).find(([, v]) => !v)?.[0];
+    const reasonMap = {
+        hasCriteria: '没有完成判据',
+        criteriaConfirmed: '判据未经人确认 (候选判据不算数)',
+        allSatisfied: '还有判据没满足',
+        hasEvidence: '没有证据',
+        noUnresolved: '还有未解决项',
+        lastRunHealthy: `最近一条 Run 状态异常 (${sum.lastRunStatus})`,
+    };
+    return { canComplete, reason: canComplete ? '判据全满足 + 已确认 + 有证据 + 无未解决项' : (reasonMap[firstFail] || '未满足完成条件'), checks };
+}

package/dist/agents/goal-store.js

@@ -0,0 +1,526 @@
+/**
+ * goal-store.ts — GoalStore: **目标事实来源** (2026-09-16 Milestone 2)
+ *
+ * 与既有模型的关系 (leo 2026-09-16: 先明确唯一关系, 不急着删旧模块):
+ *   GoalStore (本文件, `~/.bolloon/goals/<goalId>.json`)  = 目标的**唯一事实来源**
+ *   RunStore  (`~/.bolloon/runs/<runId>.json`)              = 一次执行的**唯一事实来源**
+ *   SessionStore                                            = 对话上下文来源
+ *   Task/Plan                                               = Goal 的执行辅助结构 (不承载目标状态)
+ *   旧模型保留但降级为"入口/草稿": `pi-ecosystem-goals` 的 queue.json (目标队列) 与
+ *   `goal-resume` 的 park/resume (双栖接力) 仍是生产者, 迁移留待后续批次 —— 不删。
+ *
+ * 关键规则 (协议 §「关键规则」):
+ *   - Goal 永远不能因为一次 prompt 结束就自动消失
+ *   - Run 结束 ≠ Goal 完成; 只有 successCriteria 全部满足 (且有证据) 才能 completed
+ *   - 不允许"done 但目标没达成"伪装成功
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as os from 'os';
+import * as crypto from 'crypto';
+/** 可被 Supervisor 自动唤醒推进的状态 (其余必须等人或等外部事件) */
+export const GOAL_RUNNABLE_STATUSES = ['open', 'active', 'recovering', 'retry_wait', 'stalled'];
+export function goalsDir() {
+    return path.join(os.homedir(), '.bolloon', 'goals');
+}
+function goalPath(goalId) {
+    return path.join(goalsDir(), `${goalId}.json`);
+}
+/** 原子写 (tmp + rename): 读到的永远是完整 JSON */
+async function writeGoal(rec) {
+    await fs.mkdir(goalsDir(), { recursive: true });
+    const p = goalPath(rec.goalId);
+    const tmp = `${p}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(rec, null, 2), 'utf8');
+    await fs.rename(tmp, p);
+}
+/** 同 goal 的进程内串行化 (并发写不覆盖判据/证据) */
+const goalLocks = new Map();
+async function withGoalLock(goalId, fn) {
+    const prev = goalLocks.get(goalId) || Promise.resolve();
+    const mine = prev.catch(() => { }).then(fn);
+    const tail = mine.catch(() => { });
+    goalLocks.set(goalId, tail);
+    try {
+        return await mine;
+    }
+    finally {
+        if (goalLocks.get(goalId) === tail)
+            goalLocks.delete(goalId);
+    }
+}
+export function newGoalId() {
+    return `g-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+}
+export async function createGoal(opts) {
+    // 2026-09-16 (Phase 3 硬门禁): 初始化未就绪时**不允许创建长期 Goal**。
+    //   生产环境生效; 测试环境跳过 (用例跑在隔离 HOME, 本来就没有真实配置)。
+    if (!process.env.VITEST && process.env.BOLLOON_SETUP_IN_PROGRESS !== '1') {
+        try {
+            const { getSetupGateCached } = await import('../setup/setup-store.js');
+            const { gate, state } = await getSetupGateCached();
+            if (gate !== 'ready') {
+                throw new Error(`初始化未就绪 (${gate}, 阶段 ${state.stage}) — 不允许创建 Goal; 先 \`bolloon setup\``);
+            }
+        }
+        catch (err) {
+            if (/初始化未就绪/.test(String(err?.message || '')))
+                throw err;
+            // 门禁自身不可读 → fail-closed (不放行)
+            throw new Error(`初始化状态不可读, 拒绝创建 Goal (fail-closed): ${String(err?.message || err).slice(0, 120)}`);
+        }
+    }
+    const now = new Date().toISOString();
+    const rec = {
+        goalId: newGoalId(),
+        objective: String(opts.objective || '').slice(0, 500),
+        successCriteria: (opts.successCriteria || []).map((c) => String(c).slice(0, 200)).slice(0, 20),
+        // 用户明确给出判据 → 直接视为已确认 (criteriaSource=user); 没给 → unknown, 之后由 agent 提候选
+        criteriaSource: (opts.successCriteria && opts.successCriteria.length) ? 'user' : 'unknown',
+        criteriaConfirmed: !!(opts.successCriteria && opts.successCriteria.length),
+        criteriaVersion: 1,
+        constraints: (opts.constraints || []).map((c) => String(c).slice(0, 200)).slice(0, 20),
+        requiredSkills: (opts.requiredSkills || []).map((c) => String(c).slice(0, 120)).slice(0, 20),
+        budget: opts.budget,
+        status: 'open',
+        channelId: opts.channelId,
+        agentId: opts.agentId,
+        createdBy: opts.createdBy,
+        createdAt: now,
+        updatedAt: now,
+        runs: [],
+        completedCriteria: [],
+        unresolvedItems: [],
+        evidence: [],
+    };
+    await writeGoal(rec);
+    return rec;
+}
+export async function readGoal(goalId) {
+    if (!goalId)
+        return null;
+    try {
+        return JSON.parse(await fs.readFile(goalPath(goalId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function listGoals(opts = {}) {
+    let files = [];
+    try {
+        files = await fs.readdir(goalsDir());
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        const g = await readGoal(f.replace(/\.json$/, ''));
+        if (!g)
+            continue;
+        if (opts.status) {
+            const want = Array.isArray(opts.status) ? opts.status : [opts.status];
+            if (!want.includes(g.status))
+                continue;
+        }
+        out.push(g);
+    }
+    out.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1));
+    return typeof opts.limit === 'number' ? out.slice(0, opts.limit) : out;
+}
+export async function updateGoal(goalId, patch) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        const next = { ...rec, ...patch, goalId: rec.goalId, updatedAt: new Date().toISOString() };
+        await writeGoal(next);
+        return next;
+    });
+}
+/**
+ * 把一次 Run 挂到 Goal 上 (Run 反查 Goal 的入口)。
+ * 幂等: 同一 runId 重复挂不会产生重复条目。
+ */
+export async function attachRun(goalId, runId, opts = {}) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        if (!rec.runs.includes(runId))
+            rec.runs.push(runId);
+        if (opts.makeCurrent !== false)
+            rec.currentRunId = runId;
+        if (rec.status === 'open')
+            rec.status = 'active';
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 标记某条判据已满足 (+可选证据) */
+export async function markCriterion(goalId, index, satisfied, evidence) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        if (index < 0 || index >= rec.successCriteria.length)
+            return rec;
+        const set = new Set(rec.completedCriteria);
+        if (satisfied)
+            set.add(index);
+        else
+            set.delete(index);
+        rec.completedCriteria = Array.from(set).sort((a, b) => a - b);
+        if (evidence)
+            rec.evidence = [...rec.evidence, String(evidence).slice(0, 300)].slice(-50);
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 记录未解决项 (失败步骤 / 待人工确认) —— 有未解决项就不许判完成 */
+export async function setUnresolved(goalId, items) {
+    return updateGoal(goalId, { unresolvedItems: items.map((i) => String(i).slice(0, 300)).slice(0, 30) });
+}
+export async function addEvidence(goalId, evidence) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        rec.evidence = [...rec.evidence, ...evidence.map((e) => String(e).slice(0, 300))].slice(-50);
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/**
+ * 完成门 (Milestone 4): **确定性**判定, 不看模型怎么说。
+ *   全部必要判据满足 + 有证据 + 无未解决项 → 才允许 completed。
+ *   未声明 successCriteria 的目标**永不**自动完成 (需要人显式确认) —— 否则"模型说完成"就变成了完成。
+ */
+export function evaluateGoalCompletion(goal, opts = {}) {
+    if (!goal.successCriteria.length) {
+        return { complete: false, reason: '未声明 successCriteria: 不允许自动判完成 (需人工确认)', missing: [] };
+    }
+    // 2-F: 候选判据 (未确认) 不许当作完成条件
+    if (goal.criteriaSource === 'agent_proposed' && goal.criteriaConfirmed !== true) {
+        return { complete: false, reason: `判据是 agent 提的候选 (v${goal.criteriaVersion || 1}), 未经人确认 → 不许判完成`, missing: goal.successCriteria };
+    }
+    if (goal.criteriaConfirmed === false) {
+        return { complete: false, reason: '判据未确认 → 不许判完成', missing: goal.successCriteria };
+    }
+    // 2-F: 最近一条 Run 还处于"没跑完"的状态 (失败/中断/失速) → 不许判完成
+    const lastRunStatus = opts.lastRunStatus;
+    if (lastRunStatus && ['failed', 'interrupted', 'stalled'].includes(String(lastRunStatus))) {
+        return { complete: false, reason: `最近一条 Run 状态是 ${lastRunStatus} (未处理好) → 不许判完成`, missing: [] };
+    }
+    const missing = goal.successCriteria
+        .map((c, i) => ({ c, i }))
+        .filter(({ i }) => !goal.completedCriteria.includes(i))
+        .map(({ c, i }) => `[${i}] ${c}`);
+    if (missing.length) {
+        return { complete: false, reason: `还有 ${missing.length} 条判据未满足`, missing };
+    }
+    if (!goal.evidence.length) {
+        return { complete: false, reason: '没有证据 (evidence 为空): 不许判完成', missing: [] };
+    }
+    if (goal.unresolvedItems.length) {
+        return { complete: false, reason: `还有 ${goal.unresolvedItems.length} 项未解决`, missing: goal.unresolvedItems };
+    }
+    return { complete: true, reason: '全部判据满足 + 有证据 + 无未解决项', missing: [] };
+}
+/**
+ * 设置/确认判据 (2-F)。
+ *   source: 谁给的 (user 显式给 / agent_proposed 候选 / imported)
+ *   confirm: 是否视为已确认 —— **候选判据必须显式 confirm 才可能完成**
+ */
+export async function setCriteria(goalId, opts) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        if (opts.criteria) {
+            rec.successCriteria = opts.criteria.map((c) => String(c).slice(0, 200)).slice(0, 20);
+            rec.criteriaVersion = (rec.criteriaVersion || 1) + 1;
+            rec.completedCriteria = []; // 判据变了 → 之前的满足记录作废 (避免拿旧判据凑完成)
+        }
+        if (opts.source)
+            rec.criteriaSource = opts.source;
+        if (opts.confirm !== undefined) {
+            rec.criteriaConfirmed = opts.confirm;
+            rec.criteriaConfirmedBy = opts.confirm ? (opts.by || 'human') : undefined;
+            rec.criteriaConfirmedAt = opts.confirm ? new Date().toISOString() : undefined;
+        }
+        if (opts.source === 'agent_proposed' && !opts.confirm)
+            rec.proposedCriteria = rec.successCriteria;
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 通过完成门就落 completed, 否则保持原状态并回传原因 (不静默) */
+export async function completeGoalIfEligible(goalId) {
+    const goal = await readGoal(goalId);
+    if (!goal)
+        return { ok: false, reason: `goal 不存在: ${goalId}`, goal: null };
+    // 2-F: 把"最近一条 Run 的真实状态"一起纳入完成门 (失败/中断/失速时不许判完成)
+    let lastRunStatus;
+    try {
+        const lastRunId = goal.currentRunId || goal.runs?.[goal.runs.length - 1];
+        if (lastRunId) {
+            const { readRun } = await import('./run-store.js');
+            lastRunStatus = (await readRun(lastRunId))?.status;
+        }
+    }
+    catch { /* 读不到就不加这一条约束, 其余判据照旧 */ }
+    const verdict = evaluateGoalCompletion(goal, { lastRunStatus });
+    if (!verdict.complete)
+        return { ok: false, reason: verdict.reason, goal, missing: verdict.missing };
+    const next = await updateGoal(goalId, {
+        status: 'completed',
+        resolution: { reason: verdict.reason, at: new Date().toISOString() },
+    });
+    return { ok: true, reason: verdict.reason, goal: next };
+}
+/**
+ * 找一个"还在进行中"的目标 (供 prompt 入口判断"继续还是新建")。
+ * 只看 open/active, 且限定 channel+agent (不同智能体的目标不混)。
+ */
+export async function findActiveGoal(opts) {
+    const all = await listGoals({ status: ['open', 'active'] });
+    for (const g of all) {
+        if (opts.channelId && g.channelId && g.channelId !== opts.channelId)
+            continue;
+        if (opts.agentId && g.agentId && g.agentId !== opts.agentId)
+            continue;
+        return g;
+    }
+    return null;
+}
+/** 给 CLI/Web 的一行摘要 */
+export function formatGoalLine(g) {
+    const done = `${g.completedCriteria.length}/${g.successCriteria.length || 0}`;
+    return `${g.goalId}  [${g.status.padEnd(9)}] 判据 ${done.padStart(4)}  run=${(g.currentRunId || '-').slice(0, 12)}  ${g.objective.slice(0, 44)}`;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 2026-09-16 (M2-A): continuation —— "下一次何时、因为什么被唤醒"
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 写调度元数据 (合并式)。
+ * 这是 2-A 的落地: Goal 永远能回答"下一步是什么/还需不需要自动继续/在等什么"。
+ */
+export async function setContinuation(goalId, patch) {
+    return withGoalLock(goalId, async () => {
+        const rec = await readGoal(goalId);
+        if (!rec)
+            return null;
+        rec.continuation = {
+            ...(rec.continuation || { autoContinue: true }),
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        rec.updatedAt = new Date().toISOString();
+        await writeGoal(rec);
+        return rec;
+    });
+}
+/** 幂等地累加自动继续尝试次数 (退避用) */
+export async function bumpContinuationAttempts(goalId) {
+    const rec = await readGoal(goalId);
+    const n = (rec?.continuation?.attempts || 0) + 1;
+    await setContinuation(goalId, { attempts: n });
+    return n;
+}
+export async function resetContinuationAttempts(goalId) {
+    await setContinuation(goalId, { attempts: 0 });
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 2026-09-16 (M2-B): 执行权租约 (跨进程排他) —— 真值在 <goalId>.lease 文件, 用 O_EXCL 独占创建
+// ─────────────────────────────────────────────────────────────────────────────
+function leasePath(goalId) {
+    return path.join(goalsDir(), `${goalId}.lease`);
+}
+function pidAlive(pid) {
+    if (!pid)
+        return false;
+    if (pid === process.pid)
+        return true;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
+}
+export async function readLease(goalId) {
+    try {
+        return JSON.parse(await fs.readFile(leasePath(goalId), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 抢执行权 (原子: 独占创建 lease 文件)。
+ * 可回收条件 (任一):
+ *   ① leaseUntil 已过期 (TTL)
+ *   ② 持有者进程已不在 (更早回收 —— 持有者可证明已死, 不必等满 TTL)
+ * 不可回收: 持有者活着且未过期 → 明确返回 ok:false + holder (调用方据此"让路", 不是报错)
+ */
+export async function claimGoal(goalId, opts = { owner: 'unknown' }) {
+    const ttl = opts.ttlMs ?? 90_000;
+    const now = opts.now ?? Date.now();
+    await fs.mkdir(goalsDir(), { recursive: true });
+    const p = leasePath(goalId);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const claimedAt = new Date(now).toISOString();
+        const lease = {
+            owner: opts.owner,
+            leaseId: `${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`,
+            claimedAt,
+            lastHeartbeat: claimedAt,
+            leaseUntil: new Date(now + ttl).toISOString(),
+            pid: process.pid,
+            host: os.hostname(),
+        };
+        try {
+            const fh = await fs.open(p, 'wx');
+            await fh.writeFile(JSON.stringify(lease, null, 2), 'utf8');
+            await fh.close();
+            // 镜像到 Goal 文件 (只为可读; 真值在 lease 文件)
+            await updateGoal(goalId, { lease: { owner: lease.owner, leaseId: lease.leaseId, claimedAt, lastHeartbeat: claimedAt, leaseUntil: lease.leaseUntil } });
+            return { ok: true, lease };
+        }
+        catch (err) {
+            if (err?.code !== 'EEXIST') {
+                return { ok: false, reason: `lease 文件不可创建: ${String(err?.message || err).slice(0, 120)}` };
+            }
+            const holder = await readLease(goalId);
+            if (!holder) {
+                await fs.rm(p, { force: true });
+                continue;
+            } // 坏文件 → 当陈旧回收
+            const expired = Date.parse(String(holder.leaseUntil || '')) <= now;
+            const dead = holder.pid ? !pidAlive(Number(holder.pid)) : false;
+            if (expired || dead) {
+                await fs.rm(p, { force: true });
+                continue;
+            }
+            return { ok: false, reason: `lease 被占用 (owner=${holder.owner}, until=${holder.leaseUntil})`, holder };
+        }
+    }
+    return { ok: false, reason: 'lease 抢占重试后仍失败' };
+}
+/** 续租 (必须带自己的 leaseId: 被接管后旧 worker 不能再续租, 也就不能再写) */
+export async function heartbeatGoal(goalId, leaseId, ttlMs = 90_000, now = Date.now()) {
+    const cur = await readLease(goalId);
+    if (!cur)
+        return { ok: false, reason: 'lease 不存在 (可能已过期被回收)' };
+    if (cur.leaseId !== leaseId)
+        return { ok: false, reason: `lease 已被接管 (当前 owner=${cur.owner})` };
+    const next = { ...cur, lastHeartbeat: new Date(now).toISOString(), leaseUntil: new Date(now + ttlMs).toISOString() };
+    try {
+        await fs.writeFile(leasePath(goalId), JSON.stringify(next, null, 2), 'utf8');
+    }
+    catch (err) {
+        return { ok: false, reason: `续租写失败: ${String(err?.message || err).slice(0, 120)}` };
+    }
+    await updateGoal(goalId, { lease: { owner: next.owner, leaseId: next.leaseId, claimedAt: next.claimedAt, lastHeartbeat: next.lastHeartbeat, leaseUntil: next.leaseUntil } });
+    return { ok: true, lease: next };
+}
+/** 释放执行权 (只释放自己的那把) */
+export async function releaseGoal(goalId, leaseId) {
+    const cur = await readLease(goalId);
+    if (!cur) {
+        await updateGoal(goalId, { lease: undefined });
+        return { ok: true };
+    }
+    if (cur.leaseId !== leaseId)
+        return { ok: false, reason: `lease 已被接管, 未释放 (当前 owner=${cur.owner})` };
+    await fs.rm(leasePath(goalId), { force: true });
+    await updateGoal(goalId, { lease: undefined });
+    return { ok: true };
+}
+/**
+ * 扫出"现在就该跑"的 Goal (M2-B 第 1-2 步: 扫描 + 判断可否唤醒)。
+ * 规则: 状态 ∈ active/recovering; autoContinue !== false; wakeAt 未到则跳过; 有活租约则跳过。
+ * 返回附带"为什么没被选"的说明, 便于诊断 (不静默)。
+ */
+export async function listRunnableGoals(opts = {}) {
+    const now = opts.now ?? Date.now();
+    const all = await listGoals({ limit: 100 });
+    const runnable = [];
+    const skipped = [];
+    for (const g of all) {
+        const c = g.continuation;
+        const skip = (reason) => skipped.push({ goalId: g.goalId, status: g.status, reason });
+        // 终态 / 等人 / 等外部事件 → 一律不自动唤醒 (这是 2-C 唤醒表的硬规则)
+        if (g.status === 'completed' || g.status === 'failed' || g.status === 'abandoned')
+            continue;
+        if (g.status === 'paused') {
+            skip('paused: 等用户 resume (重启也不会自动跑)');
+            continue;
+        }
+        if (g.status === 'needs_human') {
+            skip(`needs_human: 等人工 approve (${c?.wakeReason || ''})`);
+            continue;
+        }
+        if (g.status === 'awaiting_external' || c?.wakeReason === 'awaiting_external') {
+            skip(`awaiting_external: 等外部事件${c?.needsExternal ? ` (${c.needsExternal})` : ''}, 不重复发送`);
+            continue;
+        }
+        if (c?.autoContinue === false) {
+            skip(`autoContinue=false (${c.wakeReason || '等人'})`);
+            continue;
+        }
+        if (g.status === 'retry_wait' || (c?.wakeAt && Date.parse(c.wakeAt) > now)) {
+            if (c?.wakeAt && Date.parse(c.wakeAt) > now) {
+                skip(`retry_wait: 时间未到 (${c.wakeAt})`);
+                continue;
+            }
+            // retry_wait 且时间已到 → 可跑
+        }
+        const lease = await readLease(g.goalId);
+        const held = !!lease && Date.parse(String(lease.leaseUntil || '')) > now && (lease.pid ? pidAlive(Number(lease.pid)) : true);
+        if (held) {
+            skip(`lease 被 ${lease.owner} 持有至 ${lease.leaseUntil}`);
+            continue;
+        }
+        runnable.push(g);
+    }
+    // 先跑等着跑最久的 (公平性: 不让一个 Goal 霸占所有 tick)
+    runnable.sort((a, b) => Date.parse(a.updatedAt || a.createdAt) - Date.parse(b.updatedAt || b.createdAt));
+    return { runnable, skipped };
+}
+/** CLI/Web 可见的长期执行诊断 (每个 Goal 为什么在/不在跑) */
+export async function wakeReport(now = Date.now()) {
+    const goals = await listGoals({ limit: 50 });
+    const out = [];
+    for (const g of goals) {
+        const c = g.continuation;
+        const lease = await readLease(g.goalId);
+        const live = lease && Date.parse(String(lease.leaseUntil || '')) > now && (lease.pid ? pidAlive(Number(lease.pid)) : true);
+        let wake = '立即';
+        if (g.status === 'completed')
+            wake = '不再唤醒';
+        else if (g.status === 'paused' || c?.autoContinue === false)
+            wake = `等人 (${c?.wakeReason || g.status})`;
+        else if (c?.wakeAt && Date.parse(c.wakeAt) > now) {
+            const left = Math.round((Date.parse(c.wakeAt) - now) / 1000);
+            wake = `等时间 (${c.wakeAt}, 还剩 ${left}s${c.attempts ? `, 已自动继续 ${c.attempts} 次` : ''})`;
+        }
+        else if (g.status === 'awaiting_external' || c?.wakeReason === 'awaiting_external' || c?.external) {
+            const what = c?.needsExternal || (c?.external ? `${c.external.expectedSource}${c.external.expectedEvent ? `:${c.external.expectedEvent}` : ''} (requestId=${c.external.requestId}, 过期 ${c.external.expiresAt})` : '');
+            wake = `等外部事件${what ? ` (${what})` : ''}`;
+        }
+        else if (live)
+            wake = `已被 ${lease.owner} 认领`;
+        out.push({ goalId: g.goalId, status: g.status, wake, autoContinue: c?.autoContinue !== false, lease: live ? lease.owner : undefined });
+    }
+    return out;
+}