peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,304 @@
+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 { writeCheckpoint } from '../../services/session/session-checkpoint-service.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { readCompactHistory, summarizeCompactHistory, } from '../../services/compact-history/compact-history-service.js';
+import { buildRecommendEnvelopePure, dryRunCompact, suggestCompact } from '../../services/compact/suggest-service.js';
+import { PHASES, SURVIVAL_TABLE, isPhase, lookupPhaseTransition } from '../../services/compact/decision-tables.js';
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+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 };
+}
+export function registerCompactCommands(program, io) {
+    const compact = program
+        .command('compact')
+        .description('Strategic-compact primitives: suggest / recommend / survival / dry-run / force');
+    // -----------------------------------------------------------------
+    // 1. peaks compact suggest [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('suggest')
+        .description('Two-signal suggestion (context-size + tool-call-count). ' +
+        'Honor COMPACT_THRESHOLD / COMPACT_CONTEXT_THRESHOLD / COMPACT_CONTEXT_INTERVAL env vars. ' +
+        'Read-only by default; pass --apply to also append a one-line info row to the session log.')
+        .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)')
+        .option('--apply', 'append a one-line info row to .peaks/_runtime/<sid>/session.json (default: dry-run)')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.suggest', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = suggestCompact({
+                projectRoot,
+                sessionId: session.sid
+            });
+            printResult(io, ok('compact.suggest', result, [], [
+                result.shouldSuggest
+                    ? `Run \`peaks compact force --reason "<short note>"\` to checkpoint, then /compact.`
+                    : `Context at ${(result.ratio * 100).toFixed(1)}% (${result.tokensUsed} of ${result.windowKind === '1m' ? '1M' : '200k'}); below threshold.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.suggest', 'COMPACT_SUGGEST_FAILED', getErrorMessage(error), {}, ['Verify project root and session binding before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks compact recommend --from <phase> --to <phase> [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('recommend')
+        .description(`Strategic-compact "Compaction Decision Guide" lookup. ` +
+        `Valid phases: ${PHASES.join(', ')}. Pure function over (from, to); no I/O.`)
+        .requiredOption('--from <phase>', `source phase (one of ${PHASES.join(', ')})`)
+        .requiredOption('--to <phase>', `target phase (one of ${PHASES.join(', ')})`)).action((options) => {
+        try {
+            if (!isPhase(options.from)) {
+                printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${options.from}")`, { from: options.from }, [`Use --from ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!isPhase(options.to)) {
+                printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${options.to}")`, { to: options.to }, [`Use --to ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = buildRecommendEnvelopePure(options.from, options.to);
+            const lookup = lookupPhaseTransition(options.from, options.to);
+            printResult(io, ok('compact.recommend', {
+                from: envelope.from,
+                to: envelope.to,
+                shouldCompact: envelope.shouldCompact,
+                severity: envelope.severity,
+                rationale: envelope.rationale,
+                suggestedMessage: envelope.suggestedMessage,
+                notInTable: lookup.notInTable
+            }, lookup.notInTable ? [`Transition ${options.from} → ${options.to} is not in the strategic-compact table; defaulting to severity=no.`] : []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.recommend', 'COMPACT_RECOMMEND_FAILED', getErrorMessage(error), { from: options.from, to: options.to }, ['Verify the phase pair against the documented transitions']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks compact survival [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('survival')
+        .description('Strategic-compact "What Survives Compaction" table. Pure static data; no I/O.')).action((options) => {
+        printResult(io, ok('compact.survival', {
+            persists: [...SURVIVAL_TABLE.persists],
+            lost: [...SURVIVAL_TABLE.lost]
+        }, [], [
+            'Persists = guaranteed across `/compact`. Lost = not preserved; persist to disk before compacting.'
+        ]), options.json);
+    });
+    // -----------------------------------------------------------------
+    // 4. peaks compact dry-run [--from <phase>] [--to <phase>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('dry-run')
+        .description('Composite preview of (suggest + recommend + survival). ' +
+        'No writes. The LLM calls this every tool-call cycle to stay informed.')
+        .option('--from <phase>', `optional source phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--to <phase>', `optional target phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.dry-run', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if ((options.from === undefined) !== (options.to === undefined)) {
+                printResult(io, fail('compact.dry-run', 'PHASE_PAIR_INCOMPLETE', 'Both --from and --to must be provided together', { from: options.from, to: options.to }, ['Pass both --from and --to, or omit both for a suggest-only dry-run']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.from !== undefined && !isPhase(options.from)) {
+                printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${options.from}")`, { from: options.from }, [`Use --from ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.to !== undefined && !isPhase(options.to)) {
+                printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${options.to}")`, { to: options.to }, [`Use --to ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const hasPhasePair = options.from !== undefined && options.to !== undefined;
+            const dryRunInput = {
+                projectRoot,
+                sessionId: session.sid
+            };
+            if (hasPhasePair) {
+                dryRunInput.from = options.from;
+                dryRunInput.to = options.to;
+            }
+            const result = dryRunCompact(dryRunInput);
+            printResult(io, ok('compact.dry-run', result, [], [
+                result.action === 'compact'
+                    ? `Action=compact: run \`peaks compact force --reason "<note>"\`, then /compact.`
+                    : `Action=skip: continue without compacting.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.dry-run', 'COMPACT_DRY_RUN_FAILED', getErrorMessage(error), {}, ['Verify project root, session binding, and phase pair before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 5. peaks compact force [--reason <text>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('force')
+        .description('Write a pre-compact checkpoint via `peaks session checkpoint --reason context-fill`. ' +
+        'The IDE-side `/compact` is still the LLM\'s call; this primitive guarantees ' +
+        'the pre-compact state is persisted. NO sleep, NO wait for IDE response.')
+        .option('--reason <text>', 'human-readable reason for the pre-compact checkpoint', 'pre-force-compact')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')
+        .option('--current-plan <text>', 'current plan summary (forwarded to the checkpoint snapshot)')
+        .option('--open-questions <list>', 'newline-separated open questions')
+        .option('--recent-decisions <list>', 'newline-separated recent decisions')
+        .option('--recent-artifact-paths <list>', 'newline-separated recent artifact paths')
+        .option('--git-status <text>', 'recent git status')
+        .option('--skills-active <list>', 'newline-separated active skill names')
+        .option('--todo-state <list>', 'newline-separated todo lines')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.force', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const reason = (options.reason ?? 'pre-force-compact').slice(0, 200);
+            // The session-checkpoint-service restricts `reason` to a fixed
+            // enum. The strategic-compact `force` primitive uses
+            // 'context-fill' (the closest semantic match: the LLM is
+            // compacting because of context pressure) and records the
+            // caller's free-form reason in `gitStatus` so the snapshot
+            // is self-describing without inventing a new enum value.
+            const checkpointOptions = {
+                sessionId: session.sid,
+                reason: 'context-fill',
+                gitStatus: `compact.force: ${reason}`,
+                openQuestions: splitList(options.openQuestions),
+                recentDecisions: splitList(options.recentDecisions),
+                recentArtifactPaths: splitList(options.recentArtifactPaths),
+                skillsActive: splitList(options.skillsActive),
+                todoState: splitList(options.todoState)
+            };
+            if (options.currentPlan !== undefined) {
+                checkpointOptions.currentPlan = options.currentPlan;
+            }
+            const result = writeCheckpoint(projectRoot, checkpointOptions);
+            printResult(io, ok('compact.force', {
+                checkpointPath: result.path,
+                reason: 'pre-force-compact',
+                callerReason: reason,
+                sessionId: result.sessionId,
+                createdAt: result.createdAt,
+                totalRetained: result.totalRetained,
+                message: 'Pre-compact checkpoint written. The IDE-side /compact is still the LLM\'s call; this CLI does NOT invoke the IDE slash command.'
+            }, [], [
+                'After the LLM fires the IDE-side /compact, call `peaks compact survival` to see what to persist before the next compact.'
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.force', 'COMPACT_FORCE_FAILED', getErrorMessage(error), {}, ['Verify the project path is writable and a session is bound']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // 6. peaks compact history [--json] (slice 2026-07-30-compact-visibility)
+    addJsonOption(compact
+        .command('history')
+        .description('Read the per-session compact-history.jsonl and emit a structured ' +
+        'summary of every auto-compact dispatch in the current session.')
+        .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) => {
+        try {
+            const project = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(project, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.history', session.error.code, session.error.message, { projectRoot: project }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = readCompactHistory({ projectRoot: project, sessionId: session.sid });
+            if (result.kind === 'file-missing') {
+                printResult(io, ok('compact.history', {
+                    sessionId: session.sid,
+                    totalCompacts: 0,
+                    message: 'No compact-history.jsonl yet; auto-compact has not fired in this session.',
+                    historyPath: result.path,
+                }), options.json);
+                return;
+            }
+            if (result.kind === 'empty') {
+                printResult(io, ok('compact.history', {
+                    sessionId: session.sid,
+                    totalCompacts: 0,
+                    message: 'compact-history.jsonl exists but is empty.',
+                    historyPath: result.path,
+                }), options.json);
+                return;
+            }
+            const summary = summarizeCompactHistory(result.events);
+            printResult(io, ok('compact.history', {
+                sessionId: session.sid,
+                ...summary,
+                events: result.events,
+                parseErrors: result.parseErrors,
+                historyPath: result.path,
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.history', 'COMPACT_HISTORY_READ_FAILED', getErrorMessage(error), {}, ['Verify the project path is readable and a session is bound']), options.json);
+            process.exitCode = 1;
+        }
+    }));
+}

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

@@ -0,0 +1,9 @@
+/**
+ * v2.15.0 follow-up — G10: peaks complexity estimate CLI.
+ *
+ *   - `peaks complexity estimate --files <list>` — per-file tier +
+ *     aggregate. Aligns with the G2 12 Gaps memory tier definition.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerComplexityCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,34 @@
+/**
+ * v2.15.0 follow-up — G10: peaks complexity estimate CLI.
+ *
+ *   - `peaks complexity estimate --files <list>` — per-file tier +
+ *     aggregate. Aligns with the G2 12 Gaps memory tier definition.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { estimateComplexity } from '../../services/complexity/complexity-estimator.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerComplexityCommands(program, io) {
+    addJsonOption(program
+        .command('complexity-estimate')
+        .description('v2.15.0 follow-up G10: estimate the complexity tier (trivial / simple / ' +
+        'complex) of a set of files, based on LOC + export count + async usage. ' +
+        'Aligns with the G2 12 Gaps memory tier definition. The aggregate ' +
+        'tier drives scheduling (trivial / simple → overnight; complex → ' +
+        'user-attended).')
+        .requiredOption('--files <list>', 'comma-separated file paths (relative to project root)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('complexity-estimate', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = estimateComplexity(projectRoot, files);
+        printResult(io, ok('complexity-estimate', { projectRoot, report }, [], [
+            `Overall tier: ${report.overall}. Schedule accordingly.`
+        ]), opts.json ?? false);
+    });
+}

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

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

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

@@ -0,0 +1,149 @@
+import { executeMigration, planMigration } from '../../services/config/config-migration.js';
+import { getConfig, isSensitiveConfigPath, redactConfigSecrets, setConfig } from '../../services/config/config-service.js';
+import { listAvailableFields, restoreField } from '../../services/config/config-restore.js';
+import { executeRollback, planRollback } from '../../services/config/config-rollback.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, parseConfigLayer, printInvalidConfigLayer, printResult } from '../cli-helpers.js';
+export function registerConfigCommands(program, io) {
+    const config = program.command('config').description('Manage Peaks configuration');
+    registerConfigGetSetCommands(config, io);
+    registerConfigMigrationCommands(config, io);
+}
+function registerConfigGetSetCommands(config, io) {
+    addJsonOption(config.command('get').description('Get current config or a specific key').option('--key <path>', 'dot-notation key path').option('--layer <layer>', 'user or project')).action((options) => {
+        const layer = parseConfigLayer(options.layer);
+        if (layer === null) {
+            printInvalidConfigLayer(io, 'config.get', options.json);
+            return;
+        }
+        const getOpts = { ...(layer !== undefined ? { layer } : {}), ...(options.key !== undefined ? { key: options.key } : {}) };
+        const value = getConfig(getOpts);
+        const isSensitiveKey = options.key !== undefined && isSensitiveConfigPath(options.key);
+        printResult(io, ok('config.get', isSensitiveKey ? '***' : redactConfigSecrets(value, options.key ?? '')), options.json);
+    });
+    addJsonOption(config.command('set').description('Set a config value').requiredOption('--key <path>', 'dot-notation key path').requiredOption('--value <json>', 'JSON value').option('--layer <layer>', 'user or project')).action((options) => {
+        const parsedLayer = parseConfigLayer(options.layer);
+        if (parsedLayer === null) {
+            printInvalidConfigLayer(io, 'config.set', options.json);
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(options.value);
+        }
+        catch {
+            printResult(io, fail('config.set', 'INVALID_JSON', 'Could not parse value as JSON', {}, ['Use valid JSON: --value \'{"key":"value"}\'']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            setConfig({ key: options.key, value: parsed, layer: parsedLayer ?? 'user' });
+            const value = isSensitiveConfigPath(options.key) ? '***' : redactConfigSecrets(parsed);
+            printResult(io, ok('config.set', { key: options.key, value }), options.json);
+        }
+        catch (error) {
+            printConfigSetError(io, error, options.json);
+        }
+    });
+}
+function registerConfigMigrationCommands(config, io) {
+    // Slice 0.5 Task 14 — peaks config {migrate,rollback,restore} subcommands.
+    // Wires up the config-migration / config-rollback / config-restore services
+    // from Tasks 10-12. The default mode is dry-run; --apply writes.
+    config
+        .command('migrate')
+        .description('Migrate global config from 1.x to 2.0 (YAGNI slim + per-project fields)')
+        .option('--project <path>', 'current project root (for migrating per-project fields)', process.cwd())
+        .option('--apply', 'actually write changes (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            const apply = options.apply === true;
+            if (apply) {
+                const result = executeMigration({ currentProjectRoot: options.project, apply: true });
+                printResult(io, ok('config.migrate', result), options.json);
+                return;
+            }
+            const plan = planMigration({ currentProjectRoot: options.project });
+            printResult(io, ok('config.migrate', { ...plan, applied: false }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('config.migrate', 'CONFIG_MIGRATE_FAILED', getErrorMessage(error), {}, ['Inspect ~/.peaks/config.json and re-run with --apply']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    config
+        .command('rollback')
+        .description('Rollback global config to 1.x from .bak')
+        .option('--apply', 'actually write changes (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            const apply = options.apply === true;
+            if (apply) {
+                const result = executeRollback({ apply: true });
+                printResult(io, ok('config.rollback', result), options.json);
+                return;
+            }
+            const plan = planRollback();
+            printResult(io, ok('config.rollback', { ...plan, applied: false }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            const code = message.startsWith('NO_BACKUP') ? 'NO_BACKUP' : 'CONFIG_ROLLBACK_FAILED';
+            io.stderr(`${code}: ${message}`);
+            printResult(io, fail('config.rollback', code, message, {}, ['Re-run peaks config migrate --apply to recreate the .bak']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    config
+        .command('restore')
+        .description('Restore a single archived field from .bak to a sidecar file')
+        .option('--field <name>', 'field name to restore (e.g. language, currentWorkspace)')
+        .option('--list', 'list all fields available in .bak')
+        .option('--apply', 'actually write sidecar (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            if (options.list === true || !options.field) {
+                const fields = listAvailableFields();
+                printResult(io, ok('config.restore', { fields, applied: false }), options.json);
+                return;
+            }
+            const apply = options.apply === true;
+            const result = restoreField({ field: options.field, apply });
+            printResult(io, ok('config.restore', result), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            let code = 'CONFIG_RESTORE_FAILED';
+            if (message.startsWith('NO_BACKUP'))
+                code = 'NO_BACKUP';
+            else if (message.startsWith('RESTORE_GUARDED'))
+                code = 'RESTORE_GUARDED';
+            else if (message.startsWith('FIELD_NOT_FOUND'))
+                code = 'FIELD_NOT_FOUND';
+            io.stderr(`${code}: ${message}`);
+            printResult(io, fail('config.restore', code, message, {}, ['Use --list to see available fields']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function printConfigSetError(io, error, asJson) {
+    const message = getErrorMessage(error);
+    if (message === 'Sensitive config keys must be stored in the user config layer') {
+        printResult(io, fail('config.set', 'SECRET_CONFIG_REQUIRES_USER_LAYER', message, {}, ['Use --layer user for sensitive config keys']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    if (message === 'Project config not found') {
+        printResult(io, fail('config.set', 'PROJECT_CONFIG_NOT_FOUND', message, {}, ['Create a safe .peaks/config.json in the project or use --layer user']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, fail('config.set', 'CONFIG_SET_FAILED', message, {}, ['Check the config key and layer, then retry']), asJson);
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * `peaks container spawn | release` — slice 2026-07-29-worktree-l2-extended Part 12.
+ *
+ * L4 container isolation bridge: Part 8 landed the CLI contract
+ * (`peaks sub-agent dispatch --isolation container` is accepted
+ * and fail-fasts with ISOLATION_CONTAINER_NOT_YET_IMPLEMENTED).
+ * Part 12 implements the spawn/release CLI surface so the
+ * dispatch command can shell out to it.
+ *
+ * This file is the `peaks container` parent command. Sub-commands:
+ *   - spawn   : `docker run <image> ...` + write container lease
+ *   - release : `docker rm --force <id>` + transition lease to released
+ *
+ * Runtime requirement: `docker` CLI on PATH. The spawn checks
+ * `docker --version` first and returns CONTAINER_RUNTIME_UNAVAILABLE
+ * with a remediation hint when the daemon is not running. Windows
+ * is supported if Docker Desktop / WSL2 is installed; native podman
+ * is a follow-up (the container-lease module is runtime-agnostic).
+ *
+ * Lease is the source of truth: the dispatch record (v3) carries
+ * the leaseId; the PreToolUse gate (Part 2.B pattern) will read
+ * PEAKS_CONTAINER_LEASE_ID and consult the lease file before
+ * allowing docker-related tool calls. The gate bridge is a
+ * follow-up rid.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContainerCommand(program: Command, io: ProgramIO): void;