peaks-loop 4.1.3 → 4.1.4

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

@@ -1,5 +1,4 @@
 /**
- *
  * 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
@@ -25,198 +24,48 @@
  * the scheduler to write its own pid. Or just run from
  * `nohup peaks-cron-scheduler start &` if you don't need
  * restart-on-crash.
+ *
+ * This file owns `registerCronSchedulerCommand`, `runSchedulerLoop` and the
+ * standalone entry shim the `bin/peaks-cron-scheduler.js` script loads; the
+ * four verb bodies live beside it, over the pid-file vocabulary in
+ * `cron-scheduler-shared.ts`.
  */
-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 { getErrorMessage } from 'peaks-loop-shared/result';
 import { findProjectRoot } from '../../services/config/config-safety.js';
-import { readSchedule, listDueTasks, runTask } from './cron-commands.js';
+import { listDueTasks, runTask } from './cron-commands.js';
 import { persistLastRunAt } from './cron-scheduler-persist.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');
-}
+import { SCHEDULER_TICK_MS } from './cron-scheduler-shared.js';
+import { registerCronSchedulerStartCommand } from './cron-scheduler-start-command.js';
+import { registerCronSchedulerStopCommand } from './cron-scheduler-stop-command.js';
+import { registerCronSchedulerStatusCommand } from './cron-scheduler-status-command.js';
+import { registerCronSchedulerRunOnceCommand } from './cron-scheduler-run-once-command.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));
-            // §2.24 applied to the one-shot path too: without it `run-once` under an
-            // external crontab re-ran the same task on every invocation.
-            persistLastRunAt(projectRoot, records);
-            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;
+    registerCronSchedulerStartCommand(cmd, io);
+    registerCronSchedulerStopCommand(cmd, io);
+    registerCronSchedulerStatusCommand(cmd, io);
+    registerCronSchedulerRunOnceCommand(cmd, io);
+}
+/** The loop's interval handle, cleared when the shutdown signal arrives. */
+function waitForShutdown(signal, handle) {
+    // 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.
+    return new Promise((resolveShutdown) => {
+        const onAbort = () => {
+            clearInterval(handle);
+            resolveShutdown();
+        };
+        if (signal) {
+            signal.addEventListener('abort', onAbort, { once: true });
         }
-        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;
+        else {
+            // POSIX: SIGTERM. Windows: kill the process directly.
+            process.on('SIGTERM', onAbort);
+            process.on('SIGINT', onAbort);
         }
     });
 }
@@ -246,7 +95,7 @@ export async function runSchedulerLoop(args) {
             // due. Without it `lastRunAt` stays null, `listDueTasks` keeps the entry
             // due, and a 24 h task re-fires on every 60,000 ms tick (measured: 6 fires
             // across 6 ticks, 1 after the write). Killed runs are deliberately NOT
-            // stamped — here, in `run-once` above, and since repair cycle 1 in `peaks
+            // stamped — here, in `run-once`, and since repair cycle 1 in `peaks
             // cron run` too; the rule and its per-platform costs are in
             // `cron-scheduler-persist.ts`.
             persistLastRunAt(args.projectRoot, records);
@@ -259,26 +108,7 @@ export async function runSchedulerLoop(args) {
     // 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);
-        }
-    });
+    await waitForShutdown(args.signal, handle);
     process.exit(0);
 }
 // Standalone entry shim. When this file is run directly via

package/dist/cli/commands/cron-scheduler-run-once-command.d.ts

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function runCronSchedulerRunOnce(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function registerCronSchedulerRunOnceCommand(cmd: Command, io: ProgramIO): void;

package/dist/cli/commands/cron-scheduler-run-once-command.js

@@ -0,0 +1,35 @@
+// src/cli/commands/cron-scheduler-run-once-command.ts
+//
+// `peaks cron-scheduler run-once` — the synchronous foreground one-shot.
+// Split out of `cron-scheduler-commands.ts`; the persistence step, the
+// success envelope and the exit-code rule are unchanged.
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { listDueTasks, runTask } from './cron-commands.js';
+import { persistLastRunAt } from './cron-scheduler-persist.js';
+export function runCronSchedulerRunOnce(io, options) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const due = listDueTasks(projectRoot);
+        const records = due.map((t) => runTask(projectRoot, t));
+        // §2.24 applied to the one-shot path too: without it `run-once` under an
+        // external crontab re-ran the same task on every invocation.
+        persistLastRunAt(projectRoot, records);
+        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 ?? false);
+        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 ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerCronSchedulerRunOnceCommand(cmd, io) {
+    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) => runCronSchedulerRunOnce(io, options));
+}

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

@@ -0,0 +1,6 @@
+export declare const SCHEDULER_TICK_MS = 60000;
+export declare const PID_FILENAME = "scheduler.pid";
+export declare function schedulerPidPath(projectRoot: string): string;
+export declare function readSchedulerPid(projectRoot: string): number | null;
+export declare function isPidAlive(pid: number): boolean;
+export declare function findSchedulerEntryPoint(): string;

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

@@ -0,0 +1,48 @@
+// src/cli/commands/cron-scheduler-shared.ts
+//
+// What every `peaks cron-scheduler *` verb shares: the tick period, the pid
+// file, and the two questions asked of it (is there a pid, is it alive) plus
+// where the detached child's entry shim lives. Split out of
+// `cron-scheduler-commands.ts`; every path, probe and constant is unchanged.
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export const SCHEDULER_TICK_MS = 60_000; // 1 minute
+export const PID_FILENAME = 'scheduler.pid';
+export function schedulerPidPath(projectRoot) {
+    return join(projectRoot, '.peaks', 'cron', PID_FILENAME);
+}
+export 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;
+}
+export 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';
+    }
+}
+export 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');
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function runCronSchedulerStart(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function registerCronSchedulerStartCommand(cmd: Command, io: ProgramIO): void;

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

@@ -0,0 +1,65 @@
+// src/cli/commands/cron-scheduler-start-command.ts
+//
+// `peaks cron-scheduler start` — spawn the scheduler as a detached background
+// process. Split out of `cron-scheduler-commands.ts`; the idempotency rule,
+// the spawn options, the pid file and both envelopes are unchanged.
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { findSchedulerEntryPoint, isPidAlive, readSchedulerPid, schedulerPidPath } from './cron-scheduler-shared.js';
+/**
+ * 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.
+ */
+function spawnDetachedScheduler(io, options, projectRoot, pidFile) {
+    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 ?? false);
+}
+export function runCronSchedulerStart(io, 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 ?? false);
+            return;
+        }
+        spawnDetachedScheduler(io, options, projectRoot, pidFile);
+    }
+    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 ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerCronSchedulerStartCommand(cmd, io) {
+    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) => runCronSchedulerStart(io, options));
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function runCronSchedulerStatus(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function registerCronSchedulerStatusCommand(cmd: Command, io: ProgramIO): void;

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

@@ -0,0 +1,46 @@
+// src/cli/commands/cron-scheduler-status-command.ts
+//
+// `peaks cron-scheduler status` — report whether the scheduler is alive and
+// how many tasks are due. Split out of `cron-scheduler-commands.ts`; the
+// degraded-tier schedule read and both envelopes are unchanged.
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { listDueTasks, readSchedule } from './cron-commands.js';
+import { isPidAlive, readSchedulerPid } from './cron-scheduler-shared.js';
+export function runCronSchedulerStatus(io, 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 {
+            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 ?? false);
+    }
+    catch (err) {
+        printResult(io, fail('cron-scheduler.status', 'SCHEDULER_STATUS_FAILED', getErrorMessage(err), { projectRoot: options.project }, ['Verify the .peaks/cron/ directory exists.']), options.json ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerCronSchedulerStatusCommand(cmd, io) {
+    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) => runCronSchedulerStatus(io, options));
+}

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

@@ -0,0 +1,7 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function runCronSchedulerStop(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function registerCronSchedulerStopCommand(cmd: Command, io: ProgramIO): void;

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

@@ -0,0 +1,61 @@
+// src/cli/commands/cron-scheduler-stop-command.ts
+//
+// `peaks cron-scheduler stop` — SIGTERM the scheduler pid (best-effort) and
+// remove the pid file either way. Split out of `cron-scheduler-commands.ts`;
+// the signal, the unlink and both envelopes are unchanged.
+import { unlinkSync } from 'node:fs';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { isPidAlive, readSchedulerPid, schedulerPidPath } from './cron-scheduler-shared.js';
+/** The no-pid-file outcome: nothing to signal, nothing to unlink. */
+function emitNoPidFile(io, options, projectRoot) {
+    printResult(io, ok('cron-scheduler.stop', { projectRoot, stopped: false, reason: 'no-pid-file' }, [], ['No scheduler pid file found; nothing to stop.']), options.json ?? false);
+}
+/** SIGTERM the pid (best-effort) and remove the pid file either way. */
+function terminateScheduler(projectRoot, pid) {
+    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 */
+    }
+    return { signalSent, pidFile };
+}
+export function runCronSchedulerStop(io, options) {
+    try {
+        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const pid = readSchedulerPid(projectRoot);
+        if (pid === null) {
+            emitNoPidFile(io, options, projectRoot);
+            return;
+        }
+        const { signalSent, pidFile } = terminateScheduler(projectRoot, pid);
+        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 ?? false);
+    }
+    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 ?? false);
+        process.exitCode = 1;
+    }
+}
+export function registerCronSchedulerStopCommand(cmd, io) {
+    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) => runCronSchedulerStop(io, options));
+}

package/dist/cli/commands/dispatch-dag-envelope.d.ts

@@ -0,0 +1,41 @@
+import type { SubAgentToolCall } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { SliceDag } from '../../services/dispatch/slice-dag.js';
+import type { SliceComplexity } from '../../services/dispatch/slice-dag-types.js';
+/** Everything the `--from-dag` success envelope reports, already resolved. */
+export type DagEnvelopeInput = {
+    readonly role: string;
+    readonly ide: string;
+    readonly fromDag: string;
+    readonly batchId: string;
+    readonly levelsTotal: number;
+    readonly emittedSliceIds: readonly string[];
+    readonly emittedToolCalls: readonly SubAgentToolCall[];
+    readonly firstLevelWaves: unknown;
+    readonly existingContractCount: number;
+    readonly dag: SliceDag;
+    readonly isSliceComplexity: (value: string) => value is SliceComplexity;
+};
+/** The `ok('sub-agent.dispatch', …)` envelope for a completed `--from-dag` run. */
+export declare function buildDagSuccessEnvelope(input: DagEnvelopeInput): import("peaks-loop-shared/result").ResultEnvelope<{
+    envelopeVersion: string;
+    role: string;
+    ide: string;
+    fromDag: string;
+    batchId: string;
+    dispatchCount: number;
+    levelsTotal: number;
+    firstLevel: readonly string[];
+    firstLevelWaves: unknown;
+    toolCalls: readonly SubAgentToolCall[];
+    existingContractCount: number;
+    expectedCompletionSeconds: number;
+    artifactsPublicPaths: never[];
+    orchestratorVisibleHint: string;
+    sliceMeta: {
+        id: string;
+        foundation: boolean;
+        upstreamSync: boolean;
+        complexity: SliceComplexity | null;
+    }[];
+    nextActions: string[];
+}>;