peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/cli/commands/cron-commands.js

@@ -0,0 +1,257 @@
+/**
+ * `peaks cron` — slice 2026-07-29-worktree-l2-extended Part 14.
+ *
+ * Persistent scheduled-task system. Stores a JSON schedule at
+ * `.peaks/cron/schedule.json` and lets the LLM-side runner
+ * trigger tasks synchronously (`peaks cron run <id>`) or
+ * register a built-in periodic lease gc that the runbook
+ * (`skills/peaks-code/`) checks on every session start.
+ *
+ * Built-in tasks (the only ones auto-registered today):
+ *   - `lease-gc-daily` — runs `peaks worktree gc --all-sessions
+ *     --project .` once every 24h. Cleans up orphan leases that
+ *     leaked past their auto-release hook (Part 3.A) — the
+ *     safety net for the safety net.
+ *
+ * Why a JSON file (not a real cron daemon): peaks-loop is a CLI
+ * tool, not a service. The schedule is best-effort: the runbook
+ * checks it on session start and surfaces overdue tasks. A
+ * proper system cron / systemd timer is the production
+ * deployment story; this CLI is the portable fallback.
+ *
+ * File layout:
+ *   .peaks/cron/schedule.json — registered tasks with their
+ *     interval + lastRunAt
+ *   .peaks/cron/history.jsonl — append-only run history
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const SCHEDULE_VERSION = 1;
+const SCHEDULE_FILENAME = 'schedule.json';
+const HISTORY_FILENAME = 'history.jsonl';
+const DEFAULT_INTERVAL_MS = 24 * 60 * 60 * 1_000; // 24h
+function cronDir(projectRoot) {
+    return join(projectRoot, '.peaks', 'cron');
+}
+function schedulePath(projectRoot) {
+    return join(cronDir(projectRoot), SCHEDULE_FILENAME);
+}
+function historyPath(projectRoot) {
+    return join(cronDir(projectRoot), HISTORY_FILENAME);
+}
+export function readSchedule(projectRoot) {
+    const path = schedulePath(projectRoot);
+    if (!existsSync(path))
+        return { version: SCHEDULE_VERSION, entries: [] };
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`schedule.json malformed: ${err.message}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw new Error('schedule.json root must be an object');
+    }
+    const obj = parsed;
+    if (obj.version !== SCHEDULE_VERSION) {
+        throw new Error(`schedule.json version mismatch (got ${String(obj.version)}, expected ${SCHEDULE_VERSION})`);
+    }
+    if (!Array.isArray(obj.entries)) {
+        throw new Error('schedule.json entries must be an array');
+    }
+    const entries = [];
+    for (const e of obj.entries) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const ent = e;
+        if (typeof ent.id !== 'string' || typeof ent.name !== 'string' || typeof ent.command !== 'string')
+            continue;
+        if (!Array.isArray(ent.args) || !ent.args.every((a) => typeof a === 'string'))
+            continue;
+        if (typeof ent.intervalMs !== 'number' || typeof ent.createdAt !== 'number')
+            continue;
+        entries.push({
+            id: ent.id,
+            name: ent.name,
+            command: ent.command,
+            args: ent.args,
+            intervalMs: ent.intervalMs,
+            lastRunAt: typeof ent.lastRunAt === 'number' ? ent.lastRunAt : null,
+            enabled: ent.enabled !== false,
+            createdAt: ent.createdAt
+        });
+    }
+    return { version: SCHEDULE_VERSION, entries };
+}
+function writeSchedule(projectRoot, file) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(schedulePath(projectRoot), `${JSON.stringify(file, null, 2)}\n`, 'utf8');
+}
+export function appendHistory(projectRoot, record) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = historyPath(projectRoot);
+    const line = `${JSON.stringify(record)}\n`;
+    if (!existsSync(path)) {
+        writeFileSync(path, line, 'utf8');
+    }
+    else {
+        // Append — small file, OK to read+write
+        const existing = readFileSync(path, 'utf8');
+        writeFileSync(path, existing + line, 'utf8');
+    }
+}
+function ensureLeaseGcEntry(file) {
+    if (file.entries.some((e) => e.id === 'lease-gc-daily'))
+        return file;
+    const entry = {
+        id: 'lease-gc-daily',
+        name: 'Daily lease listing — refresh the alive-lease set; operators run peaks worktree gc --lease-id <id> manually on stale entries',
+        command: 'worktree',
+        args: ['list'],
+        intervalMs: DEFAULT_INTERVAL_MS,
+        lastRunAt: null,
+        enabled: true,
+        createdAt: Date.now()
+    };
+    return { version: SCHEDULE_VERSION, entries: [...file.entries, entry] };
+}
+export function runTask(projectRoot, task) {
+    const id = randomUUID();
+    const startedAt = Date.now();
+    let exitCode = 0;
+    let stderr = '';
+    try {
+        execSync(`peaks ${task.command} ${task.args.map((a) => `"${a.replace(/"/g, '\\"')}"`).join(' ')}`, {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            encoding: 'utf8',
+            timeout: 5 * 60_000
+        });
+    }
+    catch (err) {
+        const e = err;
+        exitCode = typeof e.status === 'number' ? e.status : 1;
+        stderr = (e.stderr ?? getErrorMessage(err)).slice(0, 2000);
+    }
+    const record = {
+        id,
+        taskId: task.id,
+        startedAt,
+        finishedAt: Date.now(),
+        exitCode,
+        stderr
+    };
+    appendHistory(projectRoot, record);
+    return record;
+}
+export function listDueTasks(projectRoot, now = Date.now()) {
+    const file = readSchedule(projectRoot);
+    return file.entries.filter((e) => {
+        if (!e.enabled)
+            return false;
+        if (e.lastRunAt === null)
+            return true;
+        return now - e.lastRunAt >= e.intervalMs;
+    });
+}
+export function registerCronCommand(program, io) {
+    const cmd = program
+        .command('cron')
+        .description('Persistent scheduled tasks (Part 14; companion to peaks worktree / peaks container).');
+    addJsonOption(cmd.command('init')
+        .description('Create .peaks/cron/schedule.json with the built-in tasks (currently: lease-gc-daily). Idempotent.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const updated = ensureLeaseGcEntry(file);
+            writeSchedule(projectRoot, updated);
+            const added = updated.entries.length - file.entries.length;
+            printResult(io, ok('cron.init', { projectRoot, schedulePath: schedulePath(projectRoot), totalEntries: updated.entries.length, added }, [], [
+                added > 0
+                    ? `Added ${added} built-in task(s). Use 'peaks cron list' to inspect.`
+                    : 'Schedule already contains the built-in tasks; no change made.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron.init', 'CRON_INIT_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                'Verify the project root is a peaks-loop project (.peaks/ exists).',
+                'Check filesystem permissions.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('list')
+        .description('List all registered cron tasks + their due status (relative to now).')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const now = Date.now();
+            const annotated = file.entries.map((e) => ({
+                ...e,
+                due: e.enabled && (e.lastRunAt === null || now - e.lastRunAt >= e.intervalMs),
+                nextDueAt: e.lastRunAt === null ? now : e.lastRunAt + e.intervalMs
+            }));
+            annotated.sort((a, b) => a.nextDueAt - b.nextDueAt);
+            printResult(io, ok('cron.list', { projectRoot, schedulePath: schedulePath(projectRoot), entries: annotated }, [], [
+                `${annotated.length} task(s); ${annotated.filter((e) => e.due).length} due now.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron.list', 'CRON_LIST_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                "If schedule.json is missing, run 'peaks cron init' first."
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('run')
+        .description('Run the specified task (by id) immediately, update lastRunAt, append a history record.')
+        .option('--id <taskId>', 'task id to run (default: all due tasks)')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const file = readSchedule(projectRoot);
+            const targets = options.id
+                ? file.entries.filter((e) => e.id === options.id)
+                : listDueTasks(projectRoot);
+            if (targets.length === 0) {
+                printResult(io, ok('cron.run', { projectRoot, ran: 0, records: [] }, [], ['No due tasks; nothing to run.']), options.json);
+                return;
+            }
+            const records = [];
+            const updatedEntries = [];
+            const now = Date.now();
+            for (const task of file.entries) {
+                if (!targets.some((t) => t.id === task.id)) {
+                    updatedEntries.push(task);
+                    continue;
+                }
+                const record = runTask(projectRoot, task);
+                records.push(record);
+                updatedEntries.push({ ...task, lastRunAt: record.finishedAt });
+            }
+            writeSchedule(projectRoot, { version: SCHEDULE_VERSION, entries: updatedEntries });
+            printResult(io, ok('cron.run', { projectRoot, ran: records.length, records }, records.filter((r) => r.exitCode !== 0).map((r) => `Task ${r.taskId} failed (exit=${r.exitCode}): ${r.stderr.slice(0, 200)}`), [`Ran ${records.length} task(s); ${records.filter((r) => r.exitCode === 0).length} succeeded.`]), options.json);
+            if (records.some((r) => r.exitCode !== 0))
+                process.exitCode = 1;
+        }
+        catch (err) {
+            printResult(io, fail('cron.run', 'CRON_RUN_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                "If schedule.json is missing, run 'peaks cron init' first."
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/cron-scheduler-commands.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `peaks cron scheduler start|stop|status|run-once` — slice 2026-07-29 Part 15.
+ *
+ * Companion CLI to Part 14 (peaks cron init/list/run). The
+ * scheduler is a long-running background daemon that wakes up
+ * once per minute, reads `.peaks/cron/schedule.json`, and runs
+ * any due tasks via detached execSync (so a misbehaving task
+ * cannot block the scheduler). Best-effort persistence via
+ * `.peaks/cron/scheduler.pid` (advisory — operators can `kill
+ * $(cat scheduler.pid)` if a stale entry lingers).
+ *
+ * Why a separate `peaks-cron-scheduler` CLI (not a peaks
+ * subcommand) — long-running daemons that are spawned from a
+ * `peaks ...` invocation confuse a future "which peaks version
+ * is running" check. A dedicated binary name keeps the
+ * scheduler's startup visible to operators.
+ *
+ * Windows: the scheduler writes its pid to a file. To run as
+ * a real Windows service, the operator wires NSSM (or
+ * node-windows) to call `peaks-cron-scheduler start` on
+ * service start. Future slice: ship an NSSM install recipe
+ * in the operator docs.
+ *
+ * POSIX: same pid-file pattern; an init.d / systemd unit
+ * file would call `peaks-cron-scheduler start` and rely on
+ * the scheduler to write its own pid. Or just run from
+ * `nohup peaks-cron-scheduler start &` if you don't need
+ * restart-on-crash.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCronSchedulerCommand(program: Command, io: ProgramIO): void;
+/**
+ * Standalone scheduler entry point (the process the CLI spawns).
+ * Runs a setInterval tick + reads schedule + runs due tasks.
+ * Exits cleanly on SIGTERM.
+ *
+ * Exported as `runSchedulerLoop` so the dedicated
+ * `peaks-cron-scheduler.js` entry shim can call it; the
+ * command-side `registerCronSchedulerCommand` only uses
+ * start/stop/status, not the loop.
+ */
+export declare function runSchedulerLoop(args: {
+    projectRoot: string;
+    tickMs?: number;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/cli/commands/cron-scheduler-commands.js

@@ -0,0 +1,284 @@
+/**
+ * `peaks cron scheduler start|stop|status|run-once` — slice 2026-07-29 Part 15.
+ *
+ * Companion CLI to Part 14 (peaks cron init/list/run). The
+ * scheduler is a long-running background daemon that wakes up
+ * once per minute, reads `.peaks/cron/schedule.json`, and runs
+ * any due tasks via detached execSync (so a misbehaving task
+ * cannot block the scheduler). Best-effort persistence via
+ * `.peaks/cron/scheduler.pid` (advisory — operators can `kill
+ * $(cat scheduler.pid)` if a stale entry lingers).
+ *
+ * Why a separate `peaks-cron-scheduler` CLI (not a peaks
+ * subcommand) — long-running daemons that are spawned from a
+ * `peaks ...` invocation confuse a future "which peaks version
+ * is running" check. A dedicated binary name keeps the
+ * scheduler's startup visible to operators.
+ *
+ * Windows: the scheduler writes its pid to a file. To run as
+ * a real Windows service, the operator wires NSSM (or
+ * node-windows) to call `peaks-cron-scheduler start` on
+ * service start. Future slice: ship an NSSM install recipe
+ * in the operator docs.
+ *
+ * POSIX: same pid-file pattern; an init.d / systemd unit
+ * file would call `peaks-cron-scheduler start` and rely on
+ * the scheduler to write its own pid. Or just run from
+ * `nohup peaks-cron-scheduler start &` if you don't need
+ * restart-on-crash.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { readSchedule, listDueTasks, runTask } from './cron-commands.js';
+const SCHEDULER_TICK_MS = 60_000; // 1 minute
+const PID_FILENAME = 'scheduler.pid';
+function schedulerPidPath(projectRoot) {
+    return join(projectRoot, '.peaks', 'cron', PID_FILENAME);
+}
+function readSchedulerPid(projectRoot) {
+    const p = schedulerPidPath(projectRoot);
+    if (!existsSync(p))
+        return null;
+    const raw = readFileSync(p, 'utf8').trim();
+    const pid = Number.parseInt(raw, 10);
+    if (!Number.isFinite(pid) || pid <= 0)
+        return null;
+    return pid;
+}
+function isPidAlive(pid) {
+    try {
+        // `process.kill(pid, 0)` does not actually kill; it just
+        // checks if the process exists. ESRCH means no such pid;
+        // EPERM means it exists but we don't have permission to
+        // signal it (still alive).
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        return code === 'EPERM';
+    }
+}
+function findSchedulerEntryPoint() {
+    // The peaks-cron-scheduler.js entry shim lives in bin/ (not
+    // dist/, so the pnpm build does not overwrite it). It forwards
+    // to dist/cli/commands/cron-scheduler-commands.js with
+    // PEAKS_CRON_SCHEDULER_DAEMON=1 set; the CLI detects the env
+    // and runs runSchedulerLoop directly.
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/cli/commands/cron-scheduler-commands.js → bin/peaks-cron-scheduler.js
+    return resolve(here, '..', '..', '..', 'bin', 'peaks-cron-scheduler.js');
+}
+export function registerCronSchedulerCommand(program, io) {
+    const cmd = program
+        .command('cron-scheduler')
+        .description('Long-running background scheduler for peaks cron tasks (Part 15).');
+    addJsonOption(cmd.command('start')
+        .description('Spawn the scheduler as a detached background process. Idempotent: refuses to start when an alive pid already exists.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const pidFile = schedulerPidPath(projectRoot);
+            const existing = readSchedulerPid(projectRoot);
+            if (existing !== null && isPidAlive(existing)) {
+                printResult(io, ok('cron-scheduler.start', { projectRoot, started: false, alreadyRunning: true, existingPid: existing }, [], [
+                    `Scheduler already running at pid ${existing}; not starting a second one.`,
+                    'Use `peaks cron-scheduler stop` first if you need to restart.'
+                ]), options.json);
+                return;
+            }
+            // Spawn detached via `peaks-cron-scheduler.js` — the
+            // child runs `runSchedulerLoop` (60s setInterval + due-task
+            // runner). The detached flag + stdio:ignore puts the
+            // scheduler in its own process group (POSIX) / detaches
+            // from the console (Windows). PEAKS_CRON_SCHEDULER_DAEMON
+            // env is the canonical "I'm the long-running child" signal.
+            const entry = findSchedulerEntryPoint();
+            const child = spawn(process.execPath, [entry, '--project', projectRoot], {
+                cwd: projectRoot,
+                stdio: 'ignore',
+                detached: true,
+                windowsHide: true,
+                env: { ...process.env, PEAKS_CRON_SCHEDULER: '1', PEAKS_CRON_SCHEDULER_DAEMON: '1' }
+            });
+            child.unref();
+            if (typeof child.pid !== 'number') {
+                throw new Error('spawn returned no pid');
+            }
+            writeFileSync(pidFile, String(child.pid), 'utf8');
+            printResult(io, ok('cron-scheduler.start', { projectRoot, started: true, pid: child.pid, pidFile }, [], [
+                `Scheduler started at pid ${child.pid}; logs go to .peaks/cron/scheduler.log.`,
+                'Use `peaks cron-scheduler status` to confirm it is alive; `stop` to terminate.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron-scheduler.start', 'SCHEDULER_START_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                'Verify the peaks-cron-scheduler.js entry point is on disk.',
+                'Check that the .peaks/cron/ directory is writable.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('stop')
+        .description('Send SIGTERM to the scheduler pid (best-effort; removes the pid file either way).')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const pid = readSchedulerPid(projectRoot);
+            if (pid === null) {
+                printResult(io, ok('cron-scheduler.stop', { projectRoot, stopped: false, reason: 'no-pid-file' }, [], ['No scheduler pid file found; nothing to stop.']), options.json);
+                return;
+            }
+            let signalSent = false;
+            if (isPidAlive(pid)) {
+                try {
+                    process.kill(pid, 'SIGTERM');
+                    signalSent = true;
+                }
+                catch {
+                    signalSent = false;
+                }
+            }
+            const pidFile = schedulerPidPath(projectRoot);
+            try {
+                unlinkSync(pidFile);
+            }
+            catch { /* best-effort */ }
+            printResult(io, ok('cron-scheduler.stop', { projectRoot, stopped: signalSent, pid, pidFile }, [], [
+                signalSent
+                    ? `Sent SIGTERM to pid ${pid}; pid file removed.`
+                    : `pid ${pid} was not alive; pid file removed.`
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron-scheduler.stop', 'SCHEDULER_STOP_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                'Verify the pid file is readable / the process is yours.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('status')
+        .description('Report whether the scheduler is alive + when it last ran a task.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const pid = readSchedulerPid(projectRoot);
+            const alive = pid !== null && isPidAlive(pid);
+            let schedule;
+            try {
+                schedule = readSchedule(projectRoot);
+            }
+            catch (err) {
+                schedule = { version: 1, entries: [] };
+            }
+            const due = alive ? listDueTasks(projectRoot) : [];
+            printResult(io, ok('cron-scheduler.status', { projectRoot, pid, alive, scheduleEntries: schedule.entries.length, dueTaskCount: due.length }, [], [alive
+                    ? `Scheduler alive at pid ${pid}; ${due.length} task(s) due now.`
+                    : 'Scheduler is NOT running. Use `peaks cron-scheduler start` to spawn.']), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('cron-scheduler.status', 'SCHEDULER_STATUS_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                'Verify the .peaks/cron/ directory exists.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(cmd.command('run-once')
+        .description('Synchronous foreground one-shot: run every currently-due task and exit. Useful for manual cron substitute.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const due = listDueTasks(projectRoot);
+            const records = due.map((t) => runTask(projectRoot, t));
+            printResult(io, ok('cron-scheduler.run-once', { projectRoot, ran: records.length, records }, [], [
+                `${records.length} due task(s) ran; ${records.filter((r) => r.exitCode === 0).length} succeeded.`
+            ]), options.json);
+            if (records.some((r) => r.exitCode !== 0))
+                process.exitCode = 1;
+        }
+        catch (err) {
+            printResult(io, fail('cron-scheduler.run-once', 'SCHEDULER_RUN_ONCE_FAILED', getErrorMessage(err), { projectRoot: options.project }, [
+                "If schedule.json is missing, run 'peaks cron init' first."
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+/**
+ * Standalone scheduler entry point (the process the CLI spawns).
+ * Runs a setInterval tick + reads schedule + runs due tasks.
+ * Exits cleanly on SIGTERM.
+ *
+ * Exported as `runSchedulerLoop` so the dedicated
+ * `peaks-cron-scheduler.js` entry shim can call it; the
+ * command-side `registerCronSchedulerCommand` only uses
+ * start/stop/status, not the loop.
+ */
+export async function runSchedulerLoop(args) {
+    const tickMs = args.tickMs ?? SCHEDULER_TICK_MS;
+    // Idempotency: refuse to start a second loop in the same
+    // process (the start CLI is expected to be a fresh spawn).
+    if (process.__peaksCronScheduler) {
+        throw new Error('scheduler loop already running in this process');
+    }
+    process.__peaksCronScheduler = true;
+    const tick = () => {
+        try {
+            const due = listDueTasks(args.projectRoot);
+            for (const task of due) {
+                runTask(args.projectRoot, task);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`[cron-scheduler] tick error: ${getErrorMessage(err)}\n`);
+        }
+    };
+    // First tick on entry (don't wait the full interval
+    // for the first run after a start).
+    tick();
+    const handle = setInterval(tick, tickMs);
+    // Wait for the abort signal (POSIX) or the platform
+    // equivalent. We don't use Node's process.on('SIGTERM')
+    // for portability — the parent process kills us via
+    // `process.kill(pid, 'SIGTERM')` and the event loop
+    // exits naturally if the interval is the only thing
+    // keeping the loop alive. We clearInterval on exit.
+    await new Promise((resolve) => {
+        const onAbort = () => {
+            clearInterval(handle);
+            resolve();
+        };
+        if (args.signal) {
+            args.signal.addEventListener('abort', onAbort, { once: true });
+        }
+        else {
+            // POSIX: SIGTERM. Windows: kill the process directly.
+            process.on('SIGTERM', onAbort);
+            process.on('SIGINT', onAbort);
+        }
+    });
+    process.exit(0);
+}
+// Standalone entry shim. When this file is run directly via
+// `node peaks-cron-scheduler.js`, the loop starts; when it is
+// imported (e.g. by the CLI), the export is used but the
+// loop is not started.
+if (process.env.PEAKS_CRON_SCHEDULER_DAEMON === '1') {
+    // Spawned by `peaks cron-scheduler start` as the long-running
+    // detached child. Run the loop until SIGTERM. Gated on the
+    // env var (not argv[1]) because on Windows a forked node
+    // process inherits the parent's argv[1] (which is bin/peaks.js).
+    const projectRoot = (() => {
+        const idx = process.argv.indexOf('--project');
+        return idx >= 0 ? process.argv[idx + 1] : findProjectRoot(process.cwd()) ?? process.cwd();
+    })();
+    runSchedulerLoop({ projectRoot }).catch((err) => {
+        process.stderr.write(`[cron-scheduler] fatal: ${getErrorMessage(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/cli/commands/dashboard-commands.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+/** Registers the top-level `peaks dashboard` command tree. */
+export declare function registerDashboardCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/dashboard-commands.js

@@ -0,0 +1,10 @@
+import { registerDashboardLongRunCommand } from './dashboard-long-run.js';
+import { registerDashboardSummaryCommand } from './dashboard-summary.js';
+/** Registers the top-level `peaks dashboard` command tree. */
+export function registerDashboardCommands(program, io) {
+    const dashboard = program
+        .command('dashboard')
+        .description('peaks dashboard surface (24h long-run view etc.)');
+    registerDashboardLongRunCommand(dashboard, io);
+    registerDashboardSummaryCommand(dashboard, io);
+}

package/dist/cli/commands/dashboard-long-run.d.ts

@@ -0,0 +1,25 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+type ParseResult = {
+    ok: true;
+    ms: number;
+} | {
+    ok: false;
+    error: string;
+};
+declare function parseSince(raw: string | undefined): ParseResult;
+type Boundary = {
+    key: 'empty' | 'cap' | 'valid';
+    message: string;
+};
+declare function boundaryLabel(raw: string): Boundary;
+export declare function registerDashboardLongRunCommand(dashboard: Command, io: ProgramIO): void;
+export declare const DASHBOARD_LONG_RUN_CONSTANTS: {
+    readonly WINDOW_CAP_HOURS: 24;
+    readonly WINDOW_CAP_MS: number;
+};
+export declare const __test__: {
+    parseSince: typeof parseSince;
+    boundaryLabel: typeof boundaryLabel;
+};
+export {};