peaks-loop 4.0.54 → 4.1.1

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

@@ -0,0 +1,43 @@
+/**
+ * The three `peaks cron` action handlers (init / list / run) — moved VERBATIM
+ * out of `cron-commands.ts` (job strict-remediation-abc, slice
+ * c1-eslint-family-sweep, leaf c3w1-cron-commands) so the registration file
+ * clears the `max-lines-per-function` findings.
+ *
+ * NOTHING was restructured: same predicate order inside the due/nextDueAt
+ * annotation (`e.enabled && (e.lastRunAt === null || now - e.lastRunAt >=
+ * e.intervalMs)`, with `>=` exactly as it was), same `process.exitCode = 1`
+ * points, same emitted message text, same sort. The run action's 66-line body
+ * was further split into `runCronTasks` / `runTargets` / `printRunOutcome`
+ * purely to cross the function-length line; ordering is unchanged.
+ *
+ * One dead local was not copied: `const now = Date.now();` inside the run
+ * action was never read (it carried a `no-unused-vars` baseline ERROR on the
+ * original file). Removing an unread, effect-free assignment changes no branch,
+ * throw, exit code, or emitted byte — and a new sibling must be clean outright.
+ *
+ * ONE thing has since been restructured, and it is not the verbatim move above:
+ * rid `2026-10-01-cron-last-run-at-01` repair cycle 1 replaced `runCronTasks`'s
+ * own fold-and-write (a `runTargets` that built the next file from the snapshot
+ * read before the runs, stamping every record including killed ones) with the
+ * scheduler's `persistLastRunAt`, so one rule and one write-time re-read cover
+ * all three `lastRunAt` writers. The `ran` / `records` envelope, the exit-code
+ * branch and every emitted message are unchanged; what changed on disk is that a
+ * killed run no longer advances `lastRunAt` here, and that entries another writer
+ * added mid-run are no longer reverted. The rule is in
+ * `cron-scheduler-persist.ts`.
+ */
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function handleCronInit(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function handleCronList(io: ProgramIO, options: {
+    project?: string;
+    json?: boolean;
+}): void;
+export declare function handleCronRun(io: ProgramIO, options: {
+    id?: string;
+    project?: string;
+    json?: boolean;
+}): void;

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

@@ -0,0 +1,128 @@
+/**
+ * The three `peaks cron` action handlers (init / list / run) — moved VERBATIM
+ * out of `cron-commands.ts` (job strict-remediation-abc, slice
+ * c1-eslint-family-sweep, leaf c3w1-cron-commands) so the registration file
+ * clears the `max-lines-per-function` findings.
+ *
+ * NOTHING was restructured: same predicate order inside the due/nextDueAt
+ * annotation (`e.enabled && (e.lastRunAt === null || now - e.lastRunAt >=
+ * e.intervalMs)`, with `>=` exactly as it was), same `process.exitCode = 1`
+ * points, same emitted message text, same sort. The run action's 66-line body
+ * was further split into `runCronTasks` / `runTargets` / `printRunOutcome`
+ * purely to cross the function-length line; ordering is unchanged.
+ *
+ * One dead local was not copied: `const now = Date.now();` inside the run
+ * action was never read (it carried a `no-unused-vars` baseline ERROR on the
+ * original file). Removing an unread, effect-free assignment changes no branch,
+ * throw, exit code, or emitted byte — and a new sibling must be clean outright.
+ *
+ * ONE thing has since been restructured, and it is not the verbatim move above:
+ * rid `2026-10-01-cron-last-run-at-01` repair cycle 1 replaced `runCronTasks`'s
+ * own fold-and-write (a `runTargets` that built the next file from the snapshot
+ * read before the runs, stamping every record including killed ones) with the
+ * scheduler's `persistLastRunAt`, so one rule and one write-time re-read cover
+ * all three `lastRunAt` writers. The `ran` / `records` envelope, the exit-code
+ * branch and every emitted message are unchanged; what changed on disk is that a
+ * killed run no longer advances `lastRunAt` here, and that entries another writer
+ * added mid-run are no longer reverted. The rule is in
+ * `cron-scheduler-persist.ts`.
+ */
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { ensureLeaseGcEntry, listDueTasks, readSchedule, schedulePath, writeSchedule } from './cron-commands-schedule.js';
+import { runTask } from './cron-commands.js';
+import { persistLastRunAt } from './cron-scheduler-persist.js';
+const STDERR_NEXT_ACTIONS_TRUNCATE_CHARS = 200;
+export function handleCronInit(io, 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;
+    }
+}
+export function handleCronList(io, 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;
+    }
+}
+export function handleCronRun(io, options) {
+    try {
+        runCronTasks(io, options);
+    }
+    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;
+    }
+}
+function runCronTasks(io, options) {
+    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 = runTargets(projectRoot, targets);
+    // ONE rule, ONE writer (rid `2026-10-01-cron-last-run-at-01`, repair cycle 1).
+    // This call is the third site of the `lastRunAt` fold, whose rule and platform
+    // costs live in `cron-scheduler-persist.ts`. Two things it replaces: a fold that
+    // stamped EVERY record, killed ones included (so the same killed fire went quiet
+    // here and stayed due under the daemon), and a write built from the `file`
+    // snapshot read above — taken up to `EXEC_TIMEOUT_MS` (300,000 ms) of synchronous
+    // runs before the write, so it reverted any stamp the daemon landed in between,
+    // back to `null`. `persistLastRunAt` re-reads at write time instead.
+    persistLastRunAt(projectRoot, records);
+    printRunOutcome(io, options, projectRoot, records);
+}
+function runTargets(projectRoot, targets) {
+    const records = [];
+    for (const task of targets)
+        records.push(runTask(projectRoot, task));
+    return records;
+}
+function printRunOutcome(io, options, projectRoot, records) {
+    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;
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The schedule model half of `peaks cron` (Part 14) — moved VERBATIM out of
+ * `cron-commands.ts` (job strict-remediation-abc, slice c1-eslint-family-sweep,
+ * leaf c3w1-cron-commands) so that file clears the 300-line cap and the
+ * `complexity` finding on `readSchedule` falls.
+ *
+ * NOTHING was restructured: same branch order, same predicates, same throw
+ * points, same message text, same on-disk bytes. `readSchedule` was split into
+ * `assertScheduleRoot` + `toScheduleEntry` + `isStringArray` only to shed the
+ * complexity finding; every check still runs in the original order with the
+ * original short-circuits.
+ *
+ * `runTask` (and its exec-timeout + record-truncation constants) deliberately
+ * stays in `cron-commands.ts`: that file carries the baseline `no-magic-numbers`
+ * warning on the timeout constant, and a new sibling must be clean outright.
+ */
+export declare const SCHEDULE_VERSION: 1;
+/**
+ * PRD-002b slice 2 — extract cron-orchestration magic numbers (24h
+ * default interval, 5-minute exec timeout, stderr-message truncation
+ * lengths in the renderer). The exec-timeout constant itself stayed in
+ * `cron-commands.ts` with `runTask`.
+ */
+export declare const MS_PER_SECOND = 1000;
+export declare const MINUTES_PER_HOUR = 60;
+export declare const SECONDS_PER_MINUTE = 60;
+export type ScheduleEntry = {
+    readonly id: string;
+    readonly name: string;
+    readonly command: string;
+    readonly args: ReadonlyArray<string>;
+    readonly intervalMs: number;
+    readonly lastRunAt: number | null;
+    readonly enabled: boolean;
+    readonly createdAt: number;
+};
+export type ScheduleFile = {
+    readonly version: typeof SCHEDULE_VERSION;
+    readonly entries: ReadonlyArray<ScheduleEntry>;
+};
+export type RunRecord = {
+    readonly id: string;
+    readonly taskId: string;
+    readonly startedAt: number;
+    readonly finishedAt: number;
+    readonly exitCode: number;
+    readonly stderr: string;
+    /**
+     * Present (and `true`) ONLY when the task was killed for exceeding its exec
+     * timeout — i.e. when there is no child exit status behind `exitCode` and the
+     * work may have been mid-flight. Added by rid 2026-10-01-cron-task-tree-kill-01
+     * so a killed run cannot be read as a clean `exitCode 1` failure.
+     *
+     * OPTIONAL on purpose: `appendHistory` is the only writer of
+     * `history.jsonl` and nothing in this repo reads it back, so the smallest
+     * representation that consumers can carry is "the key is absent unless the
+     * task was killed" — every pre-existing row shape is unchanged.
+     */
+    readonly killed?: true;
+};
+export declare function schedulePath(projectRoot: string): string;
+export declare function readSchedule(projectRoot: string): ScheduleFile;
+/**
+ * The one "can this raw JSON entry be represented?" predicate. Exported because
+ * a writer that must NOT lose an entry needs to know which ones the reader
+ * dropped (rid `2026-10-01-cron-last-run-at-01`, repair cycle 1, F5 — see
+ * `persistLastRunAt` in `cron-scheduler-persist.ts`).
+ */
+export declare function toScheduleEntry(e: unknown): ScheduleEntry | null;
+/**
+ * The write half's input shape: a version plus the entries to store.
+ *
+ * `entries` is `ReadonlyArray<unknown>`, not `ReadonlyArray<ScheduleEntry>`, for one
+ * caller: `persistLastRunAt` re-writes the raw JSON of entries `toScheduleEntry`
+ * refused, so that a daemon write cannot delete an operator's hand-edited entry
+ * (rid `2026-10-01-cron-last-run-at-01` repair cycle 1, F5). Every other caller
+ * passes a `ScheduleFile`, which satisfies this shape.
+ */
+export type ScheduleWrite = {
+    readonly version: typeof SCHEDULE_VERSION;
+    readonly entries: ReadonlyArray<unknown>;
+};
+export declare function writeSchedule(projectRoot: string, file: ScheduleWrite): void;
+export declare function appendHistory(projectRoot: string, record: RunRecord): void;
+export declare function ensureLeaseGcEntry(file: ScheduleFile): ScheduleFile;
+export declare function listDueTasks(projectRoot: string, now?: number): ReadonlyArray<ScheduleEntry>;

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

@@ -0,0 +1,151 @@
+/**
+ * The schedule model half of `peaks cron` (Part 14) — moved VERBATIM out of
+ * `cron-commands.ts` (job strict-remediation-abc, slice c1-eslint-family-sweep,
+ * leaf c3w1-cron-commands) so that file clears the 300-line cap and the
+ * `complexity` finding on `readSchedule` falls.
+ *
+ * NOTHING was restructured: same branch order, same predicates, same throw
+ * points, same message text, same on-disk bytes. `readSchedule` was split into
+ * `assertScheduleRoot` + `toScheduleEntry` + `isStringArray` only to shed the
+ * complexity finding; every check still runs in the original order with the
+ * original short-circuits.
+ *
+ * `runTask` (and its exec-timeout + record-truncation constants) deliberately
+ * stays in `cron-commands.ts`: that file carries the baseline `no-magic-numbers`
+ * warning on the timeout constant, and a new sibling must be clean outright.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const SCHEDULE_VERSION = 1;
+const SCHEDULE_FILENAME = 'schedule.json';
+const HISTORY_FILENAME = 'history.jsonl';
+/**
+ * PRD-002b slice 2 — extract cron-orchestration magic numbers (24h
+ * default interval, 5-minute exec timeout, stderr-message truncation
+ * lengths in the renderer). The exec-timeout constant itself stayed in
+ * `cron-commands.ts` with `runTask`.
+ */
+export const MS_PER_SECOND = 1_000;
+export const MINUTES_PER_HOUR = 60;
+export 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;
+function cronDir(projectRoot) {
+    return join(projectRoot, '.peaks', 'cron');
+}
+export function schedulePath(projectRoot) {
+    return join(cronDir(projectRoot), SCHEDULE_FILENAME);
+}
+function historyPath(projectRoot) {
+    return join(cronDir(projectRoot), HISTORY_FILENAME);
+}
+export function readSchedule(projectRoot) {
+    const path = schedulePath(projectRoot);
+    if (!existsSync(path))
+        return { version: SCHEDULE_VERSION, entries: [] };
+    const raw = readFileSync(path, 'utf8');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`schedule.json malformed: ${err.message}`);
+    }
+    const obj = assertScheduleRoot(parsed);
+    if (!Array.isArray(obj.entries)) {
+        throw new Error('schedule.json entries must be an array');
+    }
+    const entries = [];
+    for (const e of obj.entries) {
+        const entry = toScheduleEntry(e);
+        if (entry !== null)
+            entries.push(entry);
+    }
+    return { version: SCHEDULE_VERSION, entries };
+}
+function assertScheduleRoot(parsed) {
+    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})`);
+    }
+    return obj;
+}
+/**
+ * The one "can this raw JSON entry be represented?" predicate. Exported because
+ * a writer that must NOT lose an entry needs to know which ones the reader
+ * dropped (rid `2026-10-01-cron-last-run-at-01`, repair cycle 1, F5 — see
+ * `persistLastRunAt` in `cron-scheduler-persist.ts`).
+ */
+export function toScheduleEntry(e) {
+    if (typeof e !== 'object' || e === null)
+        return null;
+    const ent = e;
+    if (typeof ent.id !== 'string' || typeof ent.name !== 'string' || typeof ent.command !== 'string')
+        return null;
+    if (!isStringArray(ent.args) ||
+        typeof ent.intervalMs !== 'number' ||
+        typeof ent.createdAt !== 'number')
+        return null;
+    return {
+        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
+    };
+}
+function isStringArray(a) {
+    return Array.isArray(a) && a.every((s) => typeof s === 'string');
+}
+export function writeSchedule(projectRoot, file) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(schedulePath(projectRoot), `${JSON.stringify(file, null, 2)}\n`, 'utf8');
+}
+export function appendHistory(projectRoot, record) {
+    const dir = cronDir(projectRoot);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = historyPath(projectRoot);
+    const line = `${JSON.stringify(record)}\n`;
+    if (!existsSync(path)) {
+        writeFileSync(path, line, 'utf8');
+    }
+    else {
+        // Append — small file, OK to read+write
+        const existing = readFileSync(path, 'utf8');
+        writeFileSync(path, existing + line, 'utf8');
+    }
+}
+export function ensureLeaseGcEntry(file) {
+    if (file.entries.some((e) => e.id === 'lease-gc-daily'))
+        return file;
+    const entry = {
+        id: 'lease-gc-daily',
+        name: 'Daily lease listing — refresh the alive-lease set; operators run peaks worktree gc --lease-id <id> manually on stale entries',
+        command: 'worktree',
+        args: ['list'],
+        intervalMs: DEFAULT_INTERVAL_MS,
+        lastRunAt: null,
+        enabled: true,
+        createdAt: Date.now()
+    };
+    return { version: SCHEDULE_VERSION, entries: [...file.entries, entry] };
+}
+export function 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;
+    });
+}

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

@@ -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,35 +26,35 @@
  *   .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 type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-declare const SCHEDULE_VERSION: 1;
-export type ScheduleEntry = {
-    readonly id: string;
-    readonly name: string;
-    readonly command: string;
-    readonly args: ReadonlyArray<string>;
-    readonly intervalMs: number;
-    readonly lastRunAt: number | null;
-    readonly enabled: boolean;
-    readonly createdAt: number;
-};
-export type ScheduleFile = {
-    readonly version: typeof SCHEDULE_VERSION;
-    readonly entries: ReadonlyArray<ScheduleEntry>;
-};
-export type RunRecord = {
-    readonly id: string;
-    readonly taskId: string;
-    readonly startedAt: number;
-    readonly finishedAt: number;
-    readonly exitCode: number;
-    readonly stderr: string;
-};
-export declare function readSchedule(projectRoot: string): ScheduleFile;
-export declare function appendHistory(projectRoot: string, record: RunRecord): void;
-export declare function runTask(projectRoot: string, task: ScheduleEntry): RunRecord;
-export declare function listDueTasks(projectRoot: string, now?: number): ReadonlyArray<ScheduleEntry>;
+import { type RunRecord, type ScheduleEntry } from './cron-commands-schedule.js';
+export { readSchedule, appendHistory, listDueTasks } from './cron-commands-schedule.js';
+export type { ScheduleEntry, ScheduleFile, RunRecord } from './cron-commands-schedule.js';
+/**
+ * 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.
+ */
+export declare const EXEC_TIMEOUT_MS: number;
+export declare function runTask(projectRoot: string, task: ScheduleEntry, timeoutMs?: number): RunRecord;
 export declare function registerCronCommand(program: Command, io: ProgramIO): void;
-export {};