berry-agent 0.1.0-alpha.1

package/dist/scheduler/cron-backend.js

@@ -0,0 +1,135 @@
+/**
+ * cron 可选后端乙案（04 §12：缺省进程内挂钟〔甲案〕；OS cron 后端 = 宿主
+ * 停机期不断保的可选增强）。写用户 crontab 的编舞：
+ *
+ *   - 自有条目行尾标记 `# berry-agent:<名>`（对外声明值位——去品牌化例外）；
+ *     读改写全程保留他人行（只增删自有标记行）；
+ *   - 人面授权链（authorize 注入——写 crontab 是改用户系统态，授权缺席
+ *     即未授权：亮拒 SCHEDULER_CRON_UNAUTHORIZED，不猜默认放行）；
+ *   - win32 诚实拒（crontab 生态不在——SCHEDULER_CRON_UNSUPPORTED，不装能）；
+ *   - schedule 可表达性：cron 分钟粒度——sub-minute 间隔与非 60 倍数分钟
+ *     间隔拒（UNSUPPORTED）；once 形拒（cron 表达不了单发——单发归进程内
+ *     挂钟独辖）；every/daily/weekly 可表达形全量映射；
+ *   - 写失败（crontab 非零退出）SCHEDULER_CRON_WRITE_FAILED。
+ *
+ * 联动契约（service 消费）：register/unregister **同步**亮拒——调用方（行
+ * 翻转/删行前的 service 面）先 OS 后行库的序，错在 OS 段即行未动（不半态）；
+ * 故本件用 spawnSync 直读直写（启停/删行低频动作，短暂阻塞可接受）。
+ */
+import { spawnSync } from 'node:child_process';
+import { BaseError } from '../contracts/index.js';
+/** 自有条目标记（行尾注释——读改写的身份判据；对外声明值位去品牌化例外） */
+export function cronMarker(name) {
+    return `# berry-agent:${name}`;
+}
+/**
+ * schedule → cron 表达式（纯函数，导出供测试）。
+ *
+ * day 编号两系同构（0=周日……6=周六：Date.getDay 与 cron dow 一致）——直接映射。
+ */
+export function scheduleToCron(s) {
+    switch (s.kind) {
+        case 'every': {
+            if (s.seconds % 60 !== 0) {
+                throw new BaseError('SCHEDULER_CRON_UNSUPPORTED', `cron 分钟粒度：every:${s.seconds}s 非 60 整除秒不可表达（进程内挂钟可跑——OS 后端不挂）`);
+            }
+            const minutes = s.seconds / 60;
+            if (minutes === 1)
+                return '* * * * *';
+            if (minutes < 60)
+                return `*/${minutes} * * * *`;
+            if (minutes % 60 === 0) {
+                const hours = minutes / 60;
+                return hours === 1 ? '0 * * * *' : `0 */${hours} * * *`;
+            }
+            throw new BaseError('SCHEDULER_CRON_UNSUPPORTED', `cron 表达不了 every:${s.seconds}s（非整分钟/整小时间隔——进程内挂钟可跑）`);
+        }
+        case 'daily': {
+            const [h, m] = s.time.split(':');
+            return `${Number(m)} ${Number(h)} * * *`; // 域序换位 + 去零垫（cron 规范形）
+        }
+        case 'weekly': {
+            const [h, min] = s.time.split(':');
+            const dow = [...s.days].sort((a, b) => a - b).join(',');
+            return `${Number(min)} ${Number(h)} * * ${dow}`;
+        }
+        case 'once':
+            throw new BaseError('SCHEDULER_CRON_UNSUPPORTED', 'cron 表达不了 once 单发形（单发归进程内挂钟独辖——行停机错过即跳过）');
+    }
+}
+/** OS crontab 注册器实装（同步编舞——联动契约见头注） */
+export function createOsCronRegistrar(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const command = deps.command ?? 'berry-agent';
+    const exec = deps.execCrontab ?? execCrontabViaSpawnSync;
+    /** 平台前置（两动词同判——win32 无 crontab 生态，读写皆不可为） */
+    function assertPlatform() {
+        if (platform === 'win32') {
+            throw new BaseError('SCHEDULER_CRON_UNSUPPORTED', 'win32 无 crontab 生态——OS cron 后端不支持（缺省进程内挂钟形态不受影响）');
+        }
+    }
+    /** 授权前置（写动作判——读 crontab 无害不判；注销摘自有行属收敛不判） */
+    function assertAuthorized() {
+        if (!deps.authorize || !deps.authorize()) {
+            throw new BaseError('SCHEDULER_CRON_UNAUTHORIZED', 'OS cron 后端未获人面授权（写用户 crontab 须显式授权——不猜默认放行）');
+        }
+    }
+    /** 读当前 crontab（无 crontab = 空表——exit 1 且空 stdout 视为常态非错误） */
+    function readCrontab() {
+        const r = exec(['-l']);
+        if (r.code === 0)
+            return r.stdout;
+        if (r.code === 1 && r.stdout.trim() === '')
+            return ''; // 「no crontab for <user>」常态
+        throw new BaseError('SCHEDULER_CRON_WRITE_FAILED', `crontab -l 读失败（exit ${r.code}）：${r.stderr.trim() || '无 stderr'}`);
+    }
+    /** 写新 crontab（stdin 注入形；非零退出亮拒） */
+    function writeCrontab(content) {
+        const r = exec(['-'], content.endsWith('\n') || content === '' ? content : `${content}\n`);
+        if (r.code !== 0) {
+            throw new BaseError('SCHEDULER_CRON_WRITE_FAILED', `crontab 写入失败（exit ${r.code}）：${r.stderr.trim() || '无 stderr'}`);
+        }
+    }
+    /** 自有标记行摘除（他人行原样保留；返回 [新内容, 是否有摘除]） */
+    function stripMarkerLines(content, name) {
+        const marker = cronMarker(name);
+        const kept = [];
+        let removed = false;
+        for (const line of content.split('\n')) {
+            if (line.includes(marker))
+                removed = true;
+            else
+                kept.push(line);
+        }
+        return [kept.join('\n'), removed];
+    }
+    return {
+        register(row) {
+            assertPlatform();
+            const cron = scheduleToCron(row.schedule); // 可表达性判先于授权（不授权也先知道形不行）
+            assertAuthorized();
+            const current = readCrontab();
+            const [withoutSelf] = stripMarkerLines(current, row.name);
+            const entry = `${cron} ${command} run --read-only --tick ${row.name} ${cronMarker(row.name)}`;
+            const next = withoutSelf.trim() === '' ? entry : `${withoutSelf.trimEnd()}\n${entry}`;
+            writeCrontab(next);
+        },
+        unregister(name) {
+            assertPlatform();
+            const current = readCrontab();
+            const [next, removed] = stripMarkerLines(current, name);
+            if (!removed)
+                return; // 无自有条目——no-op（不重写用户 crontab）
+            writeCrontab(next);
+        },
+    };
+}
+/** 缺省 crontab 执行器（spawnSync；错误折 exit code——-1 = spawn 失败） */
+function execCrontabViaSpawnSync(args, input) {
+    const r = spawnSync('crontab', args, input === undefined ? undefined : { input });
+    return {
+        stdout: r.stdout?.toString() ?? '',
+        stderr: r.stderr?.toString() ?? '',
+        code: r.error ? -1 : (r.status ?? -1),
+    };
+}

package/dist/scheduler/engine.js

@@ -0,0 +1,280 @@
+/**
+ * scheduler 引擎（04 §12 缺省甲案：进程内挂钟）。
+ *
+ * 编舞：轮询求 due 集 → 闸评估（clock 道独辖）→ 执行前抢占（同任务在飞先
+ * kill 'preempted' 再起新——同任务不并发双跑）→ runner spawn → 墙钟超时
+ * 守卫 → 结算回写（last_fire_at/last_outcome/next_fire_at 推进）。
+ *
+ * 语义钉死（与 schedule.ts 三钉同源）：
+ *   - 错过不重放：start() 重启补推进——启机时既 due 的行静默 advance 到
+ *     下一刻（不补跑、只 warn 留痕）；
+ *   - gated 拦截也推进：闸拦的行 settleGated 记结局 + advance（不动
+ *     last_fire_at——gated 非真跑，冷却闸判据不被污染）；
+ *   - manual 道不走闸（用户显式意图）也不受并发帽辖（pi-tick manual 同律）；
+ *     帽只辖 clock sweep 的自动并发。
+ *
+ * claim-then-advance 接线律（04 §12 无人值守执行链定形注③——u-2 落码）：
+ * fire 起跑 setActive 记账（activePid = runner 句柄 pid——甲案宿主 pid/
+ * 乙案子进程 pid）、settle 清账——「执行前抢占」条款的 durable 对偶（进程
+ * 内注册表管进程内防双跑，activePid 管跨进程可见性）；start() 僵行清扫
+ * （pid 死 + 超墙钟 → 行回 idle 可重发）+ fire 前跨进程在飞判定（乙案
+ * 并存窗让位的引擎侧对偶——见 fireRow）。墙钟 kill 语义由 runner 实装
+ * 定义（定形注④两形：进程内实装 = interrupt 协作中止；进程实装 = TERM
+ * →KILL）——引擎只认 kill 接口零感知。
+ *
+ * 定时器全接缝注入（TimerSeam——测试假钟驱动；缺省真身 setTimeout）。
+ * 停钟不杀在飞：stop 只摘轮询定时器，在飞实例自然收场照常结算回写
+ * （宿主退出编舞若需「杀在飞」属 host 装配批 killAll 编舞，不在本件）。
+ */
+import { kill as processKill, pid as processPid } from 'node:process';
+import { BaseError } from '../contracts/index.js';
+import { evaluateGates } from './gates.js';
+import { nextFireAt } from './schedule.js';
+/** 墙钟超时缺省（毫秒）——单次 fire 的最长在飞时帽（30min；pi-tick 同量级） */
+export const FIRE_WALL_TIMEOUT_MS = 30 * 60_000;
+/** 轮询下限（毫秒）——due 等待的定时夹取下限（防零毫秒自旋；every:5s 粒度下无害） */
+export const MIN_POLL_MS = 500;
+/** 轮询上限（毫秒）——无近期 due 时的 belt 巡检间隔（行可能被外部 enable，最迟此距补觉） */
+export const MAX_POLL_MS = 60_000;
+/** clock sweep 并发帽缺省（1——单并发保守档：同时至多一个自动任务在飞） */
+export const DEFAULT_MAX_CONCURRENT = 1;
+/** 缺省真身定时器 */
+export function realTimerSeam() {
+    return {
+        set(ms, fn) {
+            return setTimeout(fn, ms);
+        },
+        clear(handle) {
+            clearTimeout(handle);
+        },
+    };
+}
+/** 引擎实装 */
+export function createSchedulerEngine(deps) {
+    const dao = deps.dao;
+    const runner = deps.runner;
+    const now = deps.now;
+    const warn = deps.warn;
+    const timers = deps.timers ?? realTimerSeam();
+    const wallTimeoutMs = deps.wallTimeoutMs ?? FIRE_WALL_TIMEOUT_MS;
+    const maxConcurrent = deps.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    const gateFacts = deps.gateFacts ?? (() => ({}));
+    const isPidAlive = deps.isPidAlive ?? realIsPidAlive;
+    /** 同名在飞注册表（键=行名——抢占判据面） */
+    const active = new Map();
+    /**
+     * 同名起跑预留位（fireRow 入口同步置、收场清）——sweep 判 active ∪ 本位：
+     * active.set 落在首个 await（spawn）之后，无预留位时同步连呼 sweep 会
+     * 在微任务窗内重复起同名任务（在飞判据穿透）。manual 道不判本位（抢占语义）。
+     */
+    const reserved = new Set();
+    let pollHandle = null;
+    let running = false;
+    let sweeping = false;
+    /** 下一轮轮询定时（夹取 [MIN_POLL_MS, MAX_POLL_MS]——null earliest 落 MAX belt 巡检） */
+    function scheduleNextPoll() {
+        if (!running)
+            return;
+        if (pollHandle !== null) {
+            timers.clear(pollHandle);
+            pollHandle = null;
+        }
+        const earliest = dao.earliestNextFire();
+        let ms = MAX_POLL_MS;
+        if (earliest !== null) {
+            const delta = Date.parse(earliest) - Date.parse(now());
+            ms = Math.min(Math.max(delta, MIN_POLL_MS), MAX_POLL_MS);
+        }
+        pollHandle = timers.set(ms, () => {
+            pollHandle = null;
+            doSweep();
+        });
+    }
+    return {
+        start() {
+            if (running)
+                return;
+            running = true;
+            // 僵行清扫（定形注③——u-2）：activePid 非空非己的行，pid 死 + 超起跑
+            // 墙钟（activeStartedAt + wallTimeoutMs）→ 清账行回 idle + lastOutcome
+            // 记回收（settleGated 形不动 last_fire_at——非真跑）。与关系保守判：
+            // 活 + 超钟形（pid 复用误判险）不清、下轮 fire 的 setActive 覆写自愈。
+            for (const row of dao.list()) {
+                if (row.activePid === null || row.activePid === processPid)
+                    continue; // 己 pid = 甲案在飞（进程内注册表管辖）
+                const startedAtMs = row.activeStartedAt !== null ? Date.parse(row.activeStartedAt) : 0;
+                const expired = Date.parse(now()) - startedAtMs > wallTimeoutMs;
+                if (!expired || isPidAlive(row.activePid))
+                    continue;
+                const outcome = {
+                    trigger: 'clock',
+                    reason: 'killed',
+                    error: `僵行回收（activePid ${row.activePid} 已死且超墙钟——乙案子进程 kill -9 残账/宿主重启旧账）`,
+                    finishedAt: now(),
+                };
+                dao.setActive(row.name, null, null, now());
+                dao.settleGated(row.name, outcome, row.nextFireAt, now());
+                warn(`[scheduler] 僵行清扫：${row.name}（activePid ${row.activePid} 死 + 超墙钟——行回 idle 可重发）`);
+            }
+            // 重启补推进：既 due 行静默跳下一刻（错过不重放——warn 留痕不 fire）
+            const missed = dao.due(now());
+            for (const row of missed) {
+                const next = nextFireAt(row.schedule, new Date(now()));
+                dao.advanceNextFire(row.name, next, now());
+                warn(`[scheduler] 重启补推进：${row.name} 错过到点 ${row.nextFireAt}，跳下一刻 ${next}`);
+            }
+            scheduleNextPoll();
+        },
+        stop() {
+            running = false;
+            if (pollHandle !== null) {
+                timers.clear(pollHandle);
+                pollHandle = null;
+            }
+        },
+        poke() {
+            if (!running)
+                return;
+            scheduleNextPoll();
+        },
+        sweep: doSweep,
+        async fireNow(name, trigger) {
+            const row = dao.get(name);
+            if (!row)
+                throw new BaseError('SCHEDULER_NOT_FOUND', `任务「${name}」不存在（run 幽灵名零行守卫）`);
+            return fireRow(row, trigger);
+        },
+        get inFlightCount() {
+            // 观察面诚实律：active.set 落在 spawn 的 await 之后，spawn 已发起但未上
+            // 注册表的瞬态窗内单计 active 会给同步观察者假 0（fireRow 已在跑）——
+            // 计 active ∪ reserved，「在飞 = 起跑中或已 spawn」。
+            return new Set([...active.keys(), ...reserved]).size;
+        },
+    };
+    /**
+     * 单行触发共核（clock/manual/cron 三道同编舞）：
+     * 抢占同任务旧实例 → 闸评估（clock/cron 道；manual 直通）→ spawn →
+     * 墙钟守卫 → 结算回写（gated 走 settleGated 不动 last_fire_at）。
+     */
+    async function fireRow(row, trigger) {
+        const name = row.name;
+        reserved.add(name); // 同步占位（见 reserved 注释——防 sweep 微任务窗重触）
+        try {
+            // 执行前抢占：同任务旧实例在飞先杀再起（kill 幂等 + 等收场——同任务不并发双跑）
+            const prev = active.get(name);
+            if (prev) {
+                prev.kill('preempted');
+                await prev.settled;
+            }
+            // 闸评估：manual 道不走（用户显式意图）；clock/cron 道序定五门
+            if (trigger !== 'manual') {
+                const block = evaluateGates(gateFacts(row), { now: now() });
+                if (block) {
+                    const firedAt = now();
+                    const next = nextFireAt(row.schedule, new Date(firedAt));
+                    const outcome = {
+                        trigger,
+                        reason: 'gated',
+                        gate: block.gate,
+                        error: block.reason,
+                        finishedAt: firedAt,
+                    };
+                    dao.settleGated(name, outcome, next, now());
+                    return outcome;
+                }
+            }
+            const firedAt = now();
+            // 跨进程在飞判定（定形注③乙案并存窗的引擎侧对偶——u-2）：行 activePid
+            // 非空非己且活体未超墙钟 = 乙案子进程（或他宿主）真在飞 → 本轮让位
+            // （gated 记结局 + 推进，不 kill 不双跑——跨进程 kill 有 pid 复用误杀
+            // 险，「执行前抢占」条款对跨进程实例不越权；子进程侧对偶 = run-entry
+            // --tick 让位律，双向对称）。死/超钟形不拦（settle 段覆写自愈）。
+            if (row.activePid !== null && row.activePid !== processPid && isPidAlive(row.activePid)) {
+                const startedAtMs = row.activeStartedAt !== null ? Date.parse(row.activeStartedAt) : 0;
+                const expired = Date.parse(now()) - startedAtMs > wallTimeoutMs;
+                if (!expired) {
+                    const next = nextFireAt(row.schedule, new Date(firedAt));
+                    const outcome = {
+                        trigger,
+                        reason: 'gated',
+                        error: `跨进程实例在飞（activePid ${row.activePid}）——本轮让位不双跑`,
+                        finishedAt: firedAt,
+                    };
+                    dao.settleGated(name, outcome, next, now());
+                    return outcome;
+                }
+            }
+            const handle = await runner.spawn({ row, trigger, wallTimeoutMs });
+            active.set(name, handle);
+            // claim-then-advance 记账（定形注③）：fire 起跑落 activePid（runner 句柄
+            // pid——甲案宿主 pid/乙案子进程 pid）+ 起跑墙钟；settle 清（对偶位）
+            if (handle.pid !== null)
+                dao.setActive(name, handle.pid, now(), now());
+            // 墙钟超时守卫（kill('timeout')——TERM→宽限→KILL 由 runner 实装升级）
+            const wallHandle = timers.set(wallTimeoutMs, () => handle.kill('timeout'));
+            let outcome;
+            try {
+                outcome = await handle.settled;
+            }
+            finally {
+                timers.clear(wallHandle);
+                active.delete(name);
+                dao.setActive(name, null, null, now()); // durable 在飞占用面清账（claim 对偶）
+            }
+            // next 从结算时刻取下一刻（every 形锚 now——错过不重放同律）；
+            // runner 内零跑判定（gated——wake 未落地/分派处理器缺席）同走 settleGated
+            // 不动 last_fire_at（与闸拦同律：非真跑不污染冷却闸判据）
+            const next = nextFireAt(row.schedule, new Date(now()));
+            if (outcome.reason === 'gated') {
+                dao.settleGated(name, outcome, next, now());
+            }
+            else {
+                dao.settleFire(name, firedAt, outcome, next, now());
+            }
+            return outcome;
+        }
+        finally {
+            reserved.delete(name);
+        }
+    }
+    /** 巡检体（定时回调与公开 sweep 直呼同体——函数声明提升供 scheduleNextPoll 前向引用） */
+    function doSweep() {
+        if (!running || sweeping)
+            return; // 重入闸：定时回调与手动直呼不叠跑
+        sweeping = true;
+        try {
+            const due = dao.due(now());
+            // 帽初值同观察面：起跑预留位（spawn 的 await 前瞬态）也占帽——同帽语义
+            let launched = new Set([...active.keys(), ...reserved]).size;
+            for (const row of due) {
+                // 在飞/起跑预留不重触：settle 前 next_fire_at 仍 due，若重触会自踏
+                // 活锁（重复抢占自家实例）——抢占只留给 manual 新实例道。在飞期间
+                // 持续 poll 是廉价 belt 巡检（settle 即推进）。
+                if (active.has(row.name) || reserved.has(row.name))
+                    continue;
+                if (launched >= maxConcurrent)
+                    break; // 帽满留 due——下轮 sweep 补觉（定时夹取防自旋）
+                launched += 1;
+                void fireRow(row, 'clock');
+            }
+        }
+        finally {
+            sweeping = false;
+        }
+        scheduleNextPoll();
+    }
+}
+/**
+ * pid 活死判真身（0 信号探活——不投递信号只验存在性）：ESRCH = 进程不存在
+ * （死）；EPERM = 存在但非己属（活——他用户/系统进程照算活体）。run-entry
+ * --tick 让位律与引擎清扫/判定共用单源（u-2 定形注③）。
+ */
+export function realIsPidAlive(pid) {
+    try {
+        processKill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}

package/dist/scheduler/gates.js

@@ -0,0 +1,60 @@
+/**
+ * DiscoveryGates 触发前置条件门（04 §12 /tick 瘦身条「照搬」——蓝本
+ * pilotdeck always-on DiscoveryGates 的纯闸评估序：**序定 first-failing-wins**，
+ * 单 Agent 场景裁多 project 位〔project_disabled/project_missing/
+ * dormant_no_signal/lock_busy 四门系 pilotdeck 多项目形态私有〕留五门）。
+ *
+ * 闸序（序即语义——前面的门先判，先拦先报）：
+ *   1. job_disabled     行启停位关（引擎 due 集已滤——belt 位，闸面仍判）
+ *   2. agent_busy       宿主前台在飞（单活跃机——定时任务不与用户对话抢跑）
+ *   3. recent_user_msg  用户静默窗内（刚说过话的窗口期不打扰）
+ *   4. cooldown         同任务上次触发后的冷却窗内（防高频任务空转连发）
+ *   5. daily_budget     当日后台预算 canAfford 闸（04 §5——缺预算跳本轮下周期再试）
+ *
+ * 判据全注入（GateFacts 由装配层从宿主面收集；评估器零 IO 零时钟）——
+ * 缺席事实 = 闸放行（探针未装配的门不咬——fail-open 属实：这些门是打扰
+ * 礼仪与预算面，非安全边界；安全边界在 runner 的 --read-only 与审批
+ * fail-closed）。
+ */
+/** 闸 id 序（评估序即语义序——勿重排：便宜的门在前、需要事实的门在后） */
+export const GATE_ORDER = ['job_disabled', 'agent_busy', 'recent_user_msg', 'cooldown', 'daily_budget'];
+/** 用户静默窗（毫秒）——窗内近期用户消息即拦（不打扰正在交互的用户） */
+export const USER_QUIET_WINDOW_MS = 5 * 60_000;
+/** 同任务冷却窗（毫秒）——上次触发后此窗内不再连发 */
+export const JOB_COOLDOWN_MS = 60_000;
+/**
+ * 序定闸评估：依 GATE_ORDER 逐门判、先拦先报。
+ *
+ * manual 触发不走本评估（/tick run = 用户显式意图——04 §12 未辖手动道，
+ * pi-tick manual 同律不设闸）；本函数只辖挂钟/cron 到点道。
+ */
+export function evaluateGates(facts, ctx) {
+    const nowMs = Date.parse(ctx.now);
+    // 1. job_disabled——行关即拦（belt：due 集已滤 enabled，闸面独立判一次）
+    if (facts.enabled === false) {
+        return { gate: 'job_disabled', reason: '任务行处于停用态' };
+    }
+    // 2. agent_busy——前台在飞即拦（本轮跳过，advance 到下一刻）
+    if (facts.agentBusy === true) {
+        return { gate: 'agent_busy', reason: '宿主前台对话在飞' };
+    }
+    // 3. recent_user_msg——静默窗内有用户消息即拦
+    if (facts.lastUserMessageAt) {
+        const at = Date.parse(facts.lastUserMessageAt);
+        if (!Number.isNaN(at) && nowMs - at < USER_QUIET_WINDOW_MS) {
+            return { gate: 'recent_user_msg', reason: `静默窗（${USER_QUIET_WINDOW_MS / 1000}s）内有用户消息` };
+        }
+    }
+    // 4. cooldown——同任务冷却窗内即拦
+    if (facts.lastFireAt) {
+        const at = Date.parse(facts.lastFireAt);
+        if (!Number.isNaN(at) && nowMs - at < JOB_COOLDOWN_MS) {
+            return { gate: 'cooldown', reason: `上次触发后冷却窗（${JOB_COOLDOWN_MS / 1000}s）内` };
+        }
+    }
+    // 5. daily_budget——canAfford 假即拦（跳本轮，下周期再试）
+    if (facts.canAfford === false) {
+        return { gate: 'daily_budget', reason: '当日后台预算不可负担（canAfford 假）' };
+    }
+    return null;
+}

package/dist/scheduler/index.js

@@ -0,0 +1,25 @@
+/**
+ * scheduler 件公开面（02 §4.1 席 22 [L3, deps contracts+context+persist]：
+ * jobs 表 + 进程内挂钟 + /tick + DiscoveryGates + cron 可选后端；04 §12）。
+ *
+ * 装载态集成归批 12 装载面后装配批：ctx.schedule 消费面（03 §10.7）、
+ * channels /tick 注册、--tick CLI 编舞、真 bin spawn 接线、GateFacts 从宿主
+ * 面收集（agentBusy/lastUserMessageAt/canAfford）——本件纯逻辑 + 全接缝注入。
+ */
+import './codes.js';
+// schedule 串词法/校验/推刻（纯函数）
+export { formatSchedule, MIN_INTERVAL_SECONDS, nextFireAt, parseSchedule, resolveRelativeOnce, } from './schedule.js';
+// 迁移
+export { SCHEDULER_MIGRATION } from './migration.js';
+// DiscoveryGates 触发前置条件门
+export { evaluateGates, GATE_ORDER, JOB_COOLDOWN_MS, USER_QUIET_WINDOW_MS, } from './gates.js';
+// jobs 表 DAO + 六动词服务面 + GoalJobsFace 第五槽
+export { createSchedulerService, JobsDao, } from './service.js';
+// runner（执行接缝 + 进程实装）
+export { createProcessRunnerFactory, } from './runner.js';
+// 进程内挂钟引擎
+export { createSchedulerEngine, DEFAULT_MAX_CONCURRENT, FIRE_WALL_TIMEOUT_MS, MAX_POLL_MS, MIN_POLL_MS, realIsPidAlive, realTimerSeam, } from './engine.js';
+// cron 可选后端（OS 注册器乙案）
+export { createOsCronRegistrar, cronMarker, scheduleToCron, } from './cron-backend.js';
+// /tick 命令处理器（纯程序面——argv → 人读文本）
+export { describeOutcome, runTickCommand, TICK_USAGE } from './tick.js';

package/dist/scheduler/migration.js

@@ -0,0 +1,22 @@
+export const SCHEDULER_MIGRATION = {
+    version: 2,
+    name: 'scheduler-jobs',
+    sql: `
+    CREATE TABLE jobs (
+      name               TEXT PRIMARY KEY,
+      prompt             TEXT NOT NULL,
+      cwd                TEXT,
+      schedule           TEXT NOT NULL,
+      enabled            INTEGER NOT NULL DEFAULT 0,
+      builtin            INTEGER NOT NULL DEFAULT 0,
+      created_at         TEXT NOT NULL,
+      updated_at         TEXT NOT NULL,
+      next_fire_at       TEXT,
+      last_fire_at       TEXT,
+      last_outcome       TEXT,
+      active_pid         INTEGER,
+      active_started_at  TEXT
+    );
+    CREATE INDEX idx_jobs_next_fire ON jobs (next_fire_at) WHERE enabled = 1 AND next_fire_at IS NOT NULL;
+  `,
+};