peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/compact-settle-command.js

@@ -0,0 +1,130 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readSessionIdFromHookPayload, readTriggerFromHookPayload, settleCompactFromHarnessEvent } from '../../services/code/compact-event-settle.js';
+import { resolveSessionId } from './compact-shared.js';
+const COMPACT_SETTLE_DESCRIPTION = 'PostCompact hook handler: settle the open compact run because the HARNESS reported a ' +
+    'compaction completed, and append an `observed` compact-history row carrying the ' +
+    'harness-reported trigger (manual | auto). Reads the hook JSON on stdin; prints nothing ' +
+    'and exits 0 when run by the hook. Pass --json for the diagnostic envelope.';
+/**
+ * Read the `PostCompact` hook payload from stdin.
+ *
+ * `PEAKS_HOOK_STDIN` is the test seam, verbatim the one `peaks gate enforce`
+ * uses (`gate-commands.ts`) — the CLI side owns `process.stdin`'s lifecycle, so
+ * the reader lives with the command rather than in the service.
+ *
+ * Returns `null` for every shape that is not a JSON object: empty stdin, a TTY
+ * (the `--json` diagnostic path run by a human), malformed JSON. A payload that
+ * cannot be read is not a failure — it is a payload with no `trigger`, which is
+ * an input this path is explicitly designed to accept.
+ */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    let raw;
+    if (override !== undefined) {
+        raw = override;
+    }
+    else if (process.stdin.isTTY) {
+        raw = '';
+    }
+    else {
+        raw = await new Promise((resolveStdin) => {
+            let data = '';
+            process.stdin.setEncoding('utf8');
+            process.stdin.on('data', (chunk) => {
+                data += chunk;
+            });
+            process.stdin.on('end', () => resolveStdin(data));
+            process.stdin.on('error', () => resolveStdin(data));
+        });
+    }
+    if (raw.trim().length === 0)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function reportCompactSettleSessionFailure(io, error, project) {
+    printResult(io, fail('compact.settle', error.code, error.message, { projectRoot: project }, error.nextActions), true);
+}
+function buildCompactSettleNextActions(result) {
+    return [
+        result.settled
+            ? result.lifecycleWritten
+                ? result.historyWritten
+                    ? `Settled run ${result.runId}; appended a kind:'observed' row with pathway 'post-compact-hook'.`
+                    : `Settled run ${result.runId}, but the kind:'observed' row could NOT be appended — check that .peaks/_runtime/<sid>/ is writable.`
+                : `The harness reported a compaction for run ${result.runId}, but the lifecycle record could NOT be written — that run is still open, so a later probe will settle it from its own measurement and append the row then. Nothing was recorded for this event: a row here would assert a settlement the store never made.`
+            : result.reason === 'different-session'
+                ? `The hook payload names a different harness session, so this project's open compact run was left alone.`
+                : 'No compact run was open, so nothing was settled and no history row was appended.'
+    ];
+}
+function reportCompactSettleFailure(io, error) {
+    printResult(io, fail('compact.settle', 'COMPACT_SETTLE_FAILED', getErrorMessage(error), {}, [
+        'Verify the project path and session binding'
+    ]), true);
+}
+async function runCompactSettle(options, io) {
+    // One parse, two fields: reading stdin twice would let the two readers
+    // disagree about the payload they were handed.
+    const payload = await readHookPayload();
+    const trigger = readTriggerFromHookPayload(payload);
+    const hookSessionId = readSessionIdFromHookPayload(payload);
+    // The hook path returns before any `process.exitCode` assignment below, so
+    // the harness never sees a non-zero exit from this command.
+    try {
+        const project = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(project, options.sessionId);
+        if (session.error !== null) {
+            if (options.json !== true)
+                return;
+            reportCompactSettleSessionFailure(io, session.error, project);
+            return;
+        }
+        const result = settleCompactFromHarnessEvent({
+            projectRoot: project,
+            sessionId: session.sid,
+            trigger,
+            hookSessionId
+        });
+        if (options.json !== true)
+            return;
+        printResult(io, ok('compact.settle', { projectRoot: project, sessionId: session.sid, trigger: trigger ?? null, ...result }, [], buildCompactSettleNextActions(result)), true);
+    }
+    catch (error) {
+        if (options.json !== true)
+            return;
+        reportCompactSettleFailure(io, error);
+    }
+}
+export function registerCompactSettleCommand(compact, io) {
+    // 8. peaks compact settle [--json]
+    //
+    // The `PostCompact` hook's transport. Before this command, peaks-loop knew a
+    // compaction had landed only because a LATER probe measured a ratio that had
+    // fallen — an inference. This command lets the harness's own event settle the
+    // run, and records what the harness said the compaction WAS (`manual` /
+    // `auto`), which is the one question a ratio can never answer.
+    //
+    // STDOUT IS CONTEXT HERE. `PostCompact`'s output contract is truncated in the
+    // retrievable docs, so the safe assumption is the `SessionStart` one: stdout
+    // is added to the model's context. The hook path therefore prints NOTHING and
+    // exits 0 for every outcome — success, no open run, unresolvable session,
+    // unparseable stdin. An error sentence in the model's context is a false
+    // problem handed to it mid-slice. Same discipline as `session reinject`;
+    // `--json` is the diagnostic surface, and the hook never passes it.
+    addJsonOption(compact
+        .command('settle')
+        .description(COMPACT_SETTLE_DESCRIPTION)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')).action((options) => runCompactSettle(options, io));
+}

package/dist/cli/commands/compact-shared.d.ts

@@ -0,0 +1,9 @@
+/** The active session id, or the refusal envelope every caller prints the same way. */
+export declare function resolveSessionId(projectRoot: string, explicit: string | undefined): {
+    sid: string | null;
+    error: {
+        code: string;
+        message: string;
+        nextActions: string[];
+    } | null;
+};

package/dist/cli/commands/compact-shared.js

@@ -0,0 +1,26 @@
+// The session binding every `peaks compact` subcommand resolves through, on its own so
+// the five commands that read it share one fix point.
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+/** The active session id, or the refusal envelope every caller prints the same way. */
+export function resolveSessionId(projectRoot, explicit) {
+    if (explicit !== undefined && explicit.length > 0) {
+        return { sid: explicit, error: null };
+    }
+    // Statically-imported `getSessionIdCanonical` (see import block
+    // at the top of this file). It is the single source of truth for
+    // "what session is bound to this project"; we use it instead of
+    // re-implementing the resolution here to keep one fix point when
+    // the binding layout changes.
+    const sid = getSessionIdCanonical(projectRoot) ?? null;
+    if (sid === null) {
+        return {
+            sid: null,
+            error: {
+                code: 'NO_ACTIVE_SESSION',
+                message: 'No active session bound. Run `peaks workspace init --project <repo> --json` to bind one.',
+                nextActions: [`peaks workspace init --project ${projectRoot} --json`]
+            }
+        };
+    }
+    return { sid, error: null };
+}

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;

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

@@ -0,0 +1,105 @@
+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 { atomicWriteJson } from '../../services/ide/shared/atomic-json.js';
+import { containerLeaseFilePath, deserializeContainerLease, markContainerReleased } from '../../services/container/container-lease.js';
+import { detectContainerRuntime, joinPathSession, resolveContainerTarget } from './container-command-shared.js';
+export function registerContainerReleaseCommand(cmd, io) {
+    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) => runContainerRelease(io, options));
+}
+/** Read + parse the lease file; `null` once the refusal is emitted. */
+function readLease(io, options, file) {
+    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 null;
+    }
+    try {
+        return 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 null;
+    }
+}
+/** `docker rm --force`, tolerating a container that is already gone. */
+function removeContainer(lease, projectRoot) {
+    try {
+        const detected = detectContainerRuntime(undefined);
+        const runtimeCmd = detected.ok ? detected.runtime : 'docker';
+        execSync(`${runtimeCmd} rm --force "${lease.containerId}"`, {
+            cwd: projectRoot,
+            stdio: 'pipe',
+            encoding: 'utf8',
+            windowsHide: true
+        });
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function runContainerRelease(io, options) {
+    const { projectRoot, sessionId } = resolveContainerTarget(options);
+    try {
+        const file = containerLeaseFilePath(joinPathSession(projectRoot, sessionId), options.leaseId);
+        const lease = readLease(io, options, file);
+        if (lease === null)
+            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;
+        }
+        const outcome = releaseLease({ options, io, projectRoot, sessionId, file, lease });
+        printResult(io, ok('container.release', outcome.data, outcome.warnings, outcome.nextActions), 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;
+    }
+}
+/**
+ * `docker rm --force` the container, flip the lease to released and write it
+ * back. A failed `docker rm` is reported, not fatal: the lease is the source
+ * of truth and it is still marked released.
+ */
+function releaseLease(plan) {
+    const { projectRoot, sessionId, file, lease } = plan;
+    const dockerRmFailed = removeContainer(lease, projectRoot);
+    const released = markContainerReleased(lease);
+    atomicWriteJson(file, released);
+    return {
+        data: { lease: released, sessionId, projectRoot, dockerRmFailed },
+        warnings: dockerRmFailed
+            ? ['docker rm failed (likely the container was already removed); lease marked released.']
+            : [],
+        nextActions: [
+            `Lease ${lease.leaseId} marked released.`,
+            dockerRmFailed
+                ? 'Manual `docker ps -a` + `docker rm` may be needed.'
+                : `Container ${lease.containerId} removed.`
+        ]
+    };
+}

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

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