peaks-loop 4.1.3 → 4.1.4

package/dist/cli/commands/codegraph-status-integrity.js

@@ -0,0 +1,121 @@
+// src/cli/commands/codegraph-status-integrity.ts
+//
+// The two integrity axes `peaks codegraph status` evaluates, and the human
+// reading of them. Split out of `codegraph-status-command.ts`; every
+// applicability predicate, degradation rule and printed line is unchanged.
+import { inspectCodegraphExcludeIntegrity, isCodegraphExcludeConfigPresent, renderCodegraphExcludeIntegrityLines } from '../../services/codegraph/codegraph-exclude-integrity.js';
+import { inspectCodegraphIndexIntegrity, isCodegraphIndexStrictMode, renderCodegraphIndexIntegrityLines, resolveCodegraphIndexIntegrityVerdict } from '../../services/codegraph/codegraph-index-integrity.js';
+import { isCodegraphInitialized } from '../../services/codegraph/codegraph-service.js';
+import { readCodegraphProjectInputs } from '../../services/codegraph/codegraph-exclude-reconciler.js';
+import { getErrorMessage } from '../cli-helpers.js';
+/**
+ * Read both axes for a project root.
+ *
+ * R12-1: the two axes have DIFFERENT applicability predicates, and folding
+ * them into the config's alone is how a db-present / config-absent project
+ * came to exit 0 in SILENCE — under `PEAKS_CODEGRAPH_INDEX_STRICT=1` too.
+ * "Could not evaluate" is a verdict; it may not be spelled the same way as
+ * "verified clean" merely because the read happened to be gated out.
+ *
+ *   - exclude axis: applicable iff `.codegraph/config.json` exists. The
+ *     config IS the subject of that axis, so with no config there is no
+ *     exclusion list in play — `not-applicable`, silent, as before.
+ *   - index axis: applicable iff `.codegraph/codegraph.db` exists — the
+ *     SAME predicate the doctor's `defaultProbe` uses
+ *     (`isCodegraphInitialized` in
+ *     `doctor-service/checks/codegraph-index-integrity.ts`), so the two
+ *     consumers now agree about when the axis is evaluable at all. The
+ *     index is the subject here and the config is only an INPUT it reads,
+ *     so a missing config is "could not evaluate" (exit 76, `[FAIL]`),
+ *     not "nothing to evaluate".
+ *
+ * The user's constraint holds either way: an absent config is LEGITIMATE
+ * for a project that never ran `peaks codegraph init` — with no db BOTH
+ * predicates are false and the command stays silent exactly as before.
+ *
+ * The two axes are evaluated INDEPENDENTLY: an unreadable index must not
+ * blind the exclude verdict, and a malformed exclude list must not hide a
+ * stale index. Each failure degrades to its own warning.
+ */
+export function readStatusAxes(projectRoot) {
+    let integrity = null;
+    let integrityWarning = null;
+    let indexIntegrity = null;
+    let indexIntegrityWarning = null;
+    const configPresent = isCodegraphExcludeConfigPresent(projectRoot);
+    const indexPresent = isCodegraphInitialized(projectRoot);
+    if (configPresent || indexPresent) {
+        // Perf audit F1: both axes need the SAME tracked-file list and the SAME
+        // config, and reading them per-axis spawned `git ls-files` twice per
+        // command and re-ran the identical 32-glob `include` filter. Read once
+        // and hand the values to both inspectors through their deps seam.
+        let sharedInputs = null;
+        try {
+            sharedInputs = readCodegraphProjectInputs(projectRoot);
+        }
+        catch (error) {
+            // One read, two blind axes — they consume exactly these two inputs,
+            // so a failure here blinds both. Report it on both, rather than
+            // letting the second axis re-run the same failing read to find out.
+            // Each axis claims the failure only where it was applicable at all:
+            // an unreadable CONFIG is not an exclude-axis finding on a project
+            // that has no config by design.
+            if (configPresent)
+                integrityWarning = getErrorMessage(error);
+            if (indexPresent)
+                indexIntegrityWarning = getErrorMessage(error);
+        }
+        if (sharedInputs !== null) {
+            if (configPresent) {
+                try {
+                    integrity = inspectCodegraphExcludeIntegrity(projectRoot, sharedInputs);
+                }
+                catch (error) {
+                    integrityWarning = getErrorMessage(error);
+                }
+            }
+            // The index axis needs an index. A config without `codegraph.db` is a
+            // pre-init / dangling state, not a defect: there are no rows to be
+            // stale and nothing `include` withheld from a graph that does not exist.
+            if (indexPresent) {
+                try {
+                    indexIntegrity = inspectCodegraphIndexIntegrity(projectRoot, sharedInputs);
+                }
+                catch (error) {
+                    indexIntegrityWarning = getErrorMessage(error);
+                }
+            }
+        }
+    }
+    return {
+        integrity,
+        integrityWarning,
+        indexIntegrity,
+        indexIntegrityWarning,
+        indexVerdict: resolveCodegraphIndexIntegrityVerdict(indexIntegrity, indexIntegrityWarning),
+        strict: isCodegraphIndexStrictMode()
+    };
+}
+/** The human-readable axis report, printed only by the non-JSON branch. */
+export function emitIntegrityText(io, axes) {
+    if (axes.integrityWarning !== null) {
+        io.stdout(`[WARN] codegraph exclude integrity not evaluated: ${axes.integrityWarning}`);
+    }
+    else if (axes.integrity !== null) {
+        for (const line of renderCodegraphExcludeIntegrityLines(axes.integrity)) {
+            io.stdout(line);
+        }
+    }
+    if (axes.indexVerdict === 'not-evaluated') {
+        // `[FAIL]`, in every mode, because the command exits non-zero in
+        // every mode: the axis was attempted and failed, so this is not a
+        // statement about the index. Distinct wording from the gap line so
+        // the two can never be confused.
+        io.stdout(`[FAIL] codegraph index integrity could not be evaluated (the index was NOT measured): ${axes.indexIntegrityWarning ?? 'unknown cause'}`);
+    }
+    else if (axes.indexIntegrity !== null) {
+        for (const line of renderCodegraphIndexIntegrityLines(axes.indexIntegrity, axes.strict)) {
+            io.stdout(line);
+        }
+    }
+}

package/dist/cli/commands/codegraph-status-json.d.ts

@@ -0,0 +1,5 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type CommonCodegraphOptions } from './codegraph-command-runtime.js';
+import type { CodegraphStatusAxes } from './codegraph-status-integrity.js';
+/** Returns true when upstream failed (the caller must stop before the gates). */
+export declare function runCodegraphStatusJson(io: ProgramIO, options: CommonCodegraphOptions, axes: CodegraphStatusAxes): Promise<boolean>;

package/dist/cli/commands/codegraph-status-json.js

@@ -0,0 +1,127 @@
+// src/cli/commands/codegraph-status-json.ts
+//
+// The `--peaks-json` machine report for `peaks codegraph status`. Split out of
+// `codegraph-status-command.ts`; every envelope code, message, `data` field,
+// next-action string and exit-code rule is unchanged.
+//
+// EXIT-CODE PRECEDENCE (decided here, mirrored on the human path, pinned
+// by tests on BOTH axes):
+//
+//   1. upstream failed      → upstream's exit code. Ranked FIRST because
+//      every gate's remedy assumes upstream can run, and because the
+//      gate's own branches would otherwise MASK a real command failure:
+//      under the advisory default a gap exits 0, so a "gate first" order
+//      would turn "upstream failed + gap" into exit 0 — the gate hiding a
+//      failure. The gate verdicts stay in `data` verbatim, so ranking
+//      them lower hides nothing.
+//   2. exclude gap          → 74 (`CODEGRAPH_INDEX_INCOMPLETE`).
+//   3. index not evaluated  → 76 (`CODEGRAPH_INDEX_NOT_EVALUATED`): the
+//      axis was attempted and failed, which is NOT "verified clean".
+//   4. index gap            → 75 (`CODEGRAPH_INDEX_GAP`) in strict mode,
+//      0 in the advisory default.
+//
+// The envelope still reports the finding in case 4 (`ok:false`, the same
+// `code`, plus `indexIntegritySeverity: 'warning'`) — the policy governs
+// the EXIT CODE, not whether the finding is visible. This mirrors the
+// doctor's established convention: `ok:false` + `severity:'warning'`
+// surfaces the finding without escalating the exit code.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE, CODEGRAPH_INDEX_STRICT_ENV_VAR, CODEGRAPH_REPAIR_INDEX_COMMAND } from '../../services/codegraph/codegraph-index-integrity.js';
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
+import { printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+import { localizeUpstreamCodegraphText, printCodegraphFailure } from './codegraph-command-runtime.js';
+/**
+ * `--peaks-json` machine report for `status`. Carries the upstream
+ * result AND the peaks-loop integrity verdict as one JSON document so a
+ * CI job can gate on `data.integrity.gap` / `data.integrity.rulesToRemove`
+ * without scraping human text.
+ */
+function buildStatusReport(result, axes) {
+    const upstream = {
+        exitCode: result.exitCode,
+        stdout: localizeUpstreamCodegraphText(result.stdout).trimEnd(),
+        stderr: redactSensitiveErrorMessage(localizeUpstreamCodegraphText(result.stderr)).trimEnd()
+    };
+    return {
+        upstream,
+        data: {
+            upstream,
+            integrity: axes.integrity,
+            integrityWarning: axes.integrityWarning,
+            indexIntegrity: axes.indexIntegrity,
+            indexIntegrityWarning: axes.indexIntegrityWarning,
+            indexIntegrityVerdict: axes.indexVerdict,
+            // Only meaningful where there IS a finding: a `clean` or `not-applicable`
+            // axis has no severity, and reporting `'warning'` there would read as
+            // "something was wrong but advisory".
+            indexIntegritySeverity: axes.indexVerdict === 'gap' ? (axes.strict ? 'error' : 'warning') : null
+        }
+    };
+}
+/** The refusal an index gap produces, in strict or advisory wording. */
+function indexGapVerdict(axes) {
+    const includeGap = axes.indexIntegrity?.includeGap.length ?? 0;
+    const deadRows = axes.indexIntegrity?.deadRows.length ?? 0;
+    return {
+        message: `codegraph index does not cover the repository: ${includeGap} extractor-supported tracked file(s) are not admitted by the config's include globs, and ${deadRows} index row(s) point at files that no longer exist.`,
+        nextActions: axes.strict
+            ? [
+                'The index must admit every extractor-supported tracked file and hold no row for a path that is gone.',
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
+            ]
+            : [
+                'Advisory: this gap is reported as a warning and the command exits 0.',
+                `Set ${CODEGRAPH_INDEX_STRICT_ENV_VAR}=1 to make it blocking (exit ${CODEGRAPH_INDEX_INTEGRITY_EXIT_CODE}).`,
+                `Run \`${CODEGRAPH_REPAIR_INDEX_COMMAND}\` to drop the blocking exclude rules and rebuild the index without the stale rows.`
+            ]
+    };
+}
+/** Upstream failed: its exit code outranks both gates, so it is ranked first. */
+function emitUpstreamFailure(io, result, report) {
+    const { stdout, stderr } = report.upstream;
+    printResult(io, fail('codegraph.status', 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(stderr || stdout || `codegraph exited with code ${String(result.exitCode)}`), report.data, ['Check the codegraph project path before retrying']), true);
+}
+/** The gate verdicts, in precedence order, when upstream itself succeeded. */
+function emitGateVerdict(io, axes, data) {
+    const integrity = axes.integrity;
+    if (integrity?.gap === true) {
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_INCOMPLETE', `codegraph index is incomplete: ${integrity.excludedTrackedCount} of ${integrity.trackedSourceCount} tracked source files are excluded by ${integrity.rulesToRemove.length} rule(s).`, data, [
+            'Run `peaks codegraph repair-exclude --project <root>` to drop the offending rules and rebuild the index.'
+        ]), true);
+        return;
+    }
+    if (axes.indexVerdict === 'not-evaluated') {
+        // Distinct from the `ok` branch below on purpose: this axis produced
+        // NO verdict, and the envelope must not read as "index verified".
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_NOT_EVALUATED', `codegraph index integrity could not be evaluated: ${axes.indexIntegrityWarning ?? 'unknown cause'}`, data, [
+            'The index was NOT measured — this is not a statement that the index is correct.',
+            'Re-run once the cause above is resolved.'
+        ]), true);
+        return;
+    }
+    if (axes.indexVerdict === 'gap') {
+        const verdict = indexGapVerdict(axes);
+        printResult(io, fail('codegraph.status', 'CODEGRAPH_INDEX_GAP', verdict.message, data, verdict.nextActions), true);
+        return;
+    }
+    printResult(io, ok('codegraph.status', data), true);
+}
+/** Returns true when upstream failed (the caller must stop before the gates). */
+export async function runCodegraphStatusJson(io, options, axes) {
+    let result;
+    try {
+        result = await executeCodegraphInvocation(createCodegraphInvocation({ subcommand: 'status', project: options.project }));
+    }
+    catch (error) {
+        printCodegraphFailure(io, 'codegraph.status', error, true);
+        return true;
+    }
+    const report = buildStatusReport(result, axes);
+    if (result.exitCode !== null && result.exitCode !== 0) {
+        emitUpstreamFailure(io, result, report);
+        process.exitCode = result.exitCode ?? 1;
+        return true;
+    }
+    emitGateVerdict(io, axes, report.data);
+    return false;
+}

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

@@ -0,0 +1,60 @@
+export declare const DEFAULT_DOCKER_IMAGE = "node:22-slim";
+/**
+ * runtime adapter. The container CLI supports both docker and
+ * podman as the underlying runtime. The auto-detect order is:
+ *   1. `--runtime docker|podman` if explicit
+ *   2. docker (most common, ships with Docker Desktop on
+ *      macOS/Windows, docker.io on Linux)
+ *   3. podman (RHEL/Fedora default, runs rootless by default,
+ *      same CLI surface as docker)
+ * Each runtime has the same spawn/release shape; the
+ * difference is the binary name (`docker` vs `podman`). The
+ * `--cidfile` flag is supported by both.
+ */
+export type ContainerRuntime = 'docker' | 'podman';
+/** A runtime that answered `--version`, or the reason none did. */
+export type ContainerRuntimeProbe = {
+    ok: true;
+    runtime: ContainerRuntime;
+    binary: string;
+} | {
+    ok: false;
+    stderr: string;
+    hint: string;
+};
+export declare function detectContainerRuntime(explicit: ContainerRuntime | undefined): ContainerRuntimeProbe;
+export type ContainerOptions = {
+    session?: string;
+    project?: string;
+    json?: boolean;
+};
+export type SpawnOptions = ContainerOptions & {
+    rid: string;
+    role: string;
+    purpose: string;
+    image?: string;
+    ttl?: string;
+    mount?: string;
+    /** Part 43: explicit runtime selector (docker | podman). */
+    runtime?: string;
+};
+export type ReleaseOptions = ContainerOptions & {
+    leaseId: string;
+};
+export declare function joinPathSession(projectRoot: string, sessionId: string): string;
+/**
+ * Resolve the project root and session id every container verb works against.
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel.
+ */
+export declare function resolveContainerTarget(options: ContainerOptions): {
+    projectRoot: string;
+    sessionId: string;
+};
+export declare function checkDockerAvailable(): {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    stderr: string;
+};

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

@@ -0,0 +1,52 @@
+import { execSync } from 'node:child_process';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+export const DEFAULT_DOCKER_IMAGE = 'node:22-slim';
+export function detectContainerRuntime(explicit) {
+    const tryOrder = explicit ? [explicit] : ['docker', 'podman'];
+    for (const r of tryOrder) {
+        try {
+            const version = execSync(`${r} --version`, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                encoding: 'utf8',
+                windowsHide: true
+            }).trim();
+            return { ok: true, runtime: r, binary: `${r} (${version.split('\n')[0] ?? ''})` };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return {
+        ok: false,
+        stderr: explicit
+            ? `explicit --runtime ${explicit} not on PATH`
+            : 'neither docker nor podman is on PATH',
+        hint: explicit
+            ? `Install ${explicit} or pass a different --runtime.`
+            : 'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).'
+    };
+}
+export function joinPathSession(projectRoot, sessionId) {
+    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
+}
+/**
+ * Resolve the project root and session id every container verb works against.
+ * The sid falls back through `PEAKS_SESSION_ID` and the canonical binding
+ * before the `unknown-sid` sentinel.
+ */
+export function resolveContainerTarget(options) {
+    const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const sessionId = options.session ??
+        process.env.PEAKS_SESSION_ID ??
+        getCurrentSessionId(projectRoot) ??
+        'unknown-sid';
+    return { projectRoot, sessionId };
+}
+export function checkDockerAvailable() {
+    // Part 43: superseded by detectContainerRuntime above; this
+    // function is preserved for callers that imported it. The
+    // container-commands.ts action handlers all use
+    // detectContainerRuntime directly.
+    return { ok: false, stderr: 'deprecated — use detectContainerRuntime' };
+}

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

@@ -23,5 +23,5 @@
  * follow-up rid.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerContainerCommand(program: Command, io: ProgramIO): void;

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

@@ -22,224 +22,12 @@
  * allowing docker-related tool calls. The gate bridge is a
  * follow-up rid.
  */
-import { execSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, printResult } from '../cli-helpers.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
-import { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
-import { normalizePath } from '../../shared/path-utils.js';
-import { containerLeaseFilePath, deserializeContainerLease, finalizeContainerLease, generateContainerLeaseId, markContainerReleased, ttlForContainerRole } from '../../services/container/container-lease.js';
-const DEFAULT_DOCKER_IMAGE = 'node:22-slim';
-function detectContainerRuntime(explicit) {
-    const tryOrder = explicit ? [explicit] : ['docker', 'podman'];
-    for (const r of tryOrder) {
-        try {
-            const version = execSync(`${r} --version`, {
-                stdio: ['ignore', 'pipe', 'pipe'],
-                encoding: 'utf8',
-                windowsHide: true
-            }).trim();
-            return { ok: true, runtime: r, binary: `${r} (${version.split('\n')[0] ?? ''})` };
-        }
-        catch {
-            /* try next */
-        }
-    }
-    return {
-        ok: false,
-        stderr: explicit
-            ? `explicit --runtime ${explicit} not on PATH`
-            : 'neither docker nor podman is on PATH',
-        hint: explicit
-            ? `Install ${explicit} or pass a different --runtime.`
-            : 'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).'
-    };
-}
-function joinPathSession(projectRoot, sessionId) {
-    return `${projectRoot.replace(/[\\/]+$/, '')}/.peaks/_runtime/${sessionId}`;
-}
-function checkDockerAvailable() {
-    // Part 43: superseded by detectContainerRuntime above; this
-    // function is preserved for callers that imported it. The
-    // container-commands.ts action handlers all use
-    // detectContainerRuntime directly.
-    return { ok: false, stderr: 'deprecated — use detectContainerRuntime' };
-}
+import { registerContainerReleaseCommand } from './container-release-command.js';
+import { registerContainerSpawnCommand } from './container-spawn-command.js';
 export function registerContainerCommand(program, io) {
     const cmd = program
         .command('container')
         .description('L4 container isolation: spawn/release container leases (Part 12; pairs with --isolation container on dispatch).');
-    addJsonOption(cmd
-        .command('spawn')
-        .description('Spawn a container via `docker run` and write a container lease. ' +
-        'The lease is the source of truth for the L4 PreToolUse gate (Part 12 follow-up). ' +
-        'Default TTL is role-aware (rd=30m / qa=15m / ui=1h); pass --ttl <ms> to override. ' +
-        'Default image is `node:22-slim`; pass --image <name> to override.')
-        .requiredOption('--rid <rid>', 'peaks request id the lease is associated with')
-        .requiredOption('--role <role>', 'sub-agent role (rd | qa | ui | sc | prd | general-purpose)')
-        .requiredOption('--purpose <text>', 'why this container was spawned (audit log)')
-        .option('--image <name>', `container image (default ${DEFAULT_DOCKER_IMAGE})`)
-        .option('--ttl <ms>', 'time-to-live in ms (default role-aware; override with positive number)')
-        .option('--mount <path>', 'host path to mount as the container working dir (default: <projectRoot>)')
-        .option('--session <sid>', 'override session id')
-        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
-        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const sessionId = options.session ??
-            process.env.PEAKS_SESSION_ID ??
-            getCurrentSessionId(projectRoot) ??
-            'unknown-sid';
-        try {
-            const explicitRuntime = (() => {
-                if (options.runtime === 'docker')
-                    return 'docker';
-                if (options.runtime === 'podman')
-                    return 'podman';
-                return undefined;
-            })();
-            const runtime = detectContainerRuntime(explicitRuntime);
-            if (!runtime.ok) {
-                printResult(io, fail('container.spawn', 'CONTAINER_RUNTIME_UNAVAILABLE', `${runtime.stderr}: ${runtime.hint}`, { rid: options.rid, role: options.role, sessionId }, [
-                    'Install docker (Docker Desktop on macOS / Windows) or podman (RHEL / Fedora).',
-                    'On Windows, ensure WSL2 backend is enabled and the daemon is running.',
-                    'Pass --runtime docker|podman to force a specific runtime.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const leaseId = generateContainerLeaseId();
-            const now = Date.now();
-            const ttlMs = options.ttl === undefined
-                ? ttlForContainerRole(options.role)
-                : Number.parseInt(options.ttl, 10);
-            if (!Number.isInteger(ttlMs) || ttlMs <= 0) {
-                printResult(io, fail('container.spawn', 'INVALID_TTL', '--ttl must be a positive integer (ms)', { ttl: options.ttl }, ['Re-run with --ttl 1800000 (30 min) or omit to use role default.']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const image = options.image ?? DEFAULT_DOCKER_IMAGE;
-            const mount = options.mount ?? projectRoot;
-            // `docker run --rm -d` so the container is detached and
-            // auto-removed when stopped; --cidfile writes the
-            // container id to a file we can read back. The
-            // `--label peaks.leaseId=<id>` lets `peaks container
-            // list` / `peaks container gc` find orphans by label
-            // when the lease file is missing.
-            const cidFile = `${normalizePath(joinPathSession(projectRoot, sessionId))}/.${runtime.runtime}-cid-${leaseId}`;
-            try {
-                execSync(`${runtime.runtime} run --rm -d --cidfile "${cidFile}" --label "peaks.leaseId=${leaseId}" --label "peaks.rid=${options.rid}" -v "${mount}:/work" -w /work ${image} sleep infinity`, { cwd: projectRoot, stdio: 'pipe', encoding: 'utf8', windowsHide: true });
-            }
-            catch (err) {
-                printResult(io, fail('container.spawn', 'DOCKER_RUN_FAILED', getErrorMessage(err), { rid: options.rid, image, runtime: runtime.runtime, sessionId }, [
-                    'Verify the image name is reachable on the configured registry.',
-                    'Verify the host path is mounted correctly (Windows: the path must be visible to WSL2).',
-                    `Run \`${runtime.runtime} ps -a\` to inspect any leftover containers with the peaks.leaseId label.`
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            const containerId = readFileSync(cidFile, 'utf8').trim();
-            const lease = finalizeContainerLease({
-                leaseId,
-                rid: options.rid,
-                role: options.role,
-                path: mount,
-                image,
-                containerId,
-                createdAt: now,
-                expiresAt: now + ttlMs,
-                purpose: options.purpose
-            });
-            atomicWriteJson(containerLeaseFilePath(joinPathSession(projectRoot, sessionId), leaseId), lease);
-            printResult(io, ok('container.spawn', {
-                lease,
-                sessionId,
-                projectRoot,
-                runtime: runtime.runtime,
-                runtimeVersion: runtime.binary,
-                nextActions: [
-                    `Container id: ${containerId}`,
-                    `Image: ${image}`,
-                    `Lease expires at: ${new Date(lease.expiresAt).toISOString()}`,
-                    'Run `peaks container release --lease-id <id>` when done'
-                ]
-            }, [], []), options.json);
-        }
-        catch (err) {
-            printResult(io, fail('container.spawn', 'SPAWN_FAILED', getErrorMessage(err), { rid: options.rid, sessionId }, [
-                'See error message; if the lease was not written, retry after fixing the underlying issue.'
-            ]), options.json);
-            process.exitCode = 1;
-        }
-    });
-    addJsonOption(cmd
-        .command('release')
-        .description('Transition a container lease to released and run `docker rm --force`. Idempotent on already-released leases.')
-        .requiredOption('--lease-id <id>', 'lease id returned by `peaks container spawn`')
-        .option('--session <sid>', 'override session id')
-        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
-        const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const sessionId = options.session ??
-            process.env.PEAKS_SESSION_ID ??
-            getCurrentSessionId(projectRoot) ??
-            'unknown-sid';
-        try {
-            const file = containerLeaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
-            if (!existsSync(file)) {
-                printResult(io, fail('container.release', 'LEASE_NOT_FOUND', `no lease on disk at ${file}`, { leaseId: options.leaseId, file }, [
-                    'Run `peaks container list` to inspect active leases.',
-                    'For a never-spawned lease, this is a no-op — no further action needed.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            let lease;
-            try {
-                lease = deserializeContainerLease(readFileSync(file, 'utf8'));
-            }
-            catch (err) {
-                printResult(io, fail('container.release', 'LEASE_FILE_INVALID', getErrorMessage(err), { leaseId: options.leaseId, file }, [
-                    'Delete the malformed lease file manually and re-issue spawn.',
-                    'For security, release never fails open on a malformed lease.'
-                ]), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (lease.status === 'released') {
-                printResult(io, ok('container.release', { lease, sessionId, projectRoot, alreadyReleased: true }, [], [`Lease ${lease.leaseId} already released; nothing to do.`]), options.json);
-                return;
-            }
-            let dockerRmFailed = false;
-            try {
-                const releaseRuntime = detectContainerRuntime(undefined);
-                const runtimeCmd = releaseRuntime.ok ? releaseRuntime.runtime : 'docker';
-                execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, {
-                    cwd: projectRoot,
-                    stdio: 'pipe',
-                    encoding: 'utf8',
-                    windowsHide: true
-                });
-            }
-            catch {
-                dockerRmFailed = true;
-            }
-            const released = markContainerReleased(lease);
-            atomicWriteJson(file, released);
-            printResult(io, ok('container.release', { lease: released, sessionId, projectRoot, dockerRmFailed }, dockerRmFailed
-                ? [
-                    'docker rm failed (likely the container was already removed); lease marked released.'
-                ]
-                : [], [
-                `Lease ${lease.leaseId} marked released.`,
-                dockerRmFailed
-                    ? 'Manual `docker ps -a` + `docker rm` may be needed.'
-                    : `Container ${lease.containerId} removed.`
-            ]), options.json);
-        }
-        catch (err) {
-            printResult(io, fail('container.release', 'RELEASE_FAILED', getErrorMessage(err), { leaseId: options.leaseId, sessionId }, ['Verify the lease id and re-run.', 'If the lease was never spawned, no-op.']), options.json);
-            process.exitCode = 1;
-        }
-    });
+    registerContainerSpawnCommand(cmd, io);
+    registerContainerReleaseCommand(cmd, io);
 }

package/dist/cli/commands/container-release-command.d.ts

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