peaks-loop 4.1.2 → 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-command-spec.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function buildDispatchCommandSpec(parent: Command): Command;

package/dist/cli/commands/dispatch-command-spec.js

@@ -0,0 +1,62 @@
+import { addJsonOption } from '../cli-helpers.js';
+const DISPATCH_DESCRIPTION = 'Build an IDE-specific tool-call descriptor for a sub-agent dispatch. ' +
+    'Dry-run by design; the LLM executes the returned toolCall in its own ' +
+    'environment. Flags: --write-artifact (G7), ' +
+    '--force (G9 CLI 兜底). ' +
+    'See skills/peaks-code/references/sub-agent-dispatch.md for the ' +
+    'orchestrator contract.';
+function buildDispatchCommandBase(parent) {
+    return parent
+        .command('dispatch')
+        .description(DISPATCH_DESCRIPTION)
+        .argument('<role>', 'sub-agent role (e.g. rd | qa | ui | txt | qa-business | qa-business-api)');
+}
+function applyDispatchInputOptions(command) {
+    return (command
+        // 2.7.0 slice-dag-dispatcher MVP: --prompt is required ONLY when --from-dag is NOT
+        // supplied. Previously this was `.requiredOption('--prompt')`, which blocked
+        // `dispatch --from-dag <file>` calls because commander.js validates
+        // `.requiredOption` before the action handler runs. The mutual-exclusion
+        // check is enforced below in the action body (--prompt XOR --from-dag).
+        .option('--prompt <text>', 'the prompt to send to the sub-agent (required unless --from-dag is provided)')
+        .option('--prompt-length <bytes>', 'DOGFOOD ONLY: synthesize a prompt of this size (overrides --prompt content for size only; content is "x" repeated)')
+        .option('--request-id <rid>', 'the same <rid> used by peaks request init')
+        .option('--session-id <sid>', 'override active session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--batch-id <uuid>', 'batch id for the dispatch (default: auto-generated UUID)')
+        .option('--write-artifact <path>', 'G7: register an artifact file at <path>; CLI computes sha256 + size + writes ArtifactMeta to the dispatch record')
+        .option('--force', 'G9: override the 80% hard reject threshold at CLI (NOT allowed at hook layer per RL-30 strict)')
+        .option('--from-dag <file>', '2.7.0 slice-dag-dispatcher MVP: read a SliceDag JSON file, dispatch one sub-agent per node in topological order; --batch-id overrides the auto-generated batch id (mutually exclusive with <role>)')
+        .option('--isolation <mode>', 'slice 2026-07-29-worktree-l2-extended Part 2.C: isolation mode for the sub-agent. Accepts "worktree" (Part 2.C + Part 12 L2 surface), "container" (Part 8 contract + Part 12 L4 docker runtime), or "vm" (Part 25 contract; the VM runtime is a follow-up rid and fail-fasts with ISOLATION_VM_NOT_YET_IMPLEMENTED). Auto-spawns a lease + injects PEAKS_<MODE>_LEASE_ID into the dispatch envelope so the sub-agent can write to the isolated surface without a separate auth grant.')
+        // Slice 4.0.8 RD §4 made this a `.requiredOption`. It is optional now:
+        // the requirement was enforced but never validated — nothing downstream
+        // reads the node, and the record writer's graph transition is
+        // best-effort — so its only observable effect was to block dispatch in
+        // every project without graph infrastructure. See
+        // `provisionDispatchNode`.
+        .option('--graph-node <id>', 'graph node id this dispatch binds to (default: a node is provisioned on demand)')
+        .option('--workflow-id <id>', 'workflow id the graph node belongs to (defaults to derived from session)'));
+}
+function applyDispatchExecutionOptions(command) {
+    return (command
+        .option('--graph-ref <ref>', 'graphRef (defaults to graphs/<workflow-id>.json)')
+        // mode is `in-process` so the 106+ existing dispatch call sites
+        // keep their path byte-identical. The detached branch below
+        // fires only when --mode detached is explicitly passed.
+        .option('--mode <mode>', 'dispatch execution mode: in-process (default, dry-run envelope only) | detached (shell out to peaks-loop-internal-runtime/dispatch.dispatchDetached for real vendor CLI execution).')
+        .option('--vendor <vendor>', 'target vendor CLI for --mode detached (claude | codex | copilot). Ignored in the default in-process path.')
+        .option('--no-throttle', 'rid-001 detached: user-overrides ResourceBudgetGuard when concurrent fan-out exceeds max-concurrent (user accepts risk; surfaces as warning)')
+        .option('--max-concurrent <n>', 'rid-001 detached: override the per-tenant max concurrent budget (default 8). Effective in both detached and in-process paths.')
+        // §Lesson 1): the RD sub-agent's fake-green failure mode was that it
+        // claimed "5/5 reachability tests PASS" while the files were never
+        // on disk. `--must-ls-files <glob>` is the anti-fake-green gate:
+        // the CLI runs `git ls-files <glob>` upfront, reports the result in
+        // the envelope (`data.mustLsFilesVerification`), and prepends a
+        // `## must_ls_files enforcement` block to the sub-agent prompt so
+        // the LLM's first action MUST re-verify file existence before any
+        // "completed" claim. Absent → old behavior is preserved.
+        .option('--must-ls-files <glob>', 'F5: anti-fake-green gate. Run `git ls-files <glob>` upfront; surface the result in the envelope as `mustLsFilesVerification: { path, exists, files }`; prepend a must_ls_files enforcement block to the sub-agent prompt. Absent → unchanged behavior.'));
+}
+export function buildDispatchCommandSpec(parent) {
+    return addJsonOption(applyDispatchExecutionOptions(applyDispatchInputOptions(buildDispatchCommandBase(parent))));
+}