peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/job-cost-check-command.js

@@ -0,0 +1,41 @@
+import { fail } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { buildCostCheckEnvelope, runKarpathyCostCheck } from '../../services/karpathy-cost/karpathy-cost-check-service.js';
+import { read24hState } from '../../services/24h-mode/store.js';
+import { asJson, failResult, projectRoot } from './job-command-shared.js';
+import { SESSION_ID_HELP } from './job-state-root.js';
+const COST_CHECK_DESCRIPTION = "Read the slice's rd/karpathy-review.md and decide whether to downgrade a block gateAction to warn (slice 2026-07-30-karpathy-cost-self-review).";
+const COST_CHECK_REVIEW_FILE_HELP = 'path to rd/karpathy-review.md (or its .json sibling if the file is JSON)';
+function runJobCostCheck(opts, io) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        return failResult(io, fail('karpathy-cost-check', 'NO_ACTIVE_SESSION', 'karpathy-cost-check requires --session-id (or an active peaks-code session)', { project }, [
+            'Re-run with --session-id <sid>',
+            'Or run `peaks workspace init` to create a session first'
+        ]), opts);
+    }
+    const is24hModeActive = () => {
+        try {
+            const snapshot = read24hState(project, sessionId);
+            return snapshot.state === '24H_ACTIVE';
+        }
+        catch {
+            return false;
+        }
+    };
+    const out = runKarpathyCostCheck({
+        reviewFilePath: opts.reviewFile,
+        is24hModeActive
+    });
+    printResult(io, buildCostCheckEnvelope(out), asJson(opts));
+}
+export function registerJobCostCheckCommand(job, io) {
+    addJsonOption(job
+        .command('karpathy-cost-check')
+        .description(COST_CHECK_DESCRIPTION)
+        .requiredOption('--review-file <path>', COST_CHECK_REVIEW_FILE_HELP)
+        .option('--project <repo>')
+        .option('--session-id <sid>', SESSION_ID_HELP)).action((opts) => runJobCostCheck(opts, io));
+}

package/dist/cli/commands/job-init-status-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobInitStatusCommands(job: Command, io: ProgramIO): void;

package/dist/cli/commands/job-init-status-commands.js

@@ -0,0 +1,149 @@
+import { ok, fail } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { asJson, failResult, projectRoot } from './job-command-shared.js';
+import { SESSION_ID_HELP, resolveJobStateRoot } from './job-state-root.js';
+/**
+ * `job init` resolves its own session id (the schema needs it before the state
+ * root exists), so it repeats the D6 precedence rather than reusing
+ * `resolveJobStateRoot`.
+ */
+function resolveInitSessionId(opts, project) {
+    return opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
+}
+/**
+ * ADVISORY (F1, 2026-09-17) — deliberately exits 0. Event emission is a
+ * telemetry side effect; a failed emit does not mean `job init` failed (the
+ * state file was already written). This catch must NOT be routed through
+ * `failResult`. Pinned by the "advisory stays 0" control in
+ * tests/unit/cli/job-exit-code.test.ts.
+ */
+function emitJobStarted(state) {
+    try {
+        emitJobEvent({
+            kind: 'job-started',
+            jobId: state.jobId,
+            total: state.slices.length,
+            strategy: state.mainLoopStrategy
+        });
+    }
+    catch (e) {
+        void e;
+    }
+}
+function failInitNoActiveSession(io, opts, project) {
+    failResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, ['Re-run with --session-id <sid>', 'Or run `peaks workspace init` to create a session first']), opts);
+}
+function parseJobInitInput(opts, sessionId, project) {
+    return JobInitInputSchema.safeParse({
+        jobId: opts.jobId,
+        sessionId,
+        sliceList: opts.sliceList
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean),
+        parallelismHint: opts.parallelismHint,
+        exitPolicy: opts.exitPolicy,
+        mainLoopStrategy: opts.mainLoopStrategy,
+        rotateEvery: Number(opts.rotateEvery),
+        project,
+        json: opts.json
+    });
+}
+function runJobInit(opts, io) {
+    const project = projectRoot(opts);
+    // Resolve sessionId: explicit flag > PEAKS_SESSION_ID > caller-first session binding
+    // (this caller's binding, else the project-global session.json) > FAIL.
+    // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+    // a random UUID would scatter state across dirs and break resume/auto-compact.
+    let sessionId = resolveInitSessionId(opts, project);
+    if (!sessionId) {
+        failInitNoActiveSession(io, opts, project);
+        return;
+    }
+    const parsed = parseJobInitInput(opts, sessionId, project);
+    if (!parsed.success)
+        return failResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+    const jobRoot = resolveJobStateRoot(opts);
+    const store = new JobStateStore(jobRoot.rootDir);
+    const orch = new JobOrchestrator(store);
+    const state = orch.init({
+        jobId: parsed.data.jobId,
+        sessionId: parsed.data.sessionId,
+        sliceList: parsed.data.sliceList,
+        parallelismHint: parsed.data.parallelismHint,
+        exitPolicy: parsed.data.exitPolicy,
+        mainLoopStrategy: parsed.data.mainLoopStrategy,
+        rotateEvery: parsed.data.rotateEvery
+    });
+    emitJobStarted(state);
+    printResult(io, ok('init', {
+        jobId: state.jobId,
+        sliceCount: state.slices.length,
+        statePath: `${jobRoot.rootDir}/${state.jobId}/state.json`
+    }), asJson(opts));
+}
+function runJobStatus(opts, io) {
+    const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+    const orch = new JobOrchestrator(store);
+    const s = orch.status(opts.jobId);
+    if (opts.watch) {
+        const draw = () => {
+            const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+            process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+        };
+        draw();
+        const iv = setInterval(() => {
+            const u = orch.status(opts.jobId);
+            Object.assign(s, u);
+            draw();
+            if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv);
+        }, 3000);
+        process.on('SIGINT', () => {
+            clearInterval(iv);
+            process.stdout.write('\n');
+            process.exit(0);
+        });
+        return;
+    }
+    try {
+        emitJobEvent({
+            kind: 'job-progress',
+            jobId: opts.jobId,
+            done: s.done,
+            total: s.total,
+            ...(s.currentSlice ? { currentSlice: s.currentSlice } : {})
+        });
+    }
+    catch (e) {
+        // ADVISORY (F1, 2026-09-17) — deliberately exits 0. The status itself
+        // was already read successfully; the emit is telemetry. Same rule as
+        // the `job init` catch above: do NOT route through `failResult`.
+        void e;
+    }
+    printResult(io, ok('status', s), asJson(opts));
+}
+export function registerJobInitStatusCommands(job, io) {
+    addJsonOption(job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobInit(opts, io));
+    addJsonOption(job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobStatus(opts, io));
+}

package/dist/cli/commands/job-run-commands.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobRunCommands(job: Command, io: ProgramIO): void;

package/dist/cli/commands/job-run-commands.js

@@ -0,0 +1,97 @@
+import { ok, fail } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { readJobProgress, tryReadJobProgress, describeNextSlice } from '../../services/job/job-progress-store.js';
+import { asJson, failResult, projectRoot } from './job-command-shared.js';
+import { SESSION_ID_HELP, resolveJobStateRoot } from './job-state-root.js';
+const PROGRESS_DESCRIPTION = 'v3.1.2: read the on-disk slice progress mirror (.peaks/_runtime/<sid>/job/<jid>/progress.json). ' +
+    'Returns { jobId, done, total, currentSlice, lastCommitSha, updatedAt }.';
+// "return done=0/total=0 envelope instead of failing when progress.json is
+// absent". No code path has ever returned such an envelope — the option was
+// born in `d9a1a098` with `process.exitCode = 1` on the same branch — so it
+// described a contract that never existed, and `--allow-missing` appeared to
+// be broken. It is not: its job is to pick WHICH structured code reports the
+// absence. The help text was the side that was wrong; it now says what the
+// flag does. See `rd/requests/013-…-exit-code-root-cause.md` for why the
+// alternative reading was rejected (the literal promise is also
+// unimplementable without a new absent-vs-corrupt distinction:
+// `tryReadJobProgress` returns `null` for a corrupt file too, so "done=0"
+// there would report unreadable state as empty state).
+const PROGRESS_ALLOW_MISSING_HELP = 'report an absent progress.json as NO_PROGRESS (expected absence) rather than PROGRESS_READ_FAILED (read error); the command still exits non-zero';
+function runJobContinue(opts, io) {
+    const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+    const orch = new JobOrchestrator(store);
+    const r = orch.continueNow(opts.jobId);
+    printResult(io, ok('continue', r), asJson(opts));
+}
+function runJobResume(opts, io) {
+    const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+    const orch = new JobOrchestrator(store);
+    const s = orch.status(opts.jobId);
+    printResult(io, ok('resume', { resumed: opts.jobId, ...s }), asJson(opts));
+}
+// v3.1.2: read the on-disk slice progress mirror written by `peaks job
+// checkpoint --state done`; gate-step-08 and Step 0.7 (resume) read it too. The
+// `next:` sentence comes from describeNextSlice, never re-derived from state.json.
+function runJobProgress(opts, io) {
+    try {
+        const jobRoot = resolveJobStateRoot(opts, opts.jobId);
+        const sessId = jobRoot.sessionId;
+        const project = projectRoot(opts);
+        const progress = opts.allowMissing === true
+            ? tryReadJobProgress(project, sessId, opts.jobId)
+            : readJobProgress(project, sessId, opts.jobId);
+        if (progress === null) {
+            // F1: this site already set `process.exitCode = 1` by hand; it is
+            // routed through `failResult` so all nine failure sites in this file
+            // share one rule instead of this one being the lone precedent.
+            failResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
+                'Run `peaks job checkpoint --state done ...` at least once to seed progress.json.',
+                // return a zero-progress envelope." That line could only ever be
+                // printed when `--allow-missing` had ALREADY been passed — this
+                // `progress === null` branch is unreachable otherwise, because the
+                // no-flag path throws into the catch below and reports
+                // PROGRESS_READ_FAILED. So the CLI was advising the caller to pass
+                // the flag they had just passed, to obtain an envelope that does
+                // not exist. Replaced with the fact the caller actually needs.
+                '--allow-missing selects this NO_PROGRESS envelope over a PROGRESS_READ_FAILED read error; it does not change the exit code.'
+            ]), opts);
+            return;
+        }
+        printResult(io, ok('progress', progress, [], [`Next: ${describeNextSlice(progress, progress.jobId)}`]), asJson(opts));
+    }
+    catch (err) {
+        failResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts);
+    }
+}
+function runJobHandoff(opts, io) {
+    const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+    const orch = new JobOrchestrator(store);
+    const s = orch.status(opts.jobId);
+    printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), asJson(opts));
+}
+export function registerJobRunCommands(job, io) {
+    addJsonOption(job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobContinue(opts, io));
+    addJsonOption(job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobResume(opts, io));
+    addJsonOption(job
+        .command('progress')
+        .description(PROGRESS_DESCRIPTION)
+        .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')
+        .option('--allow-missing', PROGRESS_ALLOW_MISSING_HELP)).action((opts) => runJobProgress(opts, io));
+    addJsonOption(job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobHandoff(opts, io));
+}

package/dist/cli/commands/job-state-root.d.ts

@@ -0,0 +1,35 @@
+import { type JobRootOpts } from './job-command-shared.js';
+/**
+ * D6: every job subcommand resolves a job root, so every one of them must be
+ * able to name the session that holds the job. Same precedence as the rest of
+ * the CLI (`peaks sub-agent dispatch`, `peaks web *`, `peaks share *`), except
+ * that job state has no "unknown-sid" location to land in — an unresolvable
+ * session is an error, not a silent fallback.
+ */
+export declare const SESSION_ID_HELP = "session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback: NO_ACTIVE_SESSION error)";
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order (D6 — a job must stay addressable while the single per-project
+ * `.peaks/_runtime/session.json` binding points at another session):
+ * 1. `--session-id` flag (explicit override)
+ * 2. `PEAKS_SESSION_ID` env var
+ * 3. `getCurrentSessionId(project)` — this caller's session binding, falling back
+ *    to `.peaks/_runtime/session.json` when no caller binding is resolvable
+ * 4. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ *
+ * When `jobId` is passed and it is absent from the resolved session, the thrown
+ * error names the session that does hold it (if any), instead of leaving the
+ * caller with a bare "no state for <job> at <other-sid>" path.
+ */
+export declare function resolveJobStateRoot(opts: JobRootOpts, jobId?: string): {
+    rootDir: string;
+    sessionId: string;
+    projectRoot: string;
+};

package/dist/cli/commands/job-state-root.js

@@ -0,0 +1,76 @@
+// Split out of `job-commands.ts`: the D6
+// session-id resolution every `job` subcommand runs before it can address
+// `<project>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`.
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { projectRoot } from './job-command-shared.js';
+/**
+ * D6: every job subcommand resolves a job root, so every one of them must be
+ * able to name the session that holds the job. Same precedence as the rest of
+ * the CLI (`peaks sub-agent dispatch`, `peaks web *`, `peaks share *`), except
+ * that job state has no "unknown-sid" location to land in — an unresolvable
+ * session is an error, not a silent fallback.
+ */
+export const SESSION_ID_HELP = 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback: NO_ACTIVE_SESSION error)';
+/**
+ * The session (a direct child of `<project>/.peaks/_runtime/`) that holds
+ * `jobId`, or null. Only used to explain a miss: a job that lives in another
+ * session must be reported by name so the caller can re-run with --session-id.
+ */
+function findSessionHoldingJob(project, jobId) {
+    const runtimeDir = join(project, '.peaks', '_runtime');
+    if (!existsSync(runtimeDir))
+        return null;
+    for (const entry of readdirSync(runtimeDir, { withFileTypes: true })) {
+        if (entry.isDirectory() &&
+            existsSync(join(runtimeDir, entry.name, 'job', jobId, 'state.json'))) {
+            return entry.name;
+        }
+    }
+    return null;
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order (D6 — a job must stay addressable while the single per-project
+ * `.peaks/_runtime/session.json` binding points at another session):
+ * 1. `--session-id` flag (explicit override)
+ * 2. `PEAKS_SESSION_ID` env var
+ * 3. `getCurrentSessionId(project)` — this caller's session binding, falling back
+ *    to `.peaks/_runtime/session.json` when no caller binding is resolvable
+ * 4. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ *
+ * When `jobId` is passed and it is absent from the resolved session, the thrown
+ * error names the session that does hold it (if any), instead of leaving the
+ * caller with a bare "no state for <job> at <other-sid>" path.
+ */
+export function resolveJobStateRoot(opts, jobId) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-code session via peaks workspace init');
+    }
+    // Sid axis — the sibling of the jobId guard in `JobStateStore.jobDir`. A
+    // caller-supplied `--session-id` reaches this join unmodified, so a
+    // traversal value lands `job/<id>/state.json` outside every project root
+    // while the envelope still reads `ok: true`.
+    if (isUnsafePathInput(sessionId)) {
+        throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    if (jobId && !existsSync(join(rootDir, jobId, 'state.json'))) {
+        const other = findSessionHoldingJob(project, jobId);
+        throw new Error(other
+            ? `JOB_NOT_IN_SESSION: no job "${jobId}" in session "${sessionId}"; it lives in session "${other}" — re-run with --session-id ${other}`
+            : `JOB_NOT_IN_SESSION: no job "${jobId}" in session "${sessionId}" (and no other session under .peaks/_runtime/ has it)`);
+    }
+    return { rootDir, sessionId, projectRoot: project };
+}

package/dist/cli/commands/lease-metrics-commands.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks lease-metrics` — slice 2026-07-29-worktree-l2-extended Part 4.A + Part 5.
  *
  * Part 4.A: aggregate lease-kind observability events for one session,
  * render per-kind counts + a 5-event chronological tail.

package/dist/cli/commands/lease-metrics-commands.js

@@ -1,5 +1,4 @@
 /**
- * `peaks lease-metrics` — slice 2026-07-29-worktree-l2-extended Part 4.A + Part 5.
  *
  * Part 4.A: aggregate lease-kind observability events for one session,
  * render per-kind counts + a 5-event chronological tail.

package/dist/cli/commands/lease-stats-commands.d.ts

@@ -1,5 +1,4 @@
 /**
- * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
  *
  * Single top-level command that aggregates lease observability for
  * the whole project root and returns a summary envelope suitable

package/dist/cli/commands/lease-stats-commands.js

@@ -1,5 +1,4 @@
 /**
- * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
  *
  * Single top-level command that aggregates lease observability for
  * the whole project root and returns a summary envelope suitable

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

@@ -1,7 +1,6 @@
 /**
  * `peaks log *` subcommands.
  *
- * Slice 2026-06-16-cli-logging (G4). Two subcommands:
  *   - `peaks log tail [--lines N]` — print the last N lines of
  *     today's JSONL log to stdout. With `--json`, prints as a
  *     JSON envelope (matching the project's response shape).
@@ -10,7 +9,6 @@
  * The CLI layer is intentionally thin: it formats the output and
  * delegates the actual filesystem reads to
  * `src/services/log/log-commands-service.ts`. That service is
- * already covered by `tests/unit/log/log-commands.test.ts`.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';

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

@@ -1,7 +1,6 @@
 /**
  * `peaks log *` subcommands.
  *
- * Slice 2026-06-16-cli-logging (G4). Two subcommands:
  *   - `peaks log tail [--lines N]` — print the last N lines of
  *     today's JSONL log to stdout. With `--json`, prints as a
  *     JSON envelope (matching the project's response shape).
@@ -10,7 +9,6 @@
  * The CLI layer is intentionally thin: it formats the output and
  * delegates the actual filesystem reads to
  * `src/services/log/log-commands-service.ts`. That service is
- * already covered by `tests/unit/log/log-commands.test.ts`.
  */
 import { join } from 'node:path';
 import { homedir } from 'node:os';
@@ -26,7 +24,6 @@ export function registerLogCommands(program, io) {
         .description("Print the last 50 lines of today's peaks-loop log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.")
         .option('--lines <n>', 'number of lines to show (default 50)', (value) => Number(value))
         .option('--date <YYYY-MM-DD>', 'read the log for this UTC date instead of today (PRD AC2: PEAKS_LOG_DATE_OVERRIDE)')
-        // Slice 2026-06-23-audit-4th #B2: --batch filter for cross-run
         // correlation. Without this, a user post-hoc cannot group the
         // log lines for one batch (they interleave in the JSONL file).
         .option('--batch <id>', 'filter entries by batchId (sub-agent dispatch / heartbeat / share)')).action((options) => {

package/dist/cli/commands/loop-eval-capture-index.d.ts

@@ -0,0 +1,4 @@
+/** Test seam: pick the next cycle-N.json number for capture-score
+ *  writes. The run-driver also writes to the same dir; the next
+ *  index = max(prior)+1, or 1. */
+export declare function nextEvalCaptureIndex(projectRoot: string, sid: string, rid: string): number;

package/dist/cli/commands/loop-eval-capture-index.js

@@ -0,0 +1,44 @@
+// The cycle-file index seam for `--capture-score`. Pure path/IO plus its own path-safety
+// contract; it owns no command registration, which is why it lives outside the
+// registrar that calls it.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+/** Test seam: pick the next cycle-N.json number for capture-score
+ *  writes. The run-driver also writes to the same dir; the next
+ *  index = max(prior)+1, or 1. */
+export function nextEvalCaptureIndex(projectRoot, sid, rid) {
+    // BOTH id axes: this function is the join for the capture-score cycle dir.
+    // The action guards `options.session` and `rid` before calling in, but the
+    // seam is callable on its own, so the join states its own contract. The rid
+    // half was missing until 2026-09-14 (repair R1) — the same second-slot hole
+    // the action had, in the same file, one function below it.
+    if (isUnsafePathInput(sid)) {
+        throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
+    }
+    if (isUnsafePathInput(rid)) {
+        throw new Error(`Invalid request id: ${rid} (must be a single path segment)`);
+    }
+    const dir = join(projectRoot, '.peaks', '_runtime', sid, 'loop', rid, 'cycles');
+    if (!existsSync(dir))
+        return 1;
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const fs = require('node:fs');
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch {
+        return 1;
+    }
+    let best = null;
+    for (const entry of entries) {
+        const m = entry.match(/^cycle-(\d+)\.json$/);
+        if (m === null)
+            continue;
+        const n = parseInt(m[1] ?? '0', 10);
+        if (best === null || n > best)
+            best = n;
+    }
+    return (best ?? 0) + 1;
+}

package/dist/cli/commands/loop-eval-commands.d.ts

@@ -3,18 +3,21 @@
  *
  * CLI surface for the workflow primitive + the loop evaluator dispatcher.
  *
- * New commands (added under the existing `peaks workflow` group and the
+ * Commands (added under the existing `peaks workflow` group and the
  * existing `peaks loop` group — never as new top-level commands, per the
  * peaks-loop add-a-new-subcommand-check-for-existing-top-level-first rule):
  *
  *   peaks workflow run <id> --session <sid> --project <repo> --json
- *   peaks workflow plan <id> --session <sid> --json   (dry-run)
+ *   peaks workflow graph <id> --session <sid> --json   (dry-run)
  *   peaks workflow lint <id> --session <sid> --json
  *   peaks loop eval <rid> --evaluator <name> [--project <repo>] [--json]
+ *   peaks loop check-monotonic <rid> --session <sid> [--json]
+ *   peaks loop spec show|bootstrap|lint ...
+ *   peaks loop run <rid> --session <sid> [--json]
  *
- * Karpathy §2: separate file from workflow-commands.ts to stay under
- * the 800-line budget.
+ * This module is the registrar only: each command family owns its own file, so a
+ * change to one family cannot make the others harder to edit.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerWorkflowEvalCommands(program: Command, io: ProgramIO): void;