peaks-loop 4.0.54 → 4.1.0

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

@@ -0,0 +1,110 @@
+/**
+ * The ONE writer of `lastRunAt` in this repo — rid `2026-10-01-cron-last-run-at-01`
+ * (backlog §2.24), repair cycle 1 (review F1/F4/F5). Lives in its own file because
+ * `cron-commands.ts` sits at 287 of its 300 raw-line cap and
+ * `cron-scheduler-commands.ts` is already over its own; the rule below is small
+ * enough to be read, tested and quoted from here.
+ *
+ * WHO CALLS THIS (3 call sites, one rule): the daemon tick
+ * (`cron-scheduler-commands.ts:369`), `cron-scheduler run-once` (:304), and
+ * `peaks cron run` (`cron-commands-actions.ts:175`). The third site is the repair:
+ * at `9badd1ac` `peaks cron run` folded its own snapshot and stamped EVERY record,
+ * killed ones included (`cron-commands-actions.ts:174` of that commit, no `killed`
+ * test), while this file skipped them. The same killed fire therefore stayed due
+ * under the daemon and went silent for a full `intervalMs` under `cron run` — the
+ * documented runbook / external-crontab path. There is now one fold, so there is one
+ * outcome per fire, whichever command ran it.
+ *
+ * WHY IT EXISTS (measured, not inferred). Before the slice the daemon tick (the
+ * `for (const task of due) { runTask(…); }` body at `9badd1ac`) discarded the
+ * `RunRecord`, and `listDueTasks` keeps an entry due whenever `lastRunAt` is
+ * null (`cron-commands-schedule.ts:212`, `if (e.lastRunAt === null) return true;`).
+ * Measured by `tests/unit/cli/commands/cron-last-run-at.test.ts`: **6 `runTask`
+ * invocations across 6 ticks** for one entry with `intervalMs` 86,400,000 at the
+ * 60,000 ms daemon period — a 1440× rate error against the declared interval, and the
+ * rate half of
+ * `.peaks/docs/diagnosis-2026-10-01-worktree-list-population.md` §9. The same
+ * test observes **1** once the write-back below runs.
+ *
+ * THE RULE (persist AFTER the run, from the record's `finishedAt`):
+ *   1. a run that reached a conclusion — exit code 0 or non-zero, not killed —
+ *      advances `lastRunAt` to `record.finishedAt`, so the entry goes quiet for
+ *      exactly its own `intervalMs` and not one ms longer;
+ *   2. a run carrying `killed: true` does NOT advance it, in EITHER entry point.
+ *      Work cut off mid-flight is not a day's work, so the task stays due and is
+ *      retried. What that costs is NOT uniform across platforms, and F3 of the
+ *      review is the reason this paragraph is platform-shaped instead of global:
+ *      - win32: the only fire shape that reaches `killed: true` here is the exec
+ *        timeout (`cron-commands.ts:178-185`, spawnSync's `error.code ===
+ *        'ETIMEDOUT'` branch), and that fire BLOCKS its caller for the whole
+ *        injected timeout — measured at 3,019 ms and 3,020 ms of block for an injected
+ *        3,000 ms timeout (`tests/unit/cli/commands/cron-exec-timeout.test.ts`, whose
+ *        positive control brings the same wiring back in 67-71 ms when the child
+ *        concludes), and the production value is `EXEC_TIMEOUT_MS = 300_000`
+ *        (`cron-commands.ts:74`). The
+ *        tick is a synchronous callback on one `setInterval`
+ *        (`cron-scheduler-commands.ts:378`), so fires serialize and a permanently
+ *        stuck entry costs at most 3,600,000 / 300,000 = **12 fires per hour**, not
+ *        one per 60,000 ms tick. A child killed from OUTSIDE does not carry `killed`
+ *        on this platform: the review measured a `taskkill /F`-terminated child
+ *        returning `status 1` in 419 ms, and the same shape driven through `runTask`
+ *        against `dist/` at repair time came back `exitCode 1` with NO `killed` key in
+ *        383 ms and 410 ms — which takes the CONCLUDED branch
+ *        (`cron-commands.ts:193-199`) and is therefore STAMPED. Both writers now
+ *        agree about that class (it is stamped by both), and neither pretends rule 2
+ *        can see it on win32.
+ *      - POSIX: an external signal death has no status and no timeout error, so it
+ *        does hit `cron-commands.ts:200-206` and carry `killed: true`, and `runTask`
+ *        returns as soon as the child dies. That class re-fires once per 60,000 ms
+ *        tick — the deliberate price of not silencing unfinished work, and the shape
+ *        this host cannot produce.
+ *      Timestamping at `startedAt` was rejected (goal §alternatives): it would mark a
+ *      killed run as done and silence it.
+ *   3. every entry the file holds survives the write. Parsed entries are re-written
+ *      from a schedule that is RE-READ at write time, so a task an operator added
+ *      while the daemon was busy is preserved field-for-field
+ *      (`cron-last-run-at.test.ts`, "when an operator adds a task while the daemon is
+ *      running one…"); and entries `toScheduleEntry`
+ *      (`cron-commands-schedule.ts:129-150`) REJECTS — a hand-edited entry missing
+ *      `name`, say — are carried through as the raw JSON they were written as,
+ *      appended after the parsed ones. F5 of the review: before this they were
+ *      silently DELETED by the daemon's first write, which is data loss on a
+ *      long-lived process nobody is watching. An unparseable entry with the same `id`
+ *      as a parsed one is the one thing still dropped, because two entries under one
+ *      id would make the fold ambiguous.
+ *
+ * WINDOWS, NAMED (F4 + the lock that does not exist):
+ * - Inside this function the read→write sequence has no `await` and no yield point,
+ *   so within one process the window is nil; it is cross-process only.
+ * - `peaks cron run` used to be the wide window: at `9badd1ac` it read the whole
+ *   schedule (`cron-commands-actions.ts:143`), ran each target synchronously for up
+ *   to `EXEC_TIMEOUT_MS` (300,000 ms) per task (:172), then rewrote the file from
+ *   that PRE-RUN snapshot (:156) — which reverted any stamp the daemon had
+ *   landed in between, back to `null`, i.e. permanently due, §2.24 re-opened until
+ *   the next concluded run. It calls this function now, so its write is a write-time
+ *   re-read like this one's; `cron-last-run-at.test.ts` ("…another writer stamps…")
+ *   measures the revert case.
+ * - What is still open, stated rather than implied: there is NO lock on
+ *   `schedule.json`, and `writeSchedule` is a plain `writeFileSync`
+ *   (`cron-commands-schedule.ts:170-174`). Last-writer-wins on the VALUE across two
+ *   processes that both land inside this function's own re-read→write tail remains,
+ *   and a host failure mid-write still truncates the file. That needs the
+ *   locking/atomic-write framework this slice deliberately does not take on.
+ * - One write per BATCH, not per record (F6, not fixed here): `runTask` throws for fs
+ *   failure inside `appendHistory` (`cron-commands-schedule.ts:176-188` does a
+ *   read+write of the whole history per record), so a throw at task k loses the
+ *   stamps for tasks 1..k-1 and the tick's catch turns it into one stderr line; those
+ *   already-concluded tasks are due again next tick. Reachability is documented at
+ *   `skills/peaks-code/references/cron-scheduler-deployment.md:98-101` (a read-only
+ *   `.peaks/cron`).
+ */
+import { type RunRecord } from './cron-commands-schedule.js';
+/**
+ * Fold a batch of finished runs into `schedule.json`.
+ *
+ * `records` is what `runTask` returned for the tasks this batch ran; a record whose
+ * task id is no longer in the schedule (an operator removed the entry mid-flight) is
+ * dropped rather than resurrected. When nothing is left to change — every run
+ * killed, or the whole batch stale — the file is not rewritten.
+ */
+export declare function persistLastRunAt(projectRoot: string, records: ReadonlyArray<RunRecord>): void;

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

@@ -0,0 +1,171 @@
+/**
+ * The ONE writer of `lastRunAt` in this repo — rid `2026-10-01-cron-last-run-at-01`
+ * (backlog §2.24), repair cycle 1 (review F1/F4/F5). Lives in its own file because
+ * `cron-commands.ts` sits at 287 of its 300 raw-line cap and
+ * `cron-scheduler-commands.ts` is already over its own; the rule below is small
+ * enough to be read, tested and quoted from here.
+ *
+ * WHO CALLS THIS (3 call sites, one rule): the daemon tick
+ * (`cron-scheduler-commands.ts:369`), `cron-scheduler run-once` (:304), and
+ * `peaks cron run` (`cron-commands-actions.ts:175`). The third site is the repair:
+ * at `9badd1ac` `peaks cron run` folded its own snapshot and stamped EVERY record,
+ * killed ones included (`cron-commands-actions.ts:174` of that commit, no `killed`
+ * test), while this file skipped them. The same killed fire therefore stayed due
+ * under the daemon and went silent for a full `intervalMs` under `cron run` — the
+ * documented runbook / external-crontab path. There is now one fold, so there is one
+ * outcome per fire, whichever command ran it.
+ *
+ * WHY IT EXISTS (measured, not inferred). Before the slice the daemon tick (the
+ * `for (const task of due) { runTask(…); }` body at `9badd1ac`) discarded the
+ * `RunRecord`, and `listDueTasks` keeps an entry due whenever `lastRunAt` is
+ * null (`cron-commands-schedule.ts:212`, `if (e.lastRunAt === null) return true;`).
+ * Measured by `tests/unit/cli/commands/cron-last-run-at.test.ts`: **6 `runTask`
+ * invocations across 6 ticks** for one entry with `intervalMs` 86,400,000 at the
+ * 60,000 ms daemon period — a 1440× rate error against the declared interval, and the
+ * rate half of
+ * `.peaks/docs/diagnosis-2026-10-01-worktree-list-population.md` §9. The same
+ * test observes **1** once the write-back below runs.
+ *
+ * THE RULE (persist AFTER the run, from the record's `finishedAt`):
+ *   1. a run that reached a conclusion — exit code 0 or non-zero, not killed —
+ *      advances `lastRunAt` to `record.finishedAt`, so the entry goes quiet for
+ *      exactly its own `intervalMs` and not one ms longer;
+ *   2. a run carrying `killed: true` does NOT advance it, in EITHER entry point.
+ *      Work cut off mid-flight is not a day's work, so the task stays due and is
+ *      retried. What that costs is NOT uniform across platforms, and F3 of the
+ *      review is the reason this paragraph is platform-shaped instead of global:
+ *      - win32: the only fire shape that reaches `killed: true` here is the exec
+ *        timeout (`cron-commands.ts:178-185`, spawnSync's `error.code ===
+ *        'ETIMEDOUT'` branch), and that fire BLOCKS its caller for the whole
+ *        injected timeout — measured at 3,019 ms and 3,020 ms of block for an injected
+ *        3,000 ms timeout (`tests/unit/cli/commands/cron-exec-timeout.test.ts`, whose
+ *        positive control brings the same wiring back in 67-71 ms when the child
+ *        concludes), and the production value is `EXEC_TIMEOUT_MS = 300_000`
+ *        (`cron-commands.ts:74`). The
+ *        tick is a synchronous callback on one `setInterval`
+ *        (`cron-scheduler-commands.ts:378`), so fires serialize and a permanently
+ *        stuck entry costs at most 3,600,000 / 300,000 = **12 fires per hour**, not
+ *        one per 60,000 ms tick. A child killed from OUTSIDE does not carry `killed`
+ *        on this platform: the review measured a `taskkill /F`-terminated child
+ *        returning `status 1` in 419 ms, and the same shape driven through `runTask`
+ *        against `dist/` at repair time came back `exitCode 1` with NO `killed` key in
+ *        383 ms and 410 ms — which takes the CONCLUDED branch
+ *        (`cron-commands.ts:193-199`) and is therefore STAMPED. Both writers now
+ *        agree about that class (it is stamped by both), and neither pretends rule 2
+ *        can see it on win32.
+ *      - POSIX: an external signal death has no status and no timeout error, so it
+ *        does hit `cron-commands.ts:200-206` and carry `killed: true`, and `runTask`
+ *        returns as soon as the child dies. That class re-fires once per 60,000 ms
+ *        tick — the deliberate price of not silencing unfinished work, and the shape
+ *        this host cannot produce.
+ *      Timestamping at `startedAt` was rejected (goal §alternatives): it would mark a
+ *      killed run as done and silence it.
+ *   3. every entry the file holds survives the write. Parsed entries are re-written
+ *      from a schedule that is RE-READ at write time, so a task an operator added
+ *      while the daemon was busy is preserved field-for-field
+ *      (`cron-last-run-at.test.ts`, "when an operator adds a task while the daemon is
+ *      running one…"); and entries `toScheduleEntry`
+ *      (`cron-commands-schedule.ts:129-150`) REJECTS — a hand-edited entry missing
+ *      `name`, say — are carried through as the raw JSON they were written as,
+ *      appended after the parsed ones. F5 of the review: before this they were
+ *      silently DELETED by the daemon's first write, which is data loss on a
+ *      long-lived process nobody is watching. An unparseable entry with the same `id`
+ *      as a parsed one is the one thing still dropped, because two entries under one
+ *      id would make the fold ambiguous.
+ *
+ * WINDOWS, NAMED (F4 + the lock that does not exist):
+ * - Inside this function the read→write sequence has no `await` and no yield point,
+ *   so within one process the window is nil; it is cross-process only.
+ * - `peaks cron run` used to be the wide window: at `9badd1ac` it read the whole
+ *   schedule (`cron-commands-actions.ts:143`), ran each target synchronously for up
+ *   to `EXEC_TIMEOUT_MS` (300,000 ms) per task (:172), then rewrote the file from
+ *   that PRE-RUN snapshot (:156) — which reverted any stamp the daemon had
+ *   landed in between, back to `null`, i.e. permanently due, §2.24 re-opened until
+ *   the next concluded run. It calls this function now, so its write is a write-time
+ *   re-read like this one's; `cron-last-run-at.test.ts` ("…another writer stamps…")
+ *   measures the revert case.
+ * - What is still open, stated rather than implied: there is NO lock on
+ *   `schedule.json`, and `writeSchedule` is a plain `writeFileSync`
+ *   (`cron-commands-schedule.ts:170-174`). Last-writer-wins on the VALUE across two
+ *   processes that both land inside this function's own re-read→write tail remains,
+ *   and a host failure mid-write still truncates the file. That needs the
+ *   locking/atomic-write framework this slice deliberately does not take on.
+ * - One write per BATCH, not per record (F6, not fixed here): `runTask` throws for fs
+ *   failure inside `appendHistory` (`cron-commands-schedule.ts:176-188` does a
+ *   read+write of the whole history per record), so a throw at task k loses the
+ *   stamps for tasks 1..k-1 and the tick's catch turns it into one stderr line; those
+ *   already-concluded tasks are due again next tick. Reachability is documented at
+ *   `skills/peaks-code/references/cron-scheduler-deployment.md:98-101` (a read-only
+ *   `.peaks/cron`).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { readSchedule, schedulePath, SCHEDULE_VERSION, toScheduleEntry, writeSchedule } from './cron-commands-schedule.js';
+/**
+ * Fold a batch of finished runs into `schedule.json`.
+ *
+ * `records` is what `runTask` returned for the tasks this batch ran; a record whose
+ * task id is no longer in the schedule (an operator removed the entry mid-flight) is
+ * dropped rather than resurrected. When nothing is left to change — every run
+ * killed, or the whole batch stale — the file is not rewritten.
+ */
+export function persistLastRunAt(projectRoot, records) {
+    const concludedAt = new Map();
+    for (const record of records) {
+        if (record.killed === true)
+            continue;
+        concludedAt.set(record.taskId, record.finishedAt);
+    }
+    if (concludedAt.size === 0)
+        return;
+    const current = readSchedule(projectRoot);
+    const entries = [];
+    let stamped = 0;
+    for (const entry of current.entries) {
+        const finishedAt = concludedAt.get(entry.id);
+        if (finishedAt === undefined) {
+            entries.push(entry);
+            continue;
+        }
+        entries.push({ ...entry, lastRunAt: finishedAt });
+        stamped += 1;
+    }
+    if (stamped === 0)
+        return;
+    writeSchedule(projectRoot, {
+        version: SCHEDULE_VERSION,
+        entries: [...entries, ...unrepresentedEntries(projectRoot, current.entries)]
+    });
+}
+/**
+ * The raw JSON of every entry on disk that `toScheduleEntry` refused, so this write
+ * preserves what it cannot represent (F5) instead of deleting it.
+ *
+ * Two reads of one file, deliberately: `readSchedule` above is the validating one
+ * (it owns the version check and the throw on malformed JSON), and this one is the
+ * byte-preserving one. They are not a snapshot of each other — a file clobbered
+ * between them throws here and the write does not happen, which is the safe answer
+ * for a schedule the reader can no longer parse.
+ */
+function unrepresentedEntries(projectRoot, parsed) {
+    const path = schedulePath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    // `Array.isArray` narrows `unknown` to `any[]`; this assertion is what makes the
+    // elements `unknown` again, so nothing below inherits an untyped value.
+    const listed = Array.isArray(raw.entries) ? raw.entries : [];
+    const ids = new Set(parsed.map((entry) => entry.id));
+    return listed.filter((entry) => typeof entry === 'object' &&
+        entry !== null &&
+        toScheduleEntry(entry) === null &&
+        !sharesIdWithAParsedEntry(entry, ids));
+}
+/**
+ * An unparseable entry that carries the `id` of a parseable one is the single case
+ * this write still drops: two entries under one id would make the fold above
+ * ambiguous about which one it just stamped.
+ */
+function sharesIdWithAParsedEntry(entry, ids) {
+    const id = entry.id;
+    return typeof id === 'string' && ids.has(id);
+}

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

@@ -21,7 +21,13 @@ function parseSince(raw) {
     if (!Number.isFinite(value) || value < 0)
         return { ok: false, error: `--since must be a non-negative integer (got ${raw})` };
     const unit = (match[2] ?? 'h').toLowerCase();
-    const multiplier = unit === 'd' ? MS_PER_DAY : unit === 'h' ? MS_PER_HOUR : unit === 'm' ? MS_PER_MINUTE : MS_PER_SECOND;
+    const multiplier = unit === 'd'
+        ? MS_PER_DAY
+        : unit === 'h'
+            ? MS_PER_HOUR
+            : unit === 'm'
+                ? MS_PER_MINUTE
+                : MS_PER_SECOND;
     return { ok: true, ms: Math.min(WINDOW_CAP_MS, value * multiplier) };
 }
 function readSlices(projectRoot, sessionId) {
@@ -34,7 +40,9 @@ function readSlices(projectRoot, sessionId) {
     if (!existsSync(path))
         return 0;
     try {
-        return readFileSync(path, 'utf8').split('\n').filter((line) => line.trim().length > 0).length;
+        return readFileSync(path, 'utf8')
+            .split('\n')
+            .filter((line) => line.trim().length > 0).length;
     }
     catch {
         return 0;
@@ -55,7 +63,13 @@ function boundaryLabel(raw) {
         return { key: 'valid', message: 'unparseable' };
     const value = Number(match[1]);
     const unit = (match[2] ?? 'h').toLowerCase();
-    const multiplier = unit === 'd' ? MS_PER_DAY : unit === 'h' ? MS_PER_HOUR : unit === 'm' ? MS_PER_MINUTE : MS_PER_SECOND;
+    const multiplier = unit === 'd'
+        ? MS_PER_DAY
+        : unit === 'h'
+            ? MS_PER_HOUR
+            : unit === 'm'
+                ? MS_PER_MINUTE
+                : MS_PER_SECOND;
     if (value * multiplier > WINDOW_CAP_MS) {
         return { key: 'cap', message: 'since>24h is capped to the 24h window' };
     }
@@ -79,14 +93,19 @@ export function registerDashboardLongRunCommand(dashboard, io) {
             process.exitCode = 1;
             return;
         }
-        const sid = options.sessionId ?? (await (async () => {
-            const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
-            return getSessionIdCanonical(projectRoot);
-        })());
+        const sid = options.sessionId ??
+            (await (async () => {
+                const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+                return getSessionIdCanonical(projectRoot);
+            })());
         if (!sid) {
-            io.stdout((options.json === true
-                ? JSON.stringify({ ok: false, code: 'NO_ACTIVE_SESSION', message: 'no --session-id and no canonical binding' })
-                : 'NO_ACTIVE_SESSION: no --session-id and no canonical binding\n'));
+            io.stdout(options.json === true
+                ? JSON.stringify({
+                    ok: false,
+                    code: 'NO_ACTIVE_SESSION',
+                    message: 'no --session-id and no canonical binding'
+                })
+                : 'NO_ACTIVE_SESSION: no --session-id and no canonical binding\n');
             process.exitCode = 1;
             return;
         }
@@ -96,7 +115,9 @@ export function registerDashboardLongRunCommand(dashboard, io) {
             const sliceCount = readSlices(projectRoot, sid);
             const checkpointAgeMs = readLastCheckpointAgeMs(snapshot);
             const checkpointFrequency = snapshot.checkpoints > 0 && snapshot.enteredAt
-                ? Math.max(1, Math.round((Date.now() - Date.parse(snapshot.enteredAt)) / snapshot.checkpoints / MS_PER_MINUTE))
+                ? Math.max(1, Math.round((Date.now() - Date.parse(snapshot.enteredAt)) /
+                    snapshot.checkpoints /
+                    MS_PER_MINUTE))
                 : null;
             const indicators = {
                 dispatchCount: sliceCount,
@@ -113,16 +134,26 @@ export function registerDashboardLongRunCommand(dashboard, io) {
                     sinceMs: parsed.ms,
                     sinceCapped: parsed.ms === WINDOW_CAP_MS && boundary.key === 'cap',
                     boundary: boundary.key,
-                    snapshot: { state: snapshot.state, enteredAt: snapshot.enteredAt, lastCheckpointAt: snapshot.lastCheckpointAt },
+                    snapshot: {
+                        state: snapshot.state,
+                        enteredAt: snapshot.enteredAt,
+                        lastCheckpointAt: snapshot.lastCheckpointAt
+                    },
                     indicators,
                     checkpointAgeMs
                 }
             };
-            io.stdout((options.json === true ? JSON.stringify(payload) : JSON.stringify(payload.data, null, 2)) + '\n');
+            io.stdout((options.json === true
+                ? JSON.stringify(payload)
+                : JSON.stringify(payload.data, null, 2)) + '\n');
         }
         catch (error) {
             io.stdout((options.json === true
-                ? JSON.stringify({ ok: false, code: 'LONG_RUN_READ_FAILED', message: getErrorMessage(error) })
+                ? JSON.stringify({
+                    ok: false,
+                    code: 'LONG_RUN_READ_FAILED',
+                    message: getErrorMessage(error)
+                })
                 : `LONG_RUN_READ_FAILED: ${getErrorMessage(error)}\n`) + '\n');
             process.exitCode = 1;
         }

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

@@ -28,9 +28,13 @@ export function registerDashboardSummaryCommand(dashboard, io) {
             sid = await getSessionIdCanonical(projectRoot);
         }
         if (!sid) {
-            io.stdout((options.json === true
-                ? JSON.stringify({ ok: false, code: 'NO_ACTIVE_SESSION', message: 'no --session-id and no canonical binding' })
-                : 'NO_ACTIVE_SESSION: no --session-id and no canonical binding\n'));
+            io.stdout(options.json === true
+                ? JSON.stringify({
+                    ok: false,
+                    code: 'NO_ACTIVE_SESSION',
+                    message: 'no --session-id and no canonical binding'
+                })
+                : 'NO_ACTIVE_SESSION: no --session-id and no canonical binding\n');
             process.exitCode = 1;
             return;
         }
@@ -46,11 +50,17 @@ export function registerDashboardSummaryCommand(dashboard, io) {
                     metrics
                 }
             };
-            io.stdout((options.json === true ? JSON.stringify(payload) : JSON.stringify(payload.data, null, 2)) + '\n');
+            io.stdout((options.json === true
+                ? JSON.stringify(payload)
+                : JSON.stringify(payload.data, null, 2)) + '\n');
         }
         catch (error) {
             io.stdout((options.json === true
-                ? JSON.stringify({ ok: false, code: 'SUMMARY_READ_FAILED', message: getErrorMessage(error) })
+                ? JSON.stringify({
+                    ok: false,
+                    code: 'SUMMARY_READ_FAILED',
+                    message: getErrorMessage(error)
+                })
                 : `SUMMARY_READ_FAILED: ${getErrorMessage(error)}\n`) + '\n');
             process.exitCode = 1;
         }

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

@@ -42,7 +42,7 @@ import { buildDispatchSystemPrompt } from '../../services/context/build-dispatch
 import { readSessionCapsule } from '../../services/dispatch/session-capsule.js';
 import { computeUiLibraryDispatchBlock } from '../../services/standards/ui-library-dispatch-block.js';
 import { readFreshContextBlock } from '../../services/fresh-context/fresh-context-block.js';
-import { createDispatchProvenanceToken, DISPATCH_PROVENANCE_ENV, writeDispatchProvenance, } from '../../services/worktree/dispatch-provenance.js';
+import { createDispatchProvenanceToken, DISPATCH_PROVENANCE_ENV, writeDispatchProvenance } from '../../services/worktree/dispatch-provenance.js';
 import { spawnWorktreeLease, spawnContainerLease } from '../../services/dispatch/isolation-lease.js';
 import { runGitLsFiles } from '../../services/dispatch/dispatch-sub-agent.js';
 export function registerDispatchCommand(parent, io) {
@@ -123,9 +123,11 @@ export function registerDispatchCommand(parent, io) {
                     project: projectRoot,
                     json: asJson,
                     ...(options.noThrottle === true ? { noThrottle: true } : {}),
-                    ...(typeof maxConcurrent === 'number' && Number.isInteger(maxConcurrent) && maxConcurrent > 0
+                    ...(typeof maxConcurrent === 'number' &&
+                        Number.isInteger(maxConcurrent) &&
+                        maxConcurrent > 0
                         ? { maxConcurrent }
-                        : {}),
+                        : {})
                 });
                 // The handler's `ok` is the launch outcome (a vendor CLI that is not
                 // installed is a failure, not a footnote) — the caller must not
@@ -177,7 +179,12 @@ export function registerDispatchCommand(parent, io) {
         // so `peaks sub-agent dispatch agent --help` continues to
         // exit 0 with the help text — that is intentional, not a bug.
         if (role === 'agent') {
-            printResult(io, fail('sub-agent.dispatch', 'ROLE_REMOVED', 'The agent role was removed in Slice 3', { role, reason: 'role-removed-in-slice-3', toolCall: null, dispatchRecordPath: null }, []), asJson);
+            printResult(io, fail('sub-agent.dispatch', 'ROLE_REMOVED', 'The agent role was removed in Slice 3', {
+                role,
+                reason: 'role-removed-in-slice-3',
+                toolCall: null,
+                dispatchRecordPath: null
+            }, []), asJson);
             process.exitCode = 1;
             return;
         }
@@ -234,10 +241,10 @@ export function registerDispatchCommand(parent, io) {
             // of the `unknown-sid` fallback. The unknown-sid branch is preserved
             // as the last-resort so callers without a bound session (e.g. an
             // ad-hoc dispatch in a fresh tree) still get a deterministic path.
-            const sid = options.sessionId
-                ?? process.env.PEAKS_SESSION_ID
-                ?? getCurrentSessionId(projectRoot)
-                ?? 'unknown-sid';
+            const sid = options.sessionId ??
+                process.env.PEAKS_SESSION_ID ??
+                getCurrentSessionId(projectRoot) ??
+                'unknown-sid';
             const rid = options.requestId ?? 'unknown-rid';
             const batchId = options.batchId ?? randomUUID();
             // Slice 2026-07-29-worktree-l2-extended Part 2.C: --isolation worktree
@@ -251,12 +258,16 @@ export function registerDispatchCommand(parent, io) {
             let worktreePath = null;
             let worktreeBranch = null;
             if (typeof options.isolation === 'string' && options.isolation.length > 0) {
-                if (options.isolation !== 'worktree' && options.isolation !== 'container' && options.isolation !== 'vm') {
+                if (options.isolation !== 'worktree' &&
+                    options.isolation !== 'container' &&
+                    options.isolation !== 'vm') {
                     printResult(io, fail('sub-agent.dispatch', 'INVALID_ISOLATION', `--isolation only accepts "worktree" | "container" | "vm" (got "${options.isolation}")`, {
                         role,
                         toolCall: null,
                         dispatchRecordPath: null
-                    }, ['Drop --isolation or pass --isolation worktree / --isolation container / --isolation vm.']), asJson);
+                    }, [
+                        'Drop --isolation or pass --isolation worktree / --isolation container / --isolation vm.'
+                    ]), asJson);
                     process.exitCode = 1;
                     return;
                 }
@@ -367,7 +378,8 @@ export function registerDispatchCommand(parent, io) {
             try {
                 projectPrefs = loadPreferences(projectRoot);
             }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            catch {
+                // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                 // Keep default preferences.
             }
             const ide = detectInstalledIde(projectRoot) ?? 'claude-code';
@@ -479,7 +491,9 @@ export function registerDispatchCommand(parent, io) {
                 ...(freshContextBlock !== undefined ? { freshContextBlock } : {}),
                 // §4: advisory session capsule pointer + precedence line.
                 ...(capsuleRef !== null
-                    ? { capsule: { batchId: capsuleRef.batchId, key: capsuleRef.key, bytes: capsuleRef.bytes } }
+                    ? {
+                        capsule: { batchId: capsuleRef.batchId, key: capsuleRef.key, bytes: capsuleRef.bytes }
+                    }
                     : {})
             });
             // Part 2.C: when --isolation worktree, prepend an isolation envelope
@@ -493,7 +507,15 @@ export function registerDispatchCommand(parent, io) {
                     `leaseId: ${leaseId}\n` +
                     `worktreePath: ${worktreePath}\n` +
                     `branch: ${worktreeBranch}\n` +
-                    `You MAY ` + '`git worktree add` ' + `and ` + '`git worktree remove` ' + `against this lease without a separate ` + '`peaks worktree auth grant` ' + `— the PreToolUse gate reads the lease file. Run ` + '`peaks worktree release --lease-id ${leaseId}` ' + `when done.\n`
+                    `You MAY ` +
+                    '`git worktree add` ' +
+                    `and ` +
+                    '`git worktree remove` ' +
+                    `against this lease without a separate ` +
+                    '`peaks worktree auth grant` ' +
+                    `— the PreToolUse gate reads the lease file. Run ` +
+                    '`peaks worktree release --lease-id ${leaseId}` ' +
+                    `when done.\n`
                 : '';
             // F5 follow-up: anti-fake-green gate. When `--must-ls-files <glob>`
             // is supplied, run `git ls-files <glob>` upfront, surface the
@@ -511,13 +533,14 @@ export function registerDispatchCommand(parent, io) {
                 const files = runGitLsFiles(projectRoot, glob);
                 const exists = files.length > 0;
                 mustLsFilesVerification = { path: glob, exists, files };
-                mustLsFilesBlock = `\n## must_ls_files enforcement (F5 anti-fake-green)\n` +
-                    `glob: ${glob}\n` +
-                    `verification: ${exists ? `EXISTS (${files.length} file${files.length === 1 ? '' : 's'} found)` : 'MISSING (no files matched the glob)'}\n` +
-                    (exists ? `first match: ${files[0] ?? ''}\n` : '') +
-                    `BEFORE any claim that work is "completed" or "PASS", you MUST run \`git ls-files ${glob}\` from the project root and ` +
-                    `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
-                    `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
+                mustLsFilesBlock =
+                    `\n## must_ls_files enforcement (F5 anti-fake-green)\n` +
+                        `glob: ${glob}\n` +
+                        `verification: ${exists ? `EXISTS (${files.length} file${files.length === 1 ? '' : 's'} found)` : 'MISSING (no files matched the glob)'}\n` +
+                        (exists ? `first match: ${files[0] ?? ''}\n` : '') +
+                        `BEFORE any claim that work is "completed" or "PASS", you MUST run \`git ls-files ${glob}\` from the project root and ` +
+                        `confirm the file exists. Anti-fake-green rule (sediment 2026-08-11-rid-001-redo-fake-green-recovery-closure §Lesson 1): ` +
+                        `if the file does not exist, your verdict MUST be \`status: "blocked"\` with reason "must_ls_files_failed". Do NOT silently skip this step.\n`;
             }
             const effectivePrompt = `${memoryAugmentedBody}${isolationBlock}${mustLsFilesBlock}`;
             // Slice F2 (rid-f2-ac1-wiring): deprecated reviewer slots are accepted
@@ -525,7 +548,12 @@ export function registerDispatchCommand(parent, io) {
             const warnings = [...decision.warnings, ...deprecatedReviewerWarnings(role)];
             let toolCall;
             try {
-                toolCall = adapter.subAgentDispatcher.buildToolCall({ role, prompt: effectivePrompt, requestId: rid, sessionId: sid });
+                toolCall = adapter.subAgentDispatcher.buildToolCall({
+                    role,
+                    prompt: effectivePrompt,
+                    requestId: rid,
+                    sessionId: sid
+                });
                 // Part 2.C: stamp the toolCall with `isolation` + a sub-agent
                 // env block so adapters that surface it (Claude Code's Task
                 // tool) propagate the lease id to the spawned process. The
@@ -536,7 +564,7 @@ export function registerDispatchCommand(parent, io) {
                     const provenanceToken = createDispatchProvenanceToken({
                         sessionId: sid,
                         requestId: rid,
-                        leaseId,
+                        leaseId
                     });
                     if (isolationMode === 'worktree') {
                         writeDispatchProvenance({
@@ -548,8 +576,8 @@ export function registerDispatchCommand(parent, io) {
                                 requestId: rid,
                                 leaseId,
                                 isolation: 'worktree',
-                                issuedAt: new Date().toISOString(),
-                            },
+                                issuedAt: new Date().toISOString()
+                            }
                         });
                     }
                     // Slice 2026-08-01-subagent-merge-and-e2e (Task 8): stamp the
@@ -562,7 +590,7 @@ export function registerDispatchCommand(parent, io) {
                     const profile = playwrightProfilePaths({
                         projectRoot,
                         sessionId: sid,
-                        dispatchId: rid,
+                        dispatchId: rid
                     });
                     toolCall = {
                         ...toolCall,
@@ -574,7 +602,9 @@ export function registerDispatchCommand(parent, io) {
                                 PEAKS_WORKTREE_LEASE_ID: leaseId,
                                 PEAKS_PLAYWRIGHT_USER_DATA_DIR: profile.userDataDir,
                                 PEAKS_PLAYWRIGHT_PROFILE_NAME: profile.profileName,
-                                ...(isolationMode === 'worktree' ? { [DISPATCH_PROVENANCE_ENV]: provenanceToken } : {}),
+                                ...(isolationMode === 'worktree'
+                                    ? { [DISPATCH_PROVENANCE_ENV]: provenanceToken }
+                                    : {})
                             }
                         }
                     };
@@ -588,7 +618,9 @@ export function registerDispatchCommand(parent, io) {
                 // roles like 'qa-business' would otherwise drop the event
                 // through schema rejection).
                 const KNOWN_ROLES = new Set(OBSERVABILITY_SUBAGENT_ROLES);
-                const knownRole = KNOWN_ROLES.has(role) ? role : null;
+                const knownRole = KNOWN_ROLES.has(role)
+                    ? role
+                    : null;
                 emitObservabilityEvent({
                     schemaVersion: 1,
                     ts: new Date().toISOString(),
@@ -604,9 +636,7 @@ export function registerDispatchCommand(parent, io) {
             }
             catch (error) {
                 if (error instanceof SubAgentNotSupportedError) {
-                    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', error.message, { role, toolCall: null, dispatchRecordPath: null }, [
-                        'Switch IDE or pick a role the current IDE supports.'
-                    ]), asJson);
+                    printResult(io, fail('sub-agent.dispatch', 'IDE_NOT_SUPPORTED', error.message, { role, toolCall: null, dispatchRecordPath: null }, ['Switch IDE or pick a role the current IDE supports.']), asJson);
                     process.exitCode = 1;
                     return;
                 }
@@ -697,7 +727,9 @@ export function registerDispatchCommand(parent, io) {
             });
             const nextActions = [
                 'Tool call is dry-run; LLM must execute the tool to actually dispatch the sub-agent.',
-                'After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record ' + dispatchRecordPath + '` periodically.'
+                'After dispatching, the sub-agent should call `peaks sub-agent heartbeat --record ' +
+                    dispatchRecordPath +
+                    '` periodically.'
             ];
             if (counter.warning) {
                 nextActions.push(`Batch is over the RL-1 limit (${BATCH_LIMIT}); consider splitting into multiple batches.`);
@@ -771,7 +803,8 @@ export function registerDispatchCommand(parent, io) {
                     }
                 });
             }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            catch {
+                // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
                 /* best-effort */
             }
         }