peaks-loop 4.1.2 → 4.1.4

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/loop-command-shared.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+export type GoalComposeOptions = {
+    project: string;
+    goal: string;
+    json?: boolean;
+};
+export type LoopDistillOptions = {
+    project: string;
+    apply: boolean;
+    json?: boolean;
+};
+export type LoopPlaceholderOptions = {
+    project: string;
+    json?: boolean;
+};
+export type LoopExportOptions = {
+    loop: string;
+    out: string;
+    project?: string;
+    json?: boolean;
+};
+export type LoopImportOptions = {
+    in: string;
+    as?: string;
+    project?: string;
+    json?: boolean;
+};
+/** `--project`, else the nearest project root above cwd, else cwd. */
+export declare function resolveLoopProjectRoot(project: string | undefined): string;
+/** `--project` + `--json`, the option chain `loop export` and `loop import` share. */
+export declare const LOOP_EXPORT_IMPORT_OPTS: (cmd: Command) => Command;

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

@@ -0,0 +1,15 @@
+// src/cli/commands/loop-command-shared.ts
+//
+// What the `peaks loop` verbs share: the option types, the `--project` /
+// `--json` chain `export` and `import` both declare, and the project-root
+// resolution. Split out of `loop-commands.ts` so the bundle verbs can live in
+// their own modules without repeating the same eight-line construction.
+import { findProjectRoot } from '../../services/config/config-safety.js';
+/** `--project`, else the nearest project root above cwd, else cwd. */
+export function resolveLoopProjectRoot(project) {
+    return project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+}
+/** `--project` + `--json`, the option chain `loop export` and `loop import` share. */
+export const LOOP_EXPORT_IMPORT_OPTS = (cmd) => cmd
+    .option('--project <path>', 'target project root (defaults to cwd)')
+    .option('--json', 'print machine-readable JSON envelope');

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

@@ -1,26 +1,21 @@
 /**
  * peaks loop * CLI (Slice #14 + M7 add).
  *
- * Slices:
  *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
- *     detect-pattern / check-consistency / peaks goal compose.
+ *     detect-pattern / check-consistency, plus `peaks goal compose`.
  *
- *   M7 (2026-07-07 spec §7A.2):
- *     peaks loop export --loop <id> --out <path.tar.gz>
- *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
+ *   M7 (2026-07-07 spec §7A.2): `peaks loop export --loop <id> --out <p.tar.gz>`
+ *     and `peaks loop import --in <p.tar.gz> [--as <loop-id>]`. `export` reads
+ *     the loop_release + relations + bees + evidence briefs and hard-blocks on
+ *     `shareable=false`; `import` validates `format_version_major=1` and lands
+ *     the release as `candidate` (spec §7A.2) — the receiver must run an
+ *     independent evaluation before promoting to `stable`. M7 only ADDs these
+ *     two verbs; the existing 14.x surface is not modified.
  *
- * `peaks loop export` reads the source loop_release + relations +
- * related bees + evidence briefs and emits a `peaks.bundle/1`
- * tar.gz. Hard-blocks when the source has `shareable=false`.
- *
- * `peaks loop import` extracts a bundle, validates
- * format_version_major=1, and lands the release as `candidate`
- * (mandatory landing status per spec §7A.2). The receiver must run
- * an independent evaluation before promoting to `stable`.
- *
- * The existing 14.x commands are kept under the same `loop` parent;
- * M7 only ADDs export / import — it does not modify the existing
- * surface.
+ * This module owns the `loop` parent, the registrar order, and `distill` — the
+ * one verb that spawns a child process, kept here so the `node:child_process`
+ * import stays on the module `tests/unit/spawn-windows-hide-guard.test.ts`
+ * pins it to. Every other verb lives beside this file, one module per verb.
  */
 import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';