peaks-loop 4.0.53 → 4.1.0

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

@@ -8,10 +8,13 @@
  * (`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.
+ *   - `lease-gc-daily` — runs `peaks worktree list` once every 24h. This is a
+ *     daily lease LISTING that refreshes the alive-lease set; operators prune
+ *     a specific stale lease on demand with `peaks worktree gc --lease-id
+ *     <id>`. (Fixed in rid 2026-10-01-cron-exec-timeout-01 §2.22: this header
+ *     previously claimed the task ran `peaks worktree gc --all-sessions`,
+ *     which is not what `cron-commands-schedule.ts` registers — the code and
+ *     the entry's own name say `list`.)
  *
  * 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
@@ -23,248 +26,201 @@
  *   .peaks/cron/schedule.json — registered tasks with their
  *     interval + lastRunAt
  *   .peaks/cron/history.jsonl — append-only run history
+ *
+ * Module layout (wave 3 split, job strict-remediation-abc, slice
+ * c1-eslint-family-sweep): the schedule model lives in
+ * `cron-commands-schedule.ts` and the three action handlers in
+ * `cron-commands-actions.ts`. Every name exported from this path before the
+ * split is still importable from here. `runTask` stays here together with
+ * its exec-timeout constant (that constant carries this file's baseline
+ * `no-magic-numbers` warning; new siblings must be clean outright).
  */
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
 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';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { addJsonOption } from '../cli-helpers.js';
+import { appendHistory, MS_PER_SECOND, SECONDS_PER_MINUTE } from './cron-commands-schedule.js';
+import { handleCronInit, handleCronList, handleCronRun } from './cron-commands-actions.js';
+export { readSchedule, appendHistory, listDueTasks } from './cron-commands-schedule.js';
 /**
- * PRD-002b slice 2 — extract cron-orchestration magic numbers (24h
- * default interval, 5-minute exec timeout, stderr-message truncation
- * lengths in the renderer).
+ * PRD-002b slice 2 — cron-orchestration magic numbers, exec half. The
+ * interval/truncation constants live with the code that renders them
+ * (`cron-commands-schedule.ts` / `cron-commands-actions.ts`).
+ *
+ * Per-task exec timeout — FIVE MINUTES (300,000 ms). `runTask` hands this to
+ * `spawnSync(…, { timeout })`, which — with no shell in the way, see
+ * `resolveTaskEntry` — kills THE TASK PROCESS itself, so a task child that
+ * stalls is reaped within five minutes rather than inherited. Fixed in rid
+ * 2026-10-01-cron-exec-timeout-01: this constant previously read `5 *
+ * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND`, and `MINUTES_PER_HOUR
+ * * SECONDS_PER_MINUTE * MS_PER_SECOND` is one HOUR, so the value was 18,000,000
+ * ms (5 h) — five times too long, contradicting the name and the intent. See
+ * backlog §2.21.
  */
-const MS_PER_SECOND = 1_000;
-const MINUTES_PER_HOUR = 60;
-const SECONDS_PER_MINUTE = 60;
-const HOURS_PER_DAY = 24;
-const DEFAULT_INTERVAL_MS = HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
-const EXEC_TIMEOUT_MS = 5 * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MS_PER_SECOND;
+export const EXEC_TIMEOUT_MS = 5 * SECONDS_PER_MINUTE * MS_PER_SECOND;
 const STDERR_RECORD_TRUNCATE_BYTES = 2000;
-const STDERR_NEXT_ACTIONS_TRUNCATE_CHARS = 200;
-function cronDir(projectRoot) {
-    return join(projectRoot, '.peaks', 'cron');
-}
-function schedulePath(projectRoot) {
-    return join(cronDir(projectRoot), SCHEDULE_FILENAME);
+/**
+ * The exit code recorded when there is no child status to record (killed, or
+ * never spawned) — the same value the pre-fix `err.status ?? 1` collapsed to.
+ */
+const NO_CHILD_STATUS_EXIT_CODE = 1;
+function truncateStderr(text) {
+    return text.slice(0, STDERR_RECORD_TRUNCATE_BYTES);
 }
-function historyPath(projectRoot) {
-    return join(cronDir(projectRoot), HISTORY_FILENAME);
+/**
+ * A `bin/peaks.js` can boot only if the build it imports is there: the shim does
+ * `await import('../dist/cli/index.js')` relative to ITSELF (see `bin/peaks.js`).
+ * Every git worktree and bare checkout has the entry WITHOUT that build, so an
+ * existence test alone selects an entry that answers
+ * `exitCode 1 / "peaks-loop: internal module not found — the local build is
+ * stale or incomplete"` on every fire. Measured in
+ * `tests/unit/cli/commands/cron-task-tree-kill.test.ts` (F1, repair cycle 1 of
+ * rid 2026-10-01-cron-task-tree-kill-01).
+ */
+function isBootableTaskEntry(entry) {
+    return existsSync(entry) && existsSync(resolve(dirname(entry), '..', 'dist', 'cli', 'index.js'));
 }
-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
-        });
+/**
+ * The JS entry a task runs through.
+ *
+ * Two candidates, in this order, each a JS file spawned via `process.execPath`
+ * with an argv ARRAY — never a shell. The pre-fix shape was
+ * `execSync(\`peaks ${command} "${arg}"\`)`, which (a) put `cmd.exe` between the
+ * scheduler and the task, so `execSync`'s timeout killed the SHELL and orphaned
+ * the node grandchild (backlog §2.23, measured in diagnosis §9), and (b) relied
+ * on hand-quoting arguments because `shell: true` concatenates rather than
+ * escapes. This is the same shape `slice-check-service.ts` and
+ * `npx-resolver.ts` settled on after measuring that a `.cmd` shim cannot be
+ * spawned without a shell at all (EINVAL, Node 20+).
+ *
+ * The project's own entry wins so a task runs against the project it was
+ * scheduled for; when the project root is not a BUILT peaks package
+ * (`isBootableTaskEntry`) the running package's own entry takes the task, which
+ * is what the pre-fix PATH `peaks` shim resolved to. `null` means neither can
+ * boot — a loud fail-closed run, never work scheduled into a broken entry.
+ */
+function resolveTaskEntry(projectRoot) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    for (const candidate of [
+        join(projectRoot, 'bin', 'peaks.js'),
+        // dist/cli/commands/cron-commands.js → <package root>/bin/peaks.js
+        resolve(here, '..', '..', '..', 'bin', 'peaks.js')
+    ]) {
+        if (isBootableTaskEntry(candidate))
+            return candidate;
     }
-    return { version: SCHEDULE_VERSION, entries };
+    return null;
+}
+/**
+ * Fails CLOSED. There is no safe fallback spawn shape left to try: a `.cmd`
+ * shim needs a shell, and a shell re-introduces the orphan this slice removes.
+ * An entry that is missing OR unbuildable is therefore a loud non-zero run with
+ * a naming stderr, never a task silently skipped.
+ */
+function unresolvedEntryRun() {
+    return {
+        exitCode: NO_CHILD_STATUS_EXIT_CODE,
+        stderr: truncateStderr('task not run: no bootable `bin/peaks.js` (one needs its `dist/cli/index.js`) in the project root or in this CLI package root'),
+        killed: false
+    };
 }
-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');
+function isTimeoutError(err) {
+    return err.code === 'ETIMEDOUT';
 }
-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');
+/**
+ * Map a spawn outcome onto the record fields.
+ *
+ * A timeout is its OWN branch. The pre-fix code read `err.status ?? 1` and
+ * `err.stderr ?? ''`, so a timed-out task — whose status is null — was recorded
+ * as `exitCode 1, stderr ''`: a definite failure for work that, because the
+ * shell had been killed and the task process left running, might still succeed.
+ * `history.jsonl` consumers read `exitCode` + `stderr`, and both now say what
+ * actually happened.
+ */
+function toTaskRun(result, timeoutMs) {
+    const childStderr = truncateStderr(result.stderr ?? '');
+    const err = result.error;
+    if (err !== undefined) {
+        if (isTimeoutError(err)) {
+            return {
+                exitCode: NO_CHILD_STATUS_EXIT_CODE,
+                stderr: truncateStderr(`killed: task exceeded its ${String(timeoutMs)} ms exec timeout and its process was killed${childStderr}`),
+                killed: true
+            };
+        }
+        return {
+            exitCode: NO_CHILD_STATUS_EXIT_CODE,
+            stderr: truncateStderr(`${err.message}${childStderr}`),
+            killed: false
+        };
     }
-    else {
-        // Append — small file, OK to read+write
-        const existing = readFileSync(path, 'utf8');
-        writeFileSync(path, existing + line, 'utf8');
+    if (typeof result.status === 'number') {
+        return {
+            exitCode: result.status,
+            stderr: result.status === 0 ? '' : childStderr,
+            killed: false
+        };
     }
-}
-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()
+    // No status and no timeout error ⇒ the task died on a signal from somewhere
+    // else. That is still "killed", not "failed with exit 1".
+    return {
+        exitCode: NO_CHILD_STATUS_EXIT_CODE,
+        stderr: truncateStderr(`killed: task died on signal ${String(result.signal)}`),
+        killed: true
     };
-    return { version: SCHEDULE_VERSION, entries: [...file.entries, entry] };
 }
-export function runTask(projectRoot, task) {
+export function runTask(projectRoot, task, 
+// Test seam only: defaults to EXEC_TIMEOUT_MS so every production caller
+// (`runTargets`, the scheduler loop) is byte-identical. This is NOT a
+// per-entry `timeoutMs` (deferred follow-up) and is not read from config;
+// it exists so a test can inject a short timeout and prove a stalled
+// child is reaped rather than inherited.
+timeoutMs = EXEC_TIMEOUT_MS) {
     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(' ')}`, {
+    const entry = resolveTaskEntry(projectRoot);
+    const run = entry === null
+        ? unresolvedEntryRun()
+        : toTaskRun(spawnSync(process.execPath, [entry, task.command, ...task.args], {
             cwd: projectRoot,
             stdio: ['ignore', 'pipe', 'pipe'],
             encoding: 'utf8',
-            timeout: EXEC_TIMEOUT_MS,
+            timeout: timeoutMs,
+            // The contract of this slice is that the task is GONE when
+            // `runTask` returns; a kill signal the task can ignore would
+            // reintroduce the ownerless survivor.
+            killSignal: 'SIGKILL',
             windowsHide: true
-        });
-    }
-    catch (err) {
-        const e = err;
-        exitCode = typeof e.status === 'number' ? e.status : 1;
-        stderr = (e.stderr ?? getErrorMessage(err)).slice(0, STDERR_RECORD_TRUNCATE_BYTES);
-    }
+        }), timeoutMs);
     const record = {
         id,
         taskId: task.id,
         startedAt,
         finishedAt: Date.now(),
-        exitCode,
-        stderr
+        exitCode: run.exitCode,
+        stderr: run.stderr,
+        ...(run.killed ? { killed: true } : {})
     };
     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')
+    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')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => handleCronInit(io, options));
+    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')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => handleCronList(io, options));
+    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, STDERR_NEXT_ACTIONS_TRUNCATE_CHARS)}`), [`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;
-        }
-    });
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => handleCronRun(io, options));
 }

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

@@ -35,6 +35,7 @@ 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';
+import { persistLastRunAt } from './cron-scheduler-persist.js';
 const SCHEDULER_TICK_MS = 60_000; // 1 minute
 const PID_FILENAME = 'scheduler.pid';
 function schedulerPidPath(projectRoot) {
@@ -78,7 +79,8 @@ 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')
+    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 {
@@ -124,7 +126,8 @@ export function registerCronSchedulerCommand(program, io) {
             process.exitCode = 1;
         }
     });
-    addJsonOption(cmd.command('stop')
+    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 {
@@ -148,7 +151,9 @@ export function registerCronSchedulerCommand(program, io) {
             try {
                 unlinkSync(pidFile);
             }
-            catch { /* best-effort */ }
+            catch {
+                /* best-effort */
+            }
             printResult(io, ok('cron-scheduler.stop', { projectRoot, stopped: signalSent, pid, pidFile }, [], [
                 signalSent
                     ? `Sent SIGTERM to pid ${pid}; pid file removed.`
@@ -156,13 +161,12 @@ export function registerCronSchedulerCommand(program, io) {
             ]), 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);
+            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')
+    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 {
@@ -177,24 +181,34 @@ export function registerCronSchedulerCommand(program, io) {
                 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
+            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);
+                    : '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);
+            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')
+    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);
@@ -202,9 +216,7 @@ export function registerCronSchedulerCommand(program, io) {
                 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);
+            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;
         }
     });
@@ -230,9 +242,15 @@ export async function runSchedulerLoop(args) {
     const tick = () => {
         try {
             const due = listDueTasks(args.projectRoot);
-            for (const task of due) {
-                runTask(args.projectRoot, task);
-            }
+            const records = due.map((task) => runTask(args.projectRoot, task));
+            // backlog §2.24: this write-back is what makes a fired task stop being
+            // 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
+            // cron run` too; the rule and its per-platform costs are in
+            // `cron-scheduler-persist.ts`.
+            persistLastRunAt(args.projectRoot, records);
         }
         catch (err) {
             process.stderr.write(`[cron-scheduler] tick error: ${getErrorMessage(err)}\n`);
@@ -275,7 +293,9 @@ if (process.env.PEAKS_CRON_SCHEDULER_DAEMON === '1') {
     // 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();
+        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`);