peaks-loop 4.1.2 → 4.1.3

package/dist/cli/commands/finalize-runners.js

@@ -0,0 +1,92 @@
+/**
+ * The `finalize` action body for `peaks sub-agent`, split out of
+ * `share-commands.ts` so that registrar file stays under the line cap. The
+ * registrar fires this runner without awaiting it (the original fired a
+ * floating async IIFE in the same way).
+ *
+ * `runFinalizeSweep` builds the accumulator, applies the outcome mapping and
+ * prints the envelope; the three selection branches live in
+ * `finalize-branches.ts` and the selection rule itself in
+ * `finalize-selection.ts`.
+ */
+import { resolve } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { OUTCOME_MAP, buildFinalizeHints, makeAccumulator, tryReadRecord } from './finalize-accumulator.js';
+import { finalizeAllStale, finalizeByBatch, finalizeByRequestId } from './finalize-branches.js';
+export async function runFinalize(options, io) {
+    const asJson = options.json === true;
+    try {
+        const projectRoot = resolve(options.project ?? process.cwd());
+        const sessionId = options.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        if (!options.allStale && !options.requestId && !options.batch) {
+            printResult(io, fail('sub-agent.finalize', 'MISSING_TARGET', 'Pass --request-id or --batch (or --all-stale)', { ok: false }, ['Call finalize after each Task completes.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        await runFinalizeSweep({ options, io, asJson, projectRoot, sessionId });
+    }
+    catch (error) {
+        printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, [
+            'Inspect the error.'
+        ]), asJson);
+        process.exitCode = 1;
+    }
+}
+async function runFinalizeSweep(input) {
+    const { options, io, asJson, projectRoot, sessionId } = input;
+    const outcome = (options.outcome ?? 'done');
+    const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
+    const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
+    const mapped = OUTCOME_MAP[outcome] ?? OUTCOME_MAP['done'];
+    const acc = makeAccumulator();
+    const readOne = (recordPath) => tryReadRecord(recordPath, readRecord, acc);
+    const apply = (recordPath, rid) => {
+        markCompleted({
+            recordPath,
+            now: () => new Date(),
+            status: mapped.status,
+            outcome: mapped.outcome,
+            projectRoot
+        });
+        acc.finalized.push({ recordPath, requestId: rid, status: mapped.status });
+    };
+    let selection = null;
+    if (options.allStale) {
+        finalizeAllStale({ readActiveDispatchIndex, projectRoot, sessionId, apply, acc });
+    }
+    else if (options.requestId) {
+        const result = await finalizeByRequestId({
+            projectRoot,
+            sessionId,
+            requestId: options.requestId,
+            io,
+            asJson,
+            readOne,
+            apply,
+            acc
+        });
+        if (result.kind === 'not-found')
+            return;
+        selection = result.selection;
+    }
+    else {
+        await finalizeByBatch({ projectRoot, sessionId, batchId: options.batch, readOne, apply, acc });
+    }
+    printFinalizeResult({ io, asJson, sessionId, outcome, acc, selection });
+    if (acc.errors.length > 0)
+        process.exitCode = 1;
+}
+/** Print the `sub-agent.finalize` envelope and its hints. */
+function printFinalizeResult(input) {
+    const { acc } = input;
+    printResult(input.io, ok('sub-agent.finalize', {
+        finalized: acc.finalized,
+        skipped: acc.skipped,
+        errors: acc.errors,
+        selection: input.selection,
+        sessionId: input.sessionId,
+        outcome: input.outcome
+    }, acc.errors.length > 0 ? [acc.errors.length + ' failed'] : [], buildFinalizeHints(acc, input.selection)), input.asJson);
+}

package/dist/cli/commands/finalize-selection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/**
+ * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
+ * The record's own `createdAt` is carried as the recency key — NOT the file's
+ * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
+ * newer than the `queued` one that superseded it. Keeping the key on the
+ * candidate makes the selection rule a pure function of the records and
+ * testable without a filesystem.
+ */
+export interface FinalizeCandidate {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly status: string;
+    readonly createdAt: string;
+}
+/**
+ * What `--request-id` actually did, reported in the envelope. N3: the branch
+ * used to resolve silently and could not say WHY a record was or was not the
+ * one finalized.
+ */
+export interface FinalizeSelection {
+    readonly requestId: string;
+    readonly rule: string;
+    readonly matched: number;
+    readonly chosen: string | null;
+    readonly rejected: readonly {
+        readonly recordPath: string;
+        readonly status: string;
+        readonly reason: string;
+    }[];
+}
+/** The one selection rule `--request-id` and `--batch` now share. */
+export declare const FINALIZE_SELECTION_RULE: string;
+/** The options `peaks sub-agent finalize` accepts. */
+export interface FinalizeOptions {
+    batch?: string;
+    requestId?: string;
+    outcome?: string;
+    error?: string;
+    allStale?: boolean;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;

package/dist/cli/commands/finalize-selection.js

@@ -0,0 +1,35 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter((candidate) => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}

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

@@ -4,6 +4,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { emitHint } from '../../services/hooks/output.js';
 import { parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
 import { classifyTool, emitAllowSkipped, emitAllowWorktree, emitSopAllow, emitSopDeny, emitSopWarnings, handleWorktreeGate, parseHookStdin, resolveToolMatcher } from './gate-commands-enforce.js';
+import { handleMcpSurfaceGate } from '../../services/hooks/mcp-surface-gate.js';
 export function registerGateCommands(program, io) {
     const gate = program
         .command('gate')
@@ -53,6 +54,19 @@ function exitWhenRealCliHook() {
         process.exit(process.exitCode || 0);
     }
 }
+/** Read the payload's surface out of the tool name, the adapter's matcher and the command. */
+function classifySurface(parsedStdin) {
+    const toolMatcher = resolveToolMatcher(parsedStdin);
+    const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+    const toolKind = classifyTool(toolName);
+    const isBash = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
+    return {
+        toolKind,
+        command,
+        bashCommand: isBash ? command : null,
+        isWorktreeToolSurface: toolKind === 'Agent' || toolKind === 'EnterWorktree'
+    };
+}
 /**
  * Body of the `gate enforce` PreToolUse handler. The worktree-then-SOP ordering and every early
  * return / exit-code path are documented on the helpers this delegates to in `gate-commands-enforce`.
@@ -63,23 +77,27 @@ async function runGateEnforceAction(io, options) {
     try {
         const raw = await readHookPayload();
         const parsedStdin = parseHookStdin(raw);
-        const toolMatcher = resolveToolMatcher(parsedStdin);
-        const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
-        const toolKind = classifyTool(toolName);
-        const isBashSurface = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
-        const isWorktreeToolSurface = toolKind === 'Agent' || toolKind === 'EnterWorktree';
-        if (!isBashSurface && !isWorktreeToolSurface) {
+        // The MCP branch runs FIRST and is fail-CLOSED, so it must not sit behind
+        // the "not a guarded surface" early return below — an MCP tool name matches
+        // neither the Bash matcher nor a worktree tool, so everything after this
+        // point would wave it through. A block here has already been emitted.
+        if (handleMcpSurfaceGate(io, parsedStdin)) {
+            return;
+        }
+        const surface = classifySurface(parsedStdin);
+        const { toolKind, command } = surface;
+        if (surface.bashCommand === null && !surface.isWorktreeToolSurface) {
             emitAllowSkipped(io, options);
             return;
         }
         if (handleWorktreeGate(io, options, toolKind, { command, parsedStdin })) {
             return;
         }
-        if (!isBashSurface) {
+        if (surface.bashCommand === null) {
             emitAllowWorktree(io, options);
             return;
         }
-        const decision = await enforceBashCommand(options.project, command);
+        const decision = await enforceBashCommand(options.project, surface.bashCommand);
         if (decision.decision === 'deny') {
             emitSopDeny(io, options, decision);
             return;

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

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

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)
+    };
+}