peaks-loop 4.0.54 → 4.1.0

package/dist/cli/commands/job-add-slice-command.js

@@ -0,0 +1,151 @@
+/**
+ * rid 2026-10-03-job-ledger-truthfulness (D1) — `peaks job add-slice`.
+ *
+ * THE DEFECT. A job's slice list was decided once, at
+ * `peaks job init --slice-list <one id>`, and no subcommand could add to it. The
+ * subcommand set was `init / status / rotate-now / subagent-cleanup / checkpoint /
+ * block / continue / resume / progress / handoff / karpathy-cost-check`. Measured
+ * against the committed build on 2026-10-03:
+ *
+ *   peaks job add-slice …                          → error: unknown command 'add-slice'
+ *   peaks job checkpoint --slice-id <new slice>    → ok:false  code:SLICE_NOT_FOUND
+ *   peaks job progress --job-id 2026-10-02-c-wave9 → { done: 1, total: 1 }  (stuck)
+ *
+ * so a wave that plans its next slice only after the previous one lands — which is
+ * how every split wave here runs — had no truthful way to record what it did. It
+ * either under-reported or opened a new job per slice, and the ledger then recorded
+ * the tooling's limitation instead of the work.
+ *
+ * WHY THIS IS ITS OWN FILE. `src/cli/commands/job-commands.ts` sits over the
+ * 300-line cap the gate already ratchets (828 raw lines, and the repository's
+ * `fileSizeExcessLines` row is held at its ceiling in both directions), so this
+ * slice could not add a subcommand there without moving a gate number — the frozen
+ * work. The command mounts onto the existing `job` parent from here, the way
+ * `api-diff-commands.ts` mounts `peaks scan api-diff`, and reuses the parent
+ * file's session/state resolution rather than re-implementing it. NOTHING about
+ * the `job` command's stored shape changed: same state file, same `slice-NNN` ids,
+ * same `progress.json` mirror, same envelope, no new ledger field.
+ *
+ * WHAT IT PROMISES, and each half is load-bearing:
+ * - **idempotent** — a label already registered on this job is reported as the
+ *   slice it already is (`added: false`) and `state.json` is not written.
+ *   Re-running the command cannot grow the job.
+ * - **honest** — an empty or whitespace-only label is refused
+ *   (`INVALID_SLICE_LABEL`) rather than appended; the mirror is rewritten only when
+ *   a slice was actually added, and only if a mirror already exists (a command that
+ *   knows nothing about progress does not invent one).
+ * - **followed by the rest of the ledger** — every `total` is `slices.length`, so
+ *   `status`, `progress`, `continue` and the mirror move together, and `checkpoint`
+ *   takes the new slice by name through the existing D7 label resolution.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { tryReadJobProgress, writeJobProgress } from '../../services/job/job-progress-store.js';
+import { SESSION_ID_HELP, asJson, resolveJobStateRoot } from './job-commands.js';
+/**
+ * Report a failed envelope AND exit non-zero — the F1 rule every failure site in
+ * `job-commands.ts` goes through.
+ *
+ * Repeated here rather than imported for one mechanical reason: exporting
+ * `job-commands.ts`'s `failResult` lengthens its signature past the line width, so
+ * prettier reflows it onto five lines, and that file is already over the 300-line
+ * cap. A slice that must move no gate number cannot spend four lines there. The
+ * behaviour is the same two statements: `printResult(...)` then
+ * `process.exitCode = 1`.
+ */
+function refuse(io, result, opts) {
+    printResult(io, result, asJson(opts));
+    process.exitCode = 1;
+}
+/** An empty or whitespace-only label never reaches the ledger. */
+function refuseEmptyLabel(io, opts) {
+    refuse(io, fail('add-slice', 'INVALID_SLICE_LABEL', `--slice-label must name one slice; got ${JSON.stringify(opts.sliceLabel)} (empty after trimming)`, { jobId: opts.jobId }, ['Re-run with --slice-label <label>, one slice label per call']), opts);
+}
+/**
+ * Re-mirror the progress file so `total` follows the ledger the hooks read.
+ *
+ * Only when a mirror already exists: `done` and `lastCommitSha` are taken from the
+ * mirror that is being updated, and this command has no checkpoint to base a
+ * `done` count on for a job that has never been checkpointed. Returns whether a
+ * mirror was written, which is what the envelope reports as `progressMirrored`.
+ */
+function mirrorProgressAfterAdd(projectRoot, sessionId, jobId, orch) {
+    const existing = tryReadJobProgress(projectRoot, sessionId, jobId);
+    if (existing === null)
+        return false;
+    const state = orch.status(jobId);
+    writeJobProgress(projectRoot, sessionId, {
+        jobId,
+        done: state.done,
+        total: state.total,
+        // D3: `undefined` is the honest answer when nothing is pending, and the
+        // store says so in its own words instead of the caller inventing a slice id.
+        currentSlice: state.currentSlice,
+        lastCommitSha: existing.lastCommitSha,
+        updatedAt: new Date().toISOString()
+    });
+    return true;
+}
+/** What the caller is told, and what it can do next. */
+function addSliceEnvelope(opts, outcome, progressMirrored, statePath) {
+    const warnings = outcome.added
+        ? []
+        : [
+            `slice "${outcome.label}" is already registered as ${outcome.sliceId} on job ${opts.jobId}; nothing changed`
+        ];
+    const nextActions = outcome.added
+        ? [
+            `Recorded ${outcome.sliceId} (${outcome.label}); job ${opts.jobId} now has ${outcome.total} slices.`,
+            `Checkpoint it by name: peaks job checkpoint --job-id ${opts.jobId} --slice-id ${outcome.label} --state done --commit-sha <sha>`
+        ]
+        : [
+            `Checkpoint the slice that exists: peaks job checkpoint --job-id ${opts.jobId} --slice-id ${outcome.sliceId} --state done --commit-sha <sha>`
+        ];
+    return ok('add-slice', {
+        jobId: opts.jobId,
+        sliceId: outcome.sliceId,
+        label: outcome.label,
+        added: outcome.added,
+        total: outcome.total,
+        progressMirrored,
+        statePath
+    }, warnings, nextActions);
+}
+function runAddSlice(io, opts) {
+    const label = opts.sliceLabel.trim();
+    if (label.length === 0) {
+        // Refused before the job is opened: a job that does not exist must not be the
+        // reason the caller learns their label was blank.
+        refuseEmptyLabel(io, opts);
+        return;
+    }
+    const jobRoot = resolveJobStateRoot(opts, opts.jobId);
+    const orch = new JobOrchestrator(new JobStateStore(jobRoot.rootDir));
+    const outcome = orch.addSlice({ jobId: opts.jobId, label });
+    const progressMirrored = outcome.added
+        ? mirrorProgressAfterAdd(jobRoot.projectRoot, jobRoot.sessionId, opts.jobId, orch)
+        : false;
+    printResult(io, addSliceEnvelope(opts, outcome, progressMirrored, `${jobRoot.rootDir}/${opts.jobId}/state.json`), asJson(opts));
+}
+export function registerJobAddSliceCommand(program, io) {
+    // Mount on the existing `job` parent. If it is not registered, this command has
+    // no session resolution, no state layout and no `--json` handling to share, so a
+    // second bare `job` group would be the wrong answer — say so loudly instead.
+    const job = program.commands.find((c) => c.name() === 'job');
+    if (job === undefined) {
+        throw new Error('registerJobAddSliceCommand: no `job` command on this program — job-commands must be registered first');
+    }
+    addJsonOption(job
+        .command('add-slice')
+        .description('Register one more slice on an existing job, for a wave planned a slice at a time. ' +
+        'Idempotent: a label the job already carries is reported and changes nothing; an ' +
+        'empty label is refused. Writes the job state file and re-mirrors progress.json ' +
+        'when a mirror already exists, so `total` in status/progress follows the ledger.')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-label <label>', 'the slice this wave has now planned')
+        .option('--session-id <sid>', SESSION_ID_HELP)
+        .option('--project <repo>')
+        .action((opts) => runAddSlice(io, opts)));
+}

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

@@ -1,3 +1,67 @@
 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;
+}
 export declare function registerJobCommands(program: Command, io?: ProgramIO): void;
+export {};