peaks-loop 4.1.1 → 4.1.3

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

@@ -0,0 +1,157 @@
+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 { writeJobProgress } from '../../services/job/job-progress-store.js';
+import { JobCheckpointInputSchema, JobBlockInputSchema } from '../../services/job/job-types.js';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice } from '../../services/codegraph/codegraph-autorefresh.js';
+import { asJson, failResult, projectRoot, resolveSliceId } from './job-command-shared.js';
+import { SESSION_ID_HELP, resolveJobStateRoot } from './job-state-root.js';
+const SLICE_NOT_FOUND_HINTS = ['Re-run with one of the valid slice ids'];
+const NO_REFRESH = { codegraph: null, codegraphWarning: null };
+/**
+ * Auto codegraph refresh at the slice-complete boundary. Best-effort:
+ * a refresh failure must never fail the checkpoint.
+ *
+ * A2 (2026-09-17): "must never fail the checkpoint" is not "must never be
+ * seen". A refresh that did not happen while a codegraph store IS in use is now
+ * a warning line (stderr, `warning: ` prefix, via printResult) naming the reason
+ * and the remedy. See `codegraphRefreshNotice` for why `no-codegraph-dir` stays
+ * silent.
+ *
+ * ADVISORY (F1, 2026-09-17) — deliberately exits 0, and the reach of that word
+ * is exactly here. The checkpoint itself SUCCEEDED (the slice flipped to done
+ * and progress.json was mirrored above); the refresh is a derived index,
+ * rebuildable on demand. So the outcome is reported through `ok(...)` + a
+ * `warning:` line, never through `failResult`, and `process.exitCode` is left
+ * alone even when the refresh throws. Raising it would turn an advisory rebuild
+ * into a build breaker for every CI that runs `peaks job checkpoint`. Pinned by
+ * the "advisory stays 0" control in tests/unit/cli/job-exit-code.test.ts.
+ */
+async function applyCheckpointDone(ctx) {
+    const { orch, jobRoot, opts, data, sliceId } = ctx;
+    await orch.checkpointDone({
+        jobId: data.jobId,
+        sliceId,
+        ...(data.commitSha ? { commitSha: data.commitSha } : {})
+    });
+    // v3.1.2: after each --state done, mirror slice progress to
+    // .peaks/_runtime/<sessionId>/job/<jid>/progress.json so the
+    // next LLM turn (or peaks code gate-step-08 hook) can read it.
+    const project = projectRoot(opts);
+    const sessId = jobRoot.sessionId;
+    const state = orch.status(data.jobId);
+    writeJobProgress(project, sessId, {
+        jobId: data.jobId,
+        done: state.done,
+        total: state.total,
+        currentSlice: state.currentSlice,
+        lastCommitSha: data.commitSha ?? null,
+        updatedAt: new Date().toISOString()
+    });
+    let codegraph;
+    try {
+        codegraph = await refreshCodegraphAfterSlice(project);
+    }
+    catch (e) {
+        codegraph = {
+            refreshed: false,
+            reason: 'unavailable',
+            note: `auto codegraph refresh failed: ${e instanceof Error ? e.message : String(e)}`
+        };
+    }
+    return { codegraph, codegraphWarning: codegraphRefreshNotice(codegraph) };
+}
+async function applyCheckpointState(ctx) {
+    const { orch, data, sliceId } = ctx;
+    if (data.state === 'done')
+        return applyCheckpointDone(ctx);
+    if (data.state === 'skipped') {
+        await orch.checkpointSkipped({ jobId: data.jobId, sliceId, reason: data.reason });
+    }
+    else {
+        await orch.checkpointFailed({ jobId: data.jobId, sliceId, reason: data.reason });
+    }
+    return NO_REFRESH;
+}
+function failCheckpointSliceNotFound(io, opts, data, slice) {
+    failResult(io, fail('checkpoint', 'SLICE_NOT_FOUND', slice.message, { jobId: data.jobId, sliceId: data.sliceId, validSliceIds: slice.validSliceIds }, SLICE_NOT_FOUND_HINTS), opts);
+}
+async function runJobCheckpoint(opts, io) {
+    const parsed = JobCheckpointInputSchema.safeParse({
+        jobId: opts.jobId,
+        sliceId: opts.sliceId,
+        state: opts.state,
+        commitSha: opts.commitSha,
+        reason: opts.reason,
+        project: projectRoot(opts),
+        json: opts.json
+    });
+    if (!parsed.success)
+        return failResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+    const jobRoot = resolveJobStateRoot(opts, opts.jobId);
+    const store = new JobStateStore(jobRoot.rootDir);
+    // D7: `--slice-id` accepts the canonical `slice-NNN` or the slice's label
+    // ("S1"); an id that matches no slice is rejected here, BEFORE any write,
+    // so progress.json is never touched by a checkpoint that matched nothing.
+    const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
+    if ('message' in slice) {
+        failCheckpointSliceNotFound(io, opts, parsed.data, slice);
+        return;
+    }
+    const orch = new JobOrchestrator(store);
+    const outcome = await applyCheckpointState({
+        orch,
+        jobRoot,
+        opts,
+        data: parsed.data,
+        sliceId: slice.sliceId
+    });
+    printResult(io, ok('checkpoint', { sliceId: slice.sliceId, status: parsed.data.state, codegraph: outcome.codegraph }, outcome.codegraphWarning === null ? [] : [outcome.codegraphWarning]), asJson(opts));
+}
+async function runJobBlock(opts, io) {
+    const parsed = JobBlockInputSchema.safeParse({
+        jobId: opts.jobId,
+        sliceId: opts.sliceId,
+        reason: opts.reason,
+        project: projectRoot(opts),
+        json: opts.json
+    });
+    if (!parsed.success)
+        return failResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+    const store = new JobStateStore(resolveJobStateRoot(opts, opts.jobId).rootDir);
+    // D7 (same silent no-op as checkpoint): resolve label → sliceId, reject a
+    // miss before any write.
+    const slice = resolveSliceId(store, parsed.data.jobId, parsed.data.sliceId);
+    if ('message' in slice) {
+        return failResult(io, fail('block', 'SLICE_NOT_FOUND', slice.message, {
+            jobId: parsed.data.jobId,
+            sliceId: parsed.data.sliceId,
+            validSliceIds: slice.validSliceIds
+        }, SLICE_NOT_FOUND_HINTS), opts);
+    }
+    const orch = new JobOrchestrator(store);
+    await orch.blockSlice({ ...parsed.data, sliceId: slice.sliceId });
+    printResult(io, ok('block', { blocked: slice.sliceId, reason: parsed.data.reason }), asJson(opts));
+}
+// M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue,
+// handoff, resume. `block` is registered first here, before `continue` /
+// `resume` / `progress` / `handoff`, to keep the `job` help order stable.
+export function registerJobCheckpointCommands(job, io) {
+    addJsonOption(job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobCheckpoint(opts, io));
+    addJsonOption(job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')).action((opts) => runJobBlock(opts, io));
+}

package/dist/cli/commands/job-command-shared.d.ts

@@ -0,0 +1,109 @@
+import type { ResultEnvelope } from 'peaks-loop-shared/result';
+import { type ProgramIO } from '../cli-helpers.js';
+import type { JobStateStore } from '../../services/job/job-state-store.js';
+export declare function asJson(opts: JobJsonOpts): boolean;
+/**
+ * process exit non-zero.
+ *
+ * WHY THIS EXISTS. `printResult` (`src/cli/cli-helpers.ts`) renders a failed
+ * envelope — `CODE: message` + `nextActions` on stderr — but it does NOT set
+ * `process.exitCode`. Measured with the real CLI before this fix:
+ * `peaks job block --job-id j1 --slice-id nope --reason why` printed
+ * `SLICE_NOT_FOUND: …` on stderr and exited **0**, so CI and every script
+ * wrapping `peaks job` read the failure as success. Seven of this file's nine
+ * failure-reporting sites had that gap; only `job progress` set the code, and
+ * that was the file's one accidental precedent rather than a rule.
+ *
+ * Every `fail(...)` envelope in this file now goes through here, so "reported a
+ * failure" and "exited non-zero" cannot drift apart again. The helper takes the
+ * Commander `opts` object and calls `asJson(opts)` itself — it must never be
+ * handed a bare `opts.json`-less boolean, and it must never pass `opts` to
+ * `printResult` (see the `asJson` comment above for that bug's history).
+ *
+ * DELIBERATELY NOT APPLIED TO THE ADVISORY PATHS. Three sites in this file
+ * report a non-fatal outcome through an `ok(...)` envelope and MUST keep
+ * exiting 0: the two `emitJobEvent` best-effort catches (`job init`,
+ * `job status`) and the post-slice codegraph refresh in `job checkpoint`, whose
+ * stated design is "a refresh failure must never fail the checkpoint". Those
+ * are annotated in place; `tests/unit/cli/job-exit-code.test.ts` pins both
+ * directions so a future blanket "every warning exits 1" edit turns red.
+ */
+export declare function failResult(io: ProgramIO, result: ResultEnvelope<unknown>, opts: JobJsonOpts): void;
+export declare function projectRoot(opts: JobProjectOpts): string;
+/**
+ * D7: slices are keyed `slice-NNN`, but `peaks job init --slice-list "S1,…"`
+ * takes labels, so the natural string to pass back to `--slice-id` is that same
+ * label. Resolve an exact sliceId OR an exact label to the canonical sliceId;
+ * anything else is a hard error listing the valid ids, so a mistyped
+ * `slice-04` can never be accepted as a silent no-op that leaves the slice
+ * pending.
+ */
+export declare function resolveSliceId(store: JobStateStore, jobId: string, sliceId: string): {
+    sliceId: string;
+} | {
+    message: string;
+    validSliceIds: string[];
+};
+/**
+ * S10 (2026-09-20) — the option shapes the `job` subcommands read.
+ *
+ * WHY. Commander types an action's `opts` as `any`, so every `opts.<field>`
+ * access in this file was an `any` access: 109 `no-unsafe-*` findings, the
+ * largest single TS root in the S10 census. The root is the *entrance* — the
+ * untyped `opts` parameter — not the 109 sites, so the fix is to declare it.
+ *
+ * Each interface names exactly the options its own command READS, plus `--json`
+ * (added by `addJsonOption`). So a field absent here is a field that command
+ * does not read, and reading it is now a compile error instead of an `any`
+ * access. (A command may declare more than it reads — `job status` declares
+ * `--show-cost` and never looks at it; that option is deliberately not listed.)
+ * `readonly` is honest: these are read-only inputs; Commander owns the object.
+ *
+ * The four helpers above (`asJson`, `failResult`, `projectRoot`,
+ * `resolveJobStateRoot`) take the narrowest structural type each one actually
+ * reads, so all eleven action callbacks remain assignable to them.
+ */
+export interface JobJsonOpts {
+    readonly json?: boolean;
+}
+export interface JobProjectOpts {
+    readonly project?: string;
+}
+export interface JobRootOpts extends JobProjectOpts {
+    readonly sessionId?: string;
+}
+export interface JobInitOpts extends JobRootOpts, JobJsonOpts {
+    readonly jobId: string;
+    readonly sliceList: string;
+    readonly parallelismHint?: string;
+    readonly exitPolicy?: string;
+    readonly mainLoopStrategy?: string;
+    readonly rotateEvery?: string;
+}
+export interface JobStatusOpts extends JobRootOpts, JobJsonOpts {
+    readonly jobId: string;
+    readonly watch?: boolean;
+}
+export interface JobIdOnlyOpts extends JobRootOpts, JobJsonOpts {
+    readonly jobId: string;
+}
+export interface JobSubagentCleanupOpts extends JobIdOnlyOpts {
+    readonly batchId: string;
+    readonly force?: boolean;
+}
+export interface JobCheckpointOpts extends JobIdOnlyOpts {
+    readonly sliceId: string;
+    readonly state: string;
+    readonly commitSha?: string;
+    readonly reason?: string;
+}
+export interface JobBlockOpts extends JobIdOnlyOpts {
+    readonly sliceId: string;
+    readonly reason: string;
+}
+export interface JobProgressOpts extends JobIdOnlyOpts {
+    readonly allowMissing?: boolean;
+}
+export interface JobCostCheckOpts extends JobRootOpts, JobJsonOpts {
+    readonly reviewFile: string;
+}

package/dist/cli/commands/job-command-shared.js

@@ -0,0 +1,72 @@
+import { printResult } from '../cli-helpers.js';
+// `printResult`'s third parameter is `asJson: boolean`. Each `job` subcommand
+// registers `--json` (see the `addJsonOption` calls below), so the flag to pass
+// it is `opts.json` — NEVER the whole options object. Commander types an
+// action's `opts` as `any`, so `printResult(io, envelope, opts)` type-checks
+// and is ALWAYS truthy: it forces the envelope branch and makes the
+// `warning: ` / `next: ` human rendering in `cli-helpers.ts` unreachable. That
+// is how the A2 codegraph-refresh warning ended up inside the JSON stdout
+// envelope instead of on stderr as `warning: `. `job progress` always passed
+// `opts.json`; the rest of this file did not, and E1 (2026-09-17) brought them
+// in line. Do not reintroduce the object form.
+//
+// S10 (2026-09-20): the parameter is now `JobJsonOpts` rather than `any`. The
+// gate above is about which VALUE is passed, not about the parameter's type —
+// declaring the one field this function reads is what stops every `opts.<x>`
+// call site in the file from being an `any` access. See the option-interface
+// block above `registerJobCommands`.
+export function asJson(opts) {
+    return opts.json === true;
+}
+/**
+ * process exit non-zero.
+ *
+ * WHY THIS EXISTS. `printResult` (`src/cli/cli-helpers.ts`) renders a failed
+ * envelope — `CODE: message` + `nextActions` on stderr — but it does NOT set
+ * `process.exitCode`. Measured with the real CLI before this fix:
+ * `peaks job block --job-id j1 --slice-id nope --reason why` printed
+ * `SLICE_NOT_FOUND: …` on stderr and exited **0**, so CI and every script
+ * wrapping `peaks job` read the failure as success. Seven of this file's nine
+ * failure-reporting sites had that gap; only `job progress` set the code, and
+ * that was the file's one accidental precedent rather than a rule.
+ *
+ * Every `fail(...)` envelope in this file now goes through here, so "reported a
+ * failure" and "exited non-zero" cannot drift apart again. The helper takes the
+ * Commander `opts` object and calls `asJson(opts)` itself — it must never be
+ * handed a bare `opts.json`-less boolean, and it must never pass `opts` to
+ * `printResult` (see the `asJson` comment above for that bug's history).
+ *
+ * DELIBERATELY NOT APPLIED TO THE ADVISORY PATHS. Three sites in this file
+ * report a non-fatal outcome through an `ok(...)` envelope and MUST keep
+ * exiting 0: the two `emitJobEvent` best-effort catches (`job init`,
+ * `job status`) and the post-slice codegraph refresh in `job checkpoint`, whose
+ * stated design is "a refresh failure must never fail the checkpoint". Those
+ * are annotated in place; `tests/unit/cli/job-exit-code.test.ts` pins both
+ * directions so a future blanket "every warning exits 1" edit turns red.
+ */
+export function failResult(io, result, opts) {
+    printResult(io, result, asJson(opts));
+    process.exitCode = 1;
+}
+export function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * D7: slices are keyed `slice-NNN`, but `peaks job init --slice-list "S1,…"`
+ * takes labels, so the natural string to pass back to `--slice-id` is that same
+ * label. Resolve an exact sliceId OR an exact label to the canonical sliceId;
+ * anything else is a hard error listing the valid ids, so a mistyped
+ * `slice-04` can never be accepted as a silent no-op that leaves the slice
+ * pending.
+ */
+export function resolveSliceId(store, jobId, sliceId) {
+    const slices = store.load(jobId).slices;
+    const hit = slices.find((sl) => sl.sliceId === sliceId || sl.label === sliceId);
+    if (hit)
+        return { sliceId: hit.sliceId };
+    return {
+        message: `no slice "${sliceId}" in job ${jobId}; valid ids: ${slices.map((sl) => `${sl.sliceId} (${sl.label})`).join(', ')}`,
+        validSliceIds: slices.map((sl) => sl.sliceId)
+    };
+}

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

@@ -1,67 +1,7 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
-export declare function asJson(opts: JobJsonOpts): boolean;
-/**
- * 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;
-};
-/**
- * S10 (2026-09-20) — the option shapes the `job` subcommands read.
- *
- * WHY. Commander types an action's `opts` as `any`, so every `opts.<field>`
- * access in this file was an `any` access: 109 `no-unsafe-*` findings, the
- * largest single TS root in the S10 census. The root is the *entrance* — the
- * untyped `opts` parameter — not the 109 sites, so the fix is to declare it.
- *
- * Each interface names exactly the options its own command READS, plus `--json`
- * (added by `addJsonOption`). So a field absent here is a field that command
- * does not read, and reading it is now a compile error instead of an `any`
- * access. (A command may declare more than it reads — `job status` declares
- * `--show-cost` and never looks at it; that option is deliberately not listed.)
- * `readonly` is honest: these are read-only inputs; Commander owns the object.
- *
- * The four helpers above (`asJson`, `failResult`, `projectRoot`,
- * `resolveJobStateRoot`) take the narrowest structural type each one actually
- * reads, so all eleven action callbacks remain assignable to them.
- */
-export interface JobJsonOpts {
-    readonly json?: boolean;
-}
-interface JobProjectOpts {
-    readonly project?: string;
-}
-export interface JobRootOpts extends JobProjectOpts {
-    readonly sessionId?: string;
-}
+import { asJson } from './job-command-shared.js';
+import { SESSION_ID_HELP, resolveJobStateRoot } from './job-state-root.js';
+export { asJson, SESSION_ID_HELP, resolveJobStateRoot };
+export type { JobJsonOpts, JobRootOpts, JobProjectOpts } from './job-command-shared.js';
 export declare function registerJobCommands(program: Command, io?: ProgramIO): void;
-export {};