berry-agent 0.1.0-alpha.1

package/dist/scheduler/runner.js

@@ -0,0 +1,171 @@
+/**
+ * 任务执行 runner（04 §12：任务执行入口 = `berry-agent run --read-only`
+ * ——headless 无应答者、审批天然 fail-closed〔§9 无静默审批单发形〕）。
+ *
+ * 两层：RunnerFactory 接缝（引擎只认接缝——spawn 编舞装配可换、测试注假件）
+ * + 进程实装（node:child_process spawn、argv = `run --read-only --tick <名>`
+ * ——子进程按名读行自跑 prompt；07 §5 --tick 旗标 = 触发载体、--read-only =
+ * sandboxMode 只读单发）。
+ *
+ * kill 语义（pi-tick createRunControls 同律）：kill(reason) 幂等——首杀
+ * SIGTERM、宽限后 SIGKILL 升级；调用方传的 reason 原样进 settled 结局。
+ * settled 永不 reject：一切收场（正常/信号/spawn 失败/被杀）都归 RunOutcome。
+ */
+import { spawn } from 'node:child_process';
+/** 结局预览截断（pi-tick TRANSCRIPT_FINAL_TEXT_PREVIEW 同值） */
+const PREVIEW_CAP = 200;
+/** 输出尾窗（字节——只保尾部供预览，防长输出吃内存） */
+const OUTPUT_TAIL_BYTES = 4096;
+/**
+ * 进程 runner 工厂实装。
+ *
+ * stdout 取尾窗作 finalTextPreview（run --output-format text 缺省只出末条
+ * assistant 文本——07 §5；尾窗即足）；stderr 尾窗作错误摘要源。
+ */
+export function createProcessRunnerFactory(options = {}) {
+    const command = options.command ?? 'berry-agent';
+    const buildArgv = options.buildArgv ?? ((row) => ['run', '--read-only', '--tick', row.name]);
+    const spawnFn = options.spawnFn ?? spawn;
+    const killGraceMs = options.killGraceMs ?? 5_000;
+    const env = options.env ?? {};
+    const now = options.now ?? (() => new Date().toISOString());
+    return {
+        async spawn(req) {
+            const startedAtMs = Date.now();
+            let child;
+            try {
+                child = spawnFn(command, buildArgv(req.row, req.trigger), {
+                    cwd: req.row.cwd ?? undefined,
+                    env,
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    // 独立进程组——kill 信号达子进程整树（exec spawn 管道同律）
+                    detached: true,
+                });
+            }
+            catch (err) {
+                // spawn 同步抛（可执行不存在等）——进程从未存在，直接归 spawn 结局
+                const outcome = {
+                    trigger: req.trigger,
+                    reason: 'spawn',
+                    error: describeError(err),
+                    finishedAt: now(),
+                };
+                return { pid: null, kill: () => { }, settled: Promise.resolve(outcome) };
+            }
+            let stdoutTail = '';
+            let stderrTail = '';
+            let settledResolve;
+            const settled = new Promise((resolve) => {
+                settledResolve = resolve;
+            });
+            let killedReason = null;
+            let escalated = false;
+            const appendTail = (current, chunk) => (current + chunk).slice(-OUTPUT_TAIL_BYTES);
+            child.stdout?.on('data', (chunk) => {
+                stdoutTail = appendTail(stdoutTail, chunk.toString('utf8'));
+            });
+            child.stderr?.on('data', (chunk) => {
+                stderrTail = appendTail(stderrTail, chunk.toString('utf8'));
+            });
+            const handle = {
+                pid: child.pid ?? null,
+                kill(reason) {
+                    if (killedReason !== null || settledResolve === undefined)
+                        return; // 幂等
+                    killedReason = reason;
+                    signalTree(child, 'SIGTERM');
+                    // 宽限后 KILL 升级（未收场才升——close 事件先到则定时器空放无害）
+                    setTimeout(() => {
+                        if (!escalated) {
+                            escalated = true;
+                            signalTree(child, 'SIGKILL');
+                        }
+                    }, killGraceMs).unref?.();
+                },
+                settled,
+            };
+            child.on('error', (err) => {
+                if (settledResolve === undefined)
+                    return;
+                const r = settledResolve;
+                settledResolve = undefined;
+                r({
+                    trigger: req.trigger,
+                    reason: killedReason ?? 'spawn',
+                    error: describeError(err),
+                    finishedAt: now(),
+                });
+            });
+            child.on('close', (code, signal) => {
+                if (settledResolve === undefined)
+                    return;
+                const r = settledResolve;
+                settledResolve = undefined;
+                if (killedReason !== null) {
+                    r({
+                        trigger: req.trigger,
+                        reason: killedReason,
+                        error: `被杀（${killedReason === 'timeout' ? '墙钟超时' : '新实例抢占'}）`,
+                        finishedAt: now(),
+                    });
+                    return;
+                }
+                if (signal) {
+                    r({
+                        trigger: req.trigger,
+                        reason: 'killed',
+                        error: `外部信号 ${signal} 终止`,
+                        finishedAt: now(),
+                    });
+                    return;
+                }
+                const outcome = {
+                    trigger: req.trigger,
+                    reason: 'exit_code',
+                    exitCode: code ?? 1,
+                    finishedAt: now(),
+                };
+                const preview = stdoutTail.trim();
+                if (preview)
+                    outcome.finalTextPreview = preview.slice(0, PREVIEW_CAP);
+                if ((code ?? 1) !== 0 && stderrTail.trim()) {
+                    outcome.error = lastLine(stderrTail).slice(0, PREVIEW_CAP);
+                }
+                void startedAtMs;
+                r(outcome);
+            });
+            return handle;
+        },
+    };
+}
+/** 进程组信号（detached 子进程 pid 即组号——先组后单 pid 兜底） */
+function signalTree(child, sig) {
+    if (typeof child.pid === 'number') {
+        try {
+            process.kill(-child.pid, sig);
+        }
+        catch {
+            /* 组不存在——单 pid 兜底 */
+        }
+    }
+    try {
+        child.kill(sig);
+    }
+    catch {
+        /* 已死 */
+    }
+}
+/** 错误转人读串 */
+function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** 尾行提取（错误摘要取末条非空行——pi-tick extractStderrSignature 保守档） */
+function lastLine(text) {
+    const lines = text.trimEnd().split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim() ?? '';
+        if (line)
+            return line;
+    }
+    return '';
+}

package/dist/scheduler/schedule.js

@@ -0,0 +1,193 @@
+/**
+ * schedule 串的词法、校验与下次到点计算（04 §12 调度条——schedule 形落码面；
+ * 词面承 pi-tick 三形 interval/daily/weekly + pilotdeck once/delay 补形）。
+ *
+ * 串形五写四形（once 有绝对/相对两写）：
+ *   every:<n>[s|m|h]        间隔重复（n 正整数；总秒数下限 5s）
+ *   once@+<n>[s|m|h]        一次性相对延迟（自建行时刻起）
+ *   once@<ISO>              一次性绝对时刻
+ *   daily@HH:MM             每日（本地时区 24h 制）
+ *   weekly@<days>@HH:MM     每周（days = 逗号分隔 mon/tue/.../sun 全写或三写）
+ *
+ * 判据全纯函数：解析/校验/推 next-fire 三段零 IO 零时钟——时钟由调用方注入
+ * （Date 形），测试确定性。语义钉死三条：
+ *   ① once 触发后不再到点（next = null——行留表、list 可见、不再 due）；
+ *   ② 错过不重放：next-fire 一律取「严格晚于 now 的下一刻」（宿主停机期的
+ *      错过到点重启后直接跳下一刻——pi-tick/launchd/cron 同律）；
+ *   ③ daily/weekly 按本地时区解释（用户面语义），存储/比较一律 ISO UTC。
+ */
+import { BaseError } from '../contracts/index.js';
+/** 间隔下限（秒）——进程内挂钟最小粒度（pi-tick macOS 后端同值 5s） */
+export const MIN_INTERVAL_SECONDS = 5;
+/** 周 day 数值（0=周日……6=周六——Date.getDay 同系，跨端无歧义） */
+const DAY_NAMES = {
+    sunday: 0,
+    sun: 0,
+    monday: 1,
+    mon: 1,
+    tuesday: 2,
+    tue: 2,
+    wednesday: 3,
+    wed: 3,
+    thursday: 4,
+    thu: 4,
+    friday: 5,
+    fri: 5,
+    saturday: 6,
+    sat: 6,
+};
+/** HH:MM 24h 制词法（pi-tick TIME_REGEX 同形） */
+const TIME_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+/** 时长因子：s=1 / m=60 / h=3600 */
+const UNIT_SECONDS = { s: 1, m: 60, h: 3600 };
+/** 相对时长段解析：`<n>[s|m|h]` → 秒数（违例返回 null——不猜不夹取） */
+function parseDuration(text) {
+    const m = text.match(/^(\d+)([smh])$/);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = UNIT_SECONDS[m[2] ?? ''] ?? 0;
+    if (!Number.isSafeInteger(n) || n <= 0)
+        return null;
+    return n * unit;
+}
+/**
+ * schedule 串 → canonical 形（词法/语义全验——坏串抛 SCHEDULER_SCHEDULE_INVALID，
+ * message 载原因；GoalJobsFace register 的「响亮拒不炸装配」消费此 message）。
+ */
+export function parseSchedule(text) {
+    const raw = text.trim();
+    const every = raw.match(/^every:(\d+[smh])$/);
+    if (every) {
+        const seconds = parseDuration(every[1] ?? '');
+        if (seconds === null)
+            throw badSchedule(raw, 'every 时长段坏形');
+        if (seconds < MIN_INTERVAL_SECONDS) {
+            throw badSchedule(raw, `间隔下限 ${MIN_INTERVAL_SECONDS}s（得 ${seconds}s）`);
+        }
+        return { kind: 'every', seconds };
+    }
+    const onceRel = raw.match(/^once@\+(\d+[smh])$/);
+    if (onceRel) {
+        // 相对延迟的锚定时刻由建行方落 at（parse 只验词法——纯函数不触时钟）
+        const seconds = parseDuration(onceRel[1] ?? '');
+        if (seconds === null)
+            throw badSchedule(raw, 'once 相对时长段坏形');
+        return { kind: 'once', at: `+${seconds}` };
+    }
+    const onceAbs = raw.match(/^once@(.+)$/);
+    if (onceAbs) {
+        const at = onceAbs[1] ?? '';
+        const t = Date.parse(at);
+        if (Number.isNaN(t))
+            throw badSchedule(raw, 'once 绝对时刻非合法 ISO');
+        return { kind: 'once', at: new Date(t).toISOString() };
+    }
+    const daily = raw.match(/^daily@(\d{2}:\d{2})$/);
+    if (daily && TIME_RE.test(daily[1] ?? '')) {
+        return { kind: 'daily', time: daily[1] ?? '' };
+    }
+    const weekly = raw.match(/^weekly@([a-z,]+)@(\d{2}:\d{2})$/);
+    if (weekly && TIME_RE.test(weekly[2] ?? '')) {
+        const days = parseDays(weekly[1] ?? '');
+        if (!days)
+            throw badSchedule(raw, 'weekly 星期段坏形');
+        return { kind: 'weekly', days, time: weekly[2] ?? '' };
+    }
+    throw badSchedule(raw, '须为 every:<n>[smh] / once@+<n>[smh] / once@<ISO> / daily@HH:MM / weekly@<days>@HH:MM 之一');
+}
+/** 星期段解析：逗号分隔名 → 去重升序 day 数组（坏名返回 null） */
+function parseDays(text) {
+    if (!/^[a-z,]+$/.test(text))
+        return null;
+    const days = new Set();
+    for (const token of text.split(',')) {
+        const d = DAY_NAMES[token ?? ''];
+        if (d === undefined)
+            return null;
+        days.add(d);
+    }
+    return [...days].sort((a, b) => a - b);
+}
+/** 坏串抛手（message 前缀统一——含原串便于诊断） */
+function badSchedule(raw, reason) {
+    return new BaseError('SCHEDULER_SCHEDULE_INVALID', `schedule 串「${raw}」坏形：${reason}`);
+}
+/** canonical 形 → 人读串（/tick list 渲染与日志面；往返 parse(format(x)) 恒等） */
+export function formatSchedule(s) {
+    switch (s.kind) {
+        case 'every':
+            return `every:${formatSeconds(s.seconds)}`;
+        case 'once':
+            return `once@${s.at}`;
+        case 'daily':
+            return `daily@${s.time}`;
+        case 'weekly':
+            return `weekly@${s.days.map((d) => DAY_SHORT[d] ?? String(d)).join(',')}@${s.time}`;
+    }
+}
+/** day 数值 → 三写名（formatSchedule weekly 段用） */
+const DAY_SHORT = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+/** 秒数 → 紧凑时长段（86400 内取最大单位整除形；不合整除回落秒形） */
+function formatSeconds(total) {
+    if (total % 3600 === 0)
+        return `${total / 3600}h`;
+    if (total % 60 === 0)
+        return `${total / 60}m`;
+    return `${total}s`;
+}
+/** once 相对延迟形（at 以 '+' 开头）的锚定落值：base + 秒数 */
+export function resolveRelativeOnce(s, base) {
+    if (s.kind !== 'once' || !s.at.startsWith('+'))
+        return s;
+    const seconds = Number(s.at.slice(1));
+    return { kind: 'once', at: new Date(base.getTime() + seconds * 1000).toISOString() };
+}
+/**
+ * 下次到点（严格晚于 now 的下一刻；once 已过或相对未锚定 → null）。
+ *
+ * `anchor` 仅 every 形消费：上次触发时刻缺省（建行/重启补推进场景）时以
+ * now 起算——「错过不重放」语义的落点（past 的 next 直接跳下一刻）。
+ */
+export function nextFireAt(s, now, anchor) {
+    switch (s.kind) {
+        case 'every': {
+            const base = anchor && anchor.getTime() < now.getTime() ? now : (anchor ?? now);
+            return new Date(base.getTime() + s.seconds * 1000).toISOString();
+        }
+        case 'once': {
+            if (s.at.startsWith('+'))
+                return null; // 相对未锚定——建行方先过 resolveRelativeOnce
+            const t = Date.parse(s.at);
+            return t > now.getTime() ? new Date(t).toISOString() : null;
+        }
+        case 'daily':
+            return nextDailyAt(now, s.time);
+        case 'weekly':
+            return nextWeeklyAt(now, s.days, s.time);
+    }
+}
+/** 每日下一刻（本地时区；今日时刻已过取明日） */
+function nextDailyAt(now, hhmm) {
+    const [h, m] = hhmm.split(':').map(Number);
+    const cand = new Date(now);
+    cand.setHours(h ?? 0, m ?? 0, 0, 0);
+    if (cand.getTime() <= now.getTime())
+        cand.setDate(cand.getDate() + 1);
+    return cand.toISOString();
+}
+/** 每周下一刻（候选日全算取最早严格未来；跨周自动落到下周同日） */
+function nextWeeklyAt(now, days, hhmm) {
+    const [h, m] = hhmm.split(':').map(Number);
+    let best = null;
+    for (const d of days) {
+        const cand = new Date(now);
+        cand.setHours(h ?? 0, m ?? 0, 0, 0);
+        cand.setDate(cand.getDate() + ((d - now.getDay() + 7) % 7));
+        if (cand.getTime() <= now.getTime())
+            cand.setDate(cand.getDate() + 7);
+        if (best === null || cand.getTime() < best.getTime())
+            best = cand;
+    }
+    return best ? best.toISOString() : new Date(now).toISOString();
+}

package/dist/scheduler/service.js

@@ -0,0 +1,283 @@
+/**
+ * scheduler 服务面（04 §12）：jobs 表 DAO + /tick 六动词的程序形态 +
+ * GoalJobsFace 四法窄面（第五槽——goal 件挂钟行的单漏斗写路径）。
+ *
+ * 分工线（04 §12「同一 jobs 表两视角」）：本面管 **jobs 表行**（挂钟行的注册
+ * 管理面）；运行中实例的 in-flight 记账归引擎内存表（§10 ctx.jobs 系另册，
+ * 语义不在此）。enable/disable **直打 jobs 表行**（幽灵名零行守卫——
+ * SCHEDULER_NOT_FOUND 响亮拒，2026-09-04 berry 侧同款守卫）；add **名冲突守卫**
+ * （SCHEDULER_NAME_EXISTS）。cron 可选后端在场时启停/rm 与 OS 注册面联动
+ * （联动细则 = 本件落码面裁决：行翻转与 crontab 同步两段——OS 段失败亮拒
+ * 不半态）。
+ */
+import { statSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { BaseError } from '../contracts/index.js';
+import { formatSchedule, nextFireAt, parseSchedule, resolveRelativeOnce } from './schedule.js';
+/** 任务名词法（pi-tick id 规则同形——goal-<goalId> 挂钟行名同型合法） */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/** prompt 硬帽（16KiB——pi-tick 同值） */
+const PROMPT_MAX_BYTES = 16 * 1024;
+/** jobs 表 DAO（service/engine 共用——行映射蛇 ↔ 驼峰单源） */
+export class JobsDao {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /** 行查（名寻径；缺席 undefined） */
+    get(name) {
+        const row = this.db
+            .prepare(`SELECT name, prompt, cwd, schedule, enabled, builtin, created_at, updated_at,
+                next_fire_at, last_fire_at, last_outcome, active_pid, active_started_at
+         FROM jobs WHERE name = ?`)
+            .get(name);
+        return row ? fromDb(row) : undefined;
+    }
+    /** 全行清单（名序——/tick list 观察面） */
+    list() {
+        const rows = this.db
+            .prepare(`SELECT name, prompt, cwd, schedule, enabled, builtin, created_at, updated_at,
+                next_fire_at, last_fire_at, last_outcome, active_pid, active_started_at
+         FROM jobs ORDER BY name`)
+            .all();
+        return rows.map(fromDb);
+    }
+    /** due 集（启用且到点——挂钟推进轮询面；next_fire_at 升序） */
+    due(now) {
+        const rows = this.db
+            .prepare(`SELECT name, prompt, cwd, schedule, enabled, builtin, created_at, updated_at,
+                next_fire_at, last_fire_at, last_outcome, active_pid, active_started_at
+         FROM jobs
+         WHERE enabled = 1 AND next_fire_at IS NOT NULL AND next_fire_at <= ?
+         ORDER BY next_fire_at`)
+            .all(now);
+        return rows.map(fromDb);
+    }
+    /** 启用行的下次到点最小值（挂钟下轮调度间隔计算面；无启用行 null） */
+    earliestNextFire() {
+        const row = this.db
+            .prepare(`SELECT MIN(next_fire_at) AS m FROM jobs WHERE enabled = 1 AND next_fire_at IS NOT NULL`)
+            .get();
+        return row.m;
+    }
+    /** 建行（名主键冲突由调用方守卫——DAO 不吞） */
+    insert(row) {
+        this.db
+            .prepare(`INSERT INTO jobs (name, prompt, cwd, schedule, enabled, builtin, created_at,
+                           updated_at, next_fire_at, last_fire_at, last_outcome,
+                           active_pid, active_started_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(row.name, row.prompt, row.cwd, JSON.stringify(row.schedule), row.enabled ? 1 : 0, row.builtin ? 1 : 0, row.createdAt, row.updatedAt, row.nextFireAt, row.lastFireAt, row.lastOutcome === null ? null : JSON.stringify(row.lastOutcome), row.activePid, row.activeStartedAt);
+    }
+    /** 更新启停位与时间戳（enable/disable 直打） */
+    setEnabled(name, enabled, updatedAt) {
+        this.db.prepare(`UPDATE jobs SET enabled = ?, updated_at = ? WHERE name = ?`).run(enabled ? 1 : 0, updatedAt, name);
+    }
+    /** 删行 */
+    remove(name) {
+        this.db.prepare(`DELETE FROM jobs WHERE name = ?`).run(name);
+    }
+    /** 结算回写：last_fire_at + last_outcome + next_fire_at 推进（fire 收场单点） */
+    settleFire(name, firedAt, outcome, nextFireAt, updatedAt) {
+        this.db
+            .prepare(`UPDATE jobs SET last_fire_at = ?, last_outcome = ?, next_fire_at = ?, updated_at = ?
+         WHERE name = ?`)
+            .run(firedAt, JSON.stringify(outcome), nextFireAt, updatedAt, name);
+    }
+    /** next_fire_at 单列推进（重启补推进/闸拦跳过——不动 last_fire_at） */
+    advanceNextFire(name, nextFireAt, updatedAt) {
+        this.db.prepare(`UPDATE jobs SET next_fire_at = ?, updated_at = ? WHERE name = ?`).run(nextFireAt, updatedAt, name);
+    }
+    /** gated 结算：记拦截结局 + 推进 next（不动 last_fire_at——gated 非真跑，冷却闸判据不被污染） */
+    settleGated(name, outcome, nextFireAt, updatedAt) {
+        this.db
+            .prepare(`UPDATE jobs SET last_outcome = ?, next_fire_at = ?, updated_at = ? WHERE name = ?`)
+            .run(JSON.stringify(outcome), nextFireAt, updatedAt, name);
+    }
+    /** 跨进程在飞占用面写/清（OS cron 后端 --tick 子进程建占用） */
+    setActive(name, pid, startedAt, updatedAt) {
+        this.db
+            .prepare(`UPDATE jobs SET active_pid = ?, active_started_at = ?, updated_at = ? WHERE name = ?`)
+            .run(pid, startedAt, updatedAt, name);
+    }
+}
+/** DB 行 → 契约行（schedule/last_outcome JSON 解析坏值容错降级——行是自有面，坏值 warn 不炸读） */
+function fromDb(row) {
+    let schedule;
+    try {
+        schedule = JSON.parse(row.schedule);
+    }
+    catch {
+        schedule = { kind: 'once', at: new Date(0).toISOString() };
+    }
+    let lastOutcome = null;
+    if (row.last_outcome) {
+        try {
+            lastOutcome = JSON.parse(row.last_outcome);
+        }
+        catch {
+            lastOutcome = null;
+        }
+    }
+    return {
+        name: row.name,
+        prompt: row.prompt,
+        cwd: row.cwd,
+        schedule,
+        enabled: row.enabled === 1,
+        builtin: row.builtin === 1,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        nextFireAt: row.next_fire_at,
+        lastFireAt: row.last_fire_at,
+        lastOutcome,
+        activePid: row.active_pid,
+        activeStartedAt: row.active_started_at,
+    };
+}
+/** 服务装配（cronRegistrar/pathExists 缺省形态见 deps 注释） */
+export function createSchedulerService(deps) {
+    const dao = new JobsDao(deps.db);
+    const pathExists = deps.pathExists ?? ((p) => statExists(p));
+    const now = deps.now;
+    /** 建行共核（add 与 goalJobs.register 单源——守卫/next_fire 初值全同律） */
+    function insertRow(req, builtin) {
+        if (!NAME_RE.test(req.name)) {
+            throw new BaseError('SCHEDULER_NAME_INVALID', `任务名「${req.name}」违例：须匹配 ${NAME_RE.source}（首字符字母数字、总长 ≤64）`);
+        }
+        if (dao.get(req.name)) {
+            throw new BaseError('SCHEDULER_NAME_EXISTS', `任务名「${req.name}」已被占用（jobs 表既有行）`);
+        }
+        const promptBytes = Buffer.byteLength(req.prompt, 'utf8');
+        if (req.prompt.length === 0 || promptBytes > PROMPT_MAX_BYTES) {
+            throw new BaseError('SCHEDULER_JOB_INVALID', `prompt 须非空且 ≤16KiB（得 ${promptBytes} 字节）`);
+        }
+        if (req.cwd !== null && req.cwd !== undefined) {
+            if (!isAbsolute(req.cwd)) {
+                throw new BaseError('SCHEDULER_JOB_INVALID', `cwd 须绝对路径（得「${req.cwd}」）`);
+            }
+            if (!pathExists(req.cwd)) {
+                throw new BaseError('SCHEDULER_JOB_INVALID', `cwd 不存在（建行时点判——「${req.cwd}」）`);
+            }
+        }
+        const schedule = resolveRelativeOnce(parseSchedule(req.schedule), new Date(now()));
+        const enabled = req.enabled === true;
+        const ts = now();
+        const row = {
+            name: req.name,
+            prompt: req.prompt,
+            cwd: req.cwd ?? null,
+            schedule,
+            enabled,
+            builtin,
+            createdAt: ts,
+            updatedAt: ts,
+            nextFireAt: enabled ? nextFireAt(schedule, new Date(ts)) : null,
+            lastFireAt: null,
+            lastOutcome: null,
+            activePid: null,
+            activeStartedAt: null,
+        };
+        dao.insert(row);
+        return row;
+    }
+    const service = {
+        addJob(req) {
+            return insertRow(req, false);
+        },
+        addBuiltinJob(req) {
+            return insertRow(req, true);
+        },
+        listJobs() {
+            return dao.list();
+        },
+        getJob(name) {
+            return dao.get(name);
+        },
+        removeJob(name) {
+            const row = dao.get(name);
+            if (!row)
+                throw new BaseError('SCHEDULER_NOT_FOUND', `任务「${name}」不存在（rm 幽灵名零行守卫）`);
+            if (deps.cronRegistrar && row.enabled) {
+                deps.cronRegistrar.unregister(name); // 失败抛 SCHEDULER_CRON_*——行不删（不半态）
+            }
+            dao.remove(name);
+        },
+        setJobEnabled(name, enabled) {
+            const row = dao.get(name);
+            if (!row) {
+                throw new BaseError('SCHEDULER_NOT_FOUND', `任务「${name}」不存在（${enabled ? 'enable' : 'disable'} 幽灵名零行守卫）`);
+            }
+            if (deps.cronRegistrar) {
+                if (enabled)
+                    deps.cronRegistrar.register(row); // OS 注册失败抛——行不翻转
+                else
+                    deps.cronRegistrar.unregister(name);
+            }
+            dao.setEnabled(name, enabled, now());
+            // 启用即刻排 next_fire（禁用期未排；once 相对形建行已锚定、every/daily/weekly 从现在取下一刻）
+            if (enabled) {
+                const fresh = dao.get(name);
+                if (fresh) {
+                    dao.advanceNextFire(name, nextFireAt(fresh.schedule, new Date(now()), fresh.lastFireAt ? new Date(fresh.lastFireAt) : undefined), now());
+                }
+            }
+            else {
+                dao.advanceNextFire(name, null, now()); // 停用即摘排（行留史）
+            }
+        },
+        describeSchedule(name) {
+            const row = dao.get(name);
+            return row ? formatSchedule(row.schedule) : '';
+        },
+    };
+    // ── GoalJobsFace 四法（第五槽窄面——挂钟行一切写经此单漏斗） ─────────────
+    const goalJobs = {
+        async register(req) {
+            const name = `goal-${req.goalId}`;
+            try {
+                const row = insertRow({ name, prompt: req.promptSnapshot, schedule: req.schedule, enabled: true, builtin: true }, true);
+                if (deps.cronRegistrar)
+                    deps.cronRegistrar.register(row); // 挂钟行启用即挂 OS（乙案形态）
+                return { ok: true, message: `挂钟已挂：${name}（${formatSchedule(row.schedule)}）` };
+            }
+            catch (err) {
+                // 响亮拒不炸装配——message 载码与原因（goal 件消费方落诊断面）
+                const message = err instanceof BaseError ? `${err.code}: ${err.message}` : String(err);
+                return { ok: false, message };
+            }
+        },
+        async disable(goalId) {
+            const name = `goal-${goalId}`;
+            if (!dao.get(name))
+                return; // 无行 = 静默 no-op
+            service.setJobEnabled(name, false); // 行留史（enable 可复活）
+        },
+        async enable(goalId) {
+            const name = `goal-${goalId}`;
+            if (!dao.get(name))
+                return; // 无行 = 静默 no-op
+            service.setJobEnabled(name, true);
+        },
+        async remove(goalId) {
+            const name = `goal-${goalId}`;
+            const row = dao.get(name);
+            if (!row)
+                return; // 无行 = 静默 no-op
+            if (deps.cronRegistrar && row.enabled)
+                deps.cronRegistrar.unregister(name); // 同步注销 OS 注册态
+            dao.remove(name);
+        },
+    };
+    return { service, dao, goalJobs };
+}
+/** cwd 存在判真身（缺省形态——测试注 pathExists 假件后不触盘） */
+function statExists(p) {
+    try {
+        statSync(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}