peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/lease-stats-commands.d.ts

@@ -0,0 +1,65 @@
+/**
+ * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
+ *
+ * Single top-level command that aggregates lease observability for
+ * the whole project root and returns a summary envelope suitable
+ * for dashboards / pipelines:
+ *
+ *   - per-kind counts (same as peaks lease-metrics)
+ *   - leak rate (estimatedActive / estimatedLeaked)
+ *   - per-rid breakdown: which request ids are still "alive"
+ *     (i.e. the rid has a spawn event with no terminal)
+ *   - per-role breakdown: lease spawns split by role
+ *   - per-isolation breakdown: 'worktree' | 'container' | 'none'
+ *     (Part 8 adds 'container')
+ *
+ * The per-rid / per-role / per-isolation breakdowns use the
+ * `rid` / `role` fields on the observability detail (Part 4.A
+ * emitter passes these). The 'isolation' field is read off the
+ * underlying dispatch record via the readObservabilityEvents
+ * reader — but the events themselves don't carry isolation
+ * mode. To get that, we walk the dispatch records (not events)
+ * and join on the dispatch's `isolation` field. This is a
+ * cross-file read but the operation is cheap (each session's
+ * dispatch records are a small JSON set).
+ *
+ * Why this is a separate command from `peaks lease-metrics`:
+ * `lease-metrics` answers "what events did I record?" (event
+ * stream semantics). `lease-stats` answers "what's the project
+ * status right now?" (state semantics). The two compose:
+ * `lease-metrics --all-sessions` is the input, `lease-stats`
+ * is the answer.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type RateStats } from './lease-metrics-commands.js';
+type RidCount = {
+    rid: string;
+    count: number;
+};
+type RoleCount = {
+    role: string;
+    count: number;
+};
+type IsolationCount = {
+    isolation: 'worktree' | 'container' | 'none';
+    count: number;
+};
+type LeaseStats = {
+    readonly projectRoot: string;
+    readonly sessionCount: number;
+    readonly totalLeaseEvents: number;
+    readonly rate: RateStats;
+    readonly perRid: ReadonlyArray<RidCount>;
+    readonly perRole: ReadonlyArray<RoleCount>;
+    readonly perIsolation: ReadonlyArray<IsolationCount>;
+};
+export declare function computeLeaseStats(args: {
+    projectRoot: string;
+    eventsBySession: ReadonlyArray<{
+        sessionId: string;
+        events: ReadonlyArray<unknown>;
+    }>;
+}): LeaseStats;
+export declare function registerLeaseStatsCommand(parent: Command, io: ProgramIO): void;
+export {};

package/dist/cli/commands/lease-stats-commands.js

@@ -0,0 +1,107 @@
+/**
+ * `peaks lease-stats` — slice 2026-07-29-worktree-l2-extended Part 6.
+ *
+ * Single top-level command that aggregates lease observability for
+ * the whole project root and returns a summary envelope suitable
+ * for dashboards / pipelines:
+ *
+ *   - per-kind counts (same as peaks lease-metrics)
+ *   - leak rate (estimatedActive / estimatedLeaked)
+ *   - per-rid breakdown: which request ids are still "alive"
+ *     (i.e. the rid has a spawn event with no terminal)
+ *   - per-role breakdown: lease spawns split by role
+ *   - per-isolation breakdown: 'worktree' | 'container' | 'none'
+ *     (Part 8 adds 'container')
+ *
+ * The per-rid / per-role / per-isolation breakdowns use the
+ * `rid` / `role` fields on the observability detail (Part 4.A
+ * emitter passes these). The 'isolation' field is read off the
+ * underlying dispatch record via the readObservabilityEvents
+ * reader — but the events themselves don't carry isolation
+ * mode. To get that, we walk the dispatch records (not events)
+ * and join on the dispatch's `isolation` field. This is a
+ * cross-file read but the operation is cheap (each session's
+ * dispatch records are a small JSON set).
+ *
+ * Why this is a separate command from `peaks lease-metrics`:
+ * `lease-metrics` answers "what events did I record?" (event
+ * stream semantics). `lease-stats` answers "what's the project
+ * status right now?" (state semantics). The two compose:
+ * `lease-metrics --all-sessions` is the input, `lease-stats`
+ * is the answer.
+ */
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { readAllSessionLeaseEvents, recomputeRate } from './lease-metrics-commands.js';
+function tallyByField(events, field) {
+    const out = new Map();
+    for (const ev of events) {
+        const v = ev.detail[field];
+        if (typeof v !== 'string' || v.length === 0)
+            continue;
+        out.set(v, (out.get(v) ?? 0) + 1);
+    }
+    return out;
+}
+export function computeLeaseStats(args) {
+    // The events pass through `tallyByField` (which only reads
+    // `detail`) and through `recomputeRate` (which reads `detail` +
+    // `ts`). The interface is widened to `unknown` here so the
+    // caller can pass any observability-event-shaped object;
+    // `recomputeRate`'s parameter type is the canonical
+    // `ObservabilityEvent[]`, so we cast at the boundary.
+    const allEvents = args.eventsBySession.flatMap((s) => s.events);
+    const rate = recomputeRate(allEvents);
+    const ridTally = tallyByField(allEvents, 'rid');
+    const roleTally = tallyByField(allEvents, 'role');
+    const isoTally = new Map();
+    for (const ev of allEvents) {
+        const detail = ev.detail;
+        const iso = typeof detail['isolation'] === 'string' ? detail['isolation'] : 'none';
+        isoTally.set(iso, (isoTally.get(iso) ?? 0) + 1);
+    }
+    return {
+        projectRoot: args.projectRoot,
+        sessionCount: args.eventsBySession.length,
+        totalLeaseEvents: allEvents.length,
+        rate,
+        perRid: Array.from(ridTally.entries())
+            .map(([rid, count]) => ({ rid, count }))
+            .sort((a, b) => b.count - a.count)
+            .slice(0, 20),
+        perRole: Array.from(roleTally.entries())
+            .map(([role, count]) => ({ role, count }))
+            .sort((a, b) => b.count - a.count),
+        perIsolation: Array.from(isoTally.entries())
+            .map(([isolation, count]) => ({ isolation: isolation, count }))
+            .sort((a, b) => b.count - a.count)
+    };
+}
+export function registerLeaseStatsCommand(parent, io) {
+    addJsonOption(parent
+        .command('lease-stats')
+        .description('Project-wide lease summary: counts, leak rate, per-rid / per-role / per-isolation breakdown. Always aggregates across every session in the project root.')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const { sessions } = readAllSessionLeaseEvents(projectRoot);
+            const eventsBySession = sessions.map((s) => ({
+                sessionId: s.sessionId,
+                events: s.events.map((e) => ({ detail: (e.detail ?? {}) }))
+            }));
+            const stats = computeLeaseStats({ projectRoot, eventsBySession });
+            printResult(io, ok('lease.stats', stats, [], [
+                `${stats.totalLeaseEvents} lease events across ${stats.sessionCount} session(s); ${stats.rate.estimatedActive} estimated active, ${stats.rate.estimatedLeaked} estimated leaked.`,
+                stats.perRid.length > 0 ? `Top rid: ${stats.perRid[0]?.rid} (${stats.perRid[0]?.count} events).` : '',
+                'Pipe to `jq` or paste into a dashboard for visual rendering.'
+            ].filter(Boolean)), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('lease.stats', 'STATS_READ_FAILED', err instanceof Error ? err.message : String(err), { projectRoot: options.project }, [
+                'Verify the project root is correct.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-loop is applied
+ *     to a 存量老项目.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLegacyCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,32 @@
+/**
+ * v2.15.0 follow-up — G8: peaks legacy detect CLI.
+ *
+ *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
+ *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
+ *     Useful as a "where to start" inventory when peaks-loop is applied
+ *     to a 存量老项目.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { detectLegacy } from '../../services/legacy/legacy-detector.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerLegacyCommands(program, io) {
+    addJsonOption(program
+        .command('legacy-detect')
+        .description('v2.15.0 follow-up G8: scan a directory for legacy smells (TODO/FIXME/HACK, ' +
+        'console.log, any-type, large files, ts-ignore). Returns a smell grade ' +
+        '(low / medium / high) and per-kind counts. Lightweight heuristics — ' +
+        'NOT a replacement for a real linter. Useful as a "where to start" ' +
+        'inventory when peaks-loop is applied to a legacy codebase.')
+        .option('--dir <path>', 'directory to scan (default: src)', 'src')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const report = detectLegacy(projectRoot, opts.dir);
+        printResult(io, ok('legacy-detect', { projectRoot, dir: opts.dir, report }, [], [
+            `Scanned ${report.scannedFiles} file(s). Smells: ${report.smells}.`,
+            report.smells === 'high'
+                ? 'Consider refactoring high-smell areas first.'
+                : 'Manageable technical debt.'
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,17 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLogCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,64 @@
+/**
+ * `peaks log *` subcommands.
+ *
+ * Slice 2026-06-16-cli-logging (G4). Two subcommands:
+ *   - `peaks log tail [--lines N]` — print the last N lines of
+ *     today's JSONL log to stdout. With `--json`, prints as a
+ *     JSON envelope (matching the project's response shape).
+ *   - `peaks log ls` — list the available log files (newest first).
+ *
+ * The CLI layer is intentionally thin: it formats the output and
+ * delegates the actual filesystem reads to
+ * `src/services/log/log-commands-service.ts`. That service is
+ * already covered by `tests/unit/log/log-commands.test.ts`.
+ */
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { tailLog, listLogFiles } from '../../services/log/log-commands-service.js';
+import { getErrorMessage, printResult, addJsonOption } from '../cli-helpers.js';
+import { ok, fail } from 'peaks-loop-shared/result';
+export function registerLogCommands(program, io) {
+    const log = program
+        .command('log')
+        .description('Inspect the peaks-loop JSONL log directory (default: ~/.peaks/logs/)');
+    addJsonOption(log
+        .command('tail')
+        .description('Print the last 50 lines of today\'s peaks-loop log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.')
+        .option('--lines <n>', 'number of lines to show (default 50)', (value) => Number(value))
+        .option('--date <YYYY-MM-DD>', 'read the log for this UTC date instead of today (PRD AC2: PEAKS_LOG_DATE_OVERRIDE)')
+        // Slice 2026-06-23-audit-4th #B2: --batch filter for cross-run
+        // correlation. Without this, a user post-hoc cannot group the
+        // log lines for one batch (they interleave in the JSONL file).
+        .option('--batch <id>', 'filter entries by batchId (sub-agent dispatch / heartbeat / share)')).action((options) => {
+        try {
+            const requestedLines = options.lines ?? 50;
+            const safeLines = Number.isFinite(requestedLines) && requestedLines > 0 ? Math.floor(requestedLines) : 50;
+            const result = tailLog({
+                lines: safeLines,
+                ...(options.date !== undefined ? { dateOverride: options.date } : {}),
+                ...(options.batch !== undefined ? { batchId: options.batch } : {})
+            });
+            printResult(io, ok('log.tail', {
+                file: result.file,
+                total: result.total,
+                lines: safeLines,
+                ...(options.batch !== undefined ? { batch: options.batch, batchMatches: result.batchMatches ?? 0 } : {}),
+                entries: result.entries
+            }, []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('log.tail', 'LOG_TAIL_FAILED', getErrorMessage(error), {}, ['Check `peaks log ls` to see available log files']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(log
+        .command('ls')
+        .description('List peaks-loop-*.log files in ~/.peaks/logs/ (newest first).')).action((options) => {
+        const files = listLogFiles();
+        printResult(io, ok('log.ls', {
+            logDir: join(homedir(), '.peaks', 'logs'),
+            total: files.length,
+            files
+        }, []), options.json);
+    });
+}

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

@@ -0,0 +1,27 @@
+/**
+ * peaks loop * CLI (Slice #14 + M7 add).
+ *
+ * Slices:
+ *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
+ *     detect-pattern / check-consistency / peaks goal compose.
+ *
+ *   M7 (2026-07-07 spec §7A.2):
+ *     peaks loop export --loop <id> --out <path.tar.gz>
+ *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
+ *
+ * `peaks loop export` reads the source loop_release + relations +
+ * related bees + evidence briefs and emits a `peaks.bundle/1`
+ * tar.gz. Hard-blocks when the source has `shareable=false`.
+ *
+ * `peaks loop import` extracts a bundle, validates
+ * format_version_major=1, and lands the release as `candidate`
+ * (mandatory landing status per spec §7A.2). The receiver must run
+ * an independent evaluation before promoting to `stable`.
+ *
+ * The existing 14.x commands are kept under the same `loop` parent;
+ * M7 only ADDs export / import — it does not modify the existing
+ * surface.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,262 @@
+/**
+ * peaks loop * CLI (Slice #14 + M7 add).
+ *
+ * Slices:
+ *   #14 sub-features (L4 Agent Loop integration): distill / preflight /
+ *     detect-pattern / check-consistency / peaks goal compose.
+ *
+ *   M7 (2026-07-07 spec §7A.2):
+ *     peaks loop export --loop <id> --out <path.tar.gz>
+ *     peaks loop import --in <path.tar.gz> [--as <loop-id>]
+ *
+ * `peaks loop export` reads the source loop_release + relations +
+ * related bees + evidence briefs and emits a `peaks.bundle/1`
+ * tar.gz. Hard-blocks when the source has `shareable=false`.
+ *
+ * `peaks loop import` extracts a bundle, validates
+ * format_version_major=1, and lands the release as `candidate`
+ * (mandatory landing status per spec §7A.2). The receiver must run
+ * an independent evaluation before promoting to `stable`.
+ *
+ * The existing 14.x commands are kept under the same `loop` parent;
+ * M7 only ADDs export / import — it does not modify the existing
+ * surface.
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { writeBundle, BundleNotShareableError, BundleAssetNotFoundError, } from '../../services/share/bundle-writer.js';
+import { readBundle, BundleMajorVersionMismatchError, BundleSchemaVersionsMismatchError, BundleImportToStableForbiddenError, BundleMalformedError, } from '../../services/share/bundle-reader.js';
+export function registerLoopCommands(program, io) {
+    // 14.5 peaks goal compose — registered as a TOP-LEVEL command (not under
+    // `peaks loop`) because IDE adapters expose it as `goalCommand`.
+    // The sub-agent dispatch path consumes it; the slice 0.7 hermes +
+    // openclaw adapters will thread it through.
+    addJsonOption(program
+        .command('goal')
+        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--goal <text>', 'the high-level goal to compose')).action(async (options) => {
+        try {
+            printResult(io, ok('goal.compose', {
+                project: options.project,
+                goal: options.goal,
+                status: 'placeholder',
+                nextSteps: [
+                    'The composed goal is consumed by peaks sub-agent dispatch.',
+                    'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.',
+                ],
+            }, [], [
+                'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop *
+    const loop = program.command('loop').description('Slice #14: L4 Agent Loop sub-features (distill / preflight / detect-pattern / check-consistency)');
+    // 14.1 distill
+    addJsonOption(loop.command('distill')
+        .description('14.1: distill patterns from past sessions into .peaks/memory/ (delegates to peaks memory extract)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write extracted memories to .peaks/memory/ (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const apply = options.apply === true;
+            // Delegate to the existing peaks memory extract CLI via dynamic
+            // import (avoids circular); the LLM-side UX layer composes the
+            // two commands.
+            const { execFileSync } = await import('node:child_process');
+            const args = ['memory', 'extract', '--project', options.project];
+            if (apply)
+                args.push('--apply');
+            const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
+                cwd: options.project,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).toString('utf-8');
+            printResult(io, ok('loop.distill', {
+                project: options.project,
+                apply,
+                delegateStdout: stdout.slice(0, 200),
+            }, [], [
+                apply ? 'peaks memory extract --apply was invoked' : 'peaks memory extract dry-run was invoked',
+                'A future slice will inline the memory extract (not via execFileSync).',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('loop.distill', 'LOOP_DISTILL_FAILED', getErrorMessage(error), { project: options.project }, ['Verify the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // 14.2 preflight
+    addJsonOption(loop.command('preflight')
+        .description('14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.preflight', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
+                'A future slice will inline the preflight checks (not just placeholder).',
+            ],
+        }, [], [
+            'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.',
+        ]), options.json);
+    });
+    // 14.3 detect-pattern
+    addJsonOption(loop.command('detect-pattern')
+        .description('14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.detect-pattern', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
+                'A future slice will rank by frequency + LLM confidence.',
+            ],
+        }, [], [
+            'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.',
+        ]), options.json);
+    });
+    // 14.4 check-consistency
+    addJsonOption(loop.command('check-consistency')
+        .description('14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.check-consistency', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
+                'A future slice will report drift with severity (warn / fail).',
+            ],
+        }, [], [
+            'loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.',
+        ]), options.json);
+    });
+    // ---------- M7: peaks loop export / import (spec §7A.2) ----------
+    const LOOP_EXPORT_IMPORT_OPTS = (cmd) => cmd
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--json', 'print machine-readable JSON envelope');
+    LOOP_EXPORT_IMPORT_OPTS(loop
+        .command('export')
+        .description("M7: export a loop_release as a peaks.bundle/1 tarball (spec §7A.2 / §10 RL-9). Refuses to export when shareable=false.")
+        .requiredOption('--loop <id>', 'loop_release id (kebab-case)')
+        .requiredOption('--out <path>', 'output .tar.gz path')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+            }
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+            try {
+                const result = writeBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    kind: 'loop',
+                    id: options.loop,
+                    outPath: options.out,
+                });
+                printResult(io, ok('loop.export', {
+                    outPath: result.outPath,
+                    kind: result.kind,
+                    assetId: result.assetId,
+                    importedAs: 'candidate',
+                }, [], [
+                    `Receiver must run \`peaks loop import --in ${result.outPath}\` to land this bundle, then run an independent evolution_evaluation before any promote.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleNotShareableError) {
+                printResult(io, fail('loop.export', error.code, error.message, { ok: false, loop: options.loop }, [
+                    'Set shareable=true on the loop_release row, or share via desktop_visible=false.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleAssetNotFoundError) {
+                printResult(io, fail('loop.export', error.code, error.message, { ok: false, loop: options.loop }, [
+                    'Verify the loop id with `peaks asset status --loop <id>`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('loop.export', 'LOOP_EXPORT_FAILED', getErrorMessage(error), { ok: false, loop: options.loop }, ['Verify --loop id and --out path.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+    LOOP_EXPORT_IMPORT_OPTS(loop
+        .command('import')
+        .description("M7: import a peaks.bundle/1 tarball. Lands as candidate only — promotion requires an evolution_evaluation row (spec §7A.2 / §10 RL-9 / AC-25 / AC-26).")
+        .requiredOption('--in <path>', 'input .tar.gz path')
+        .option('--as <id>', 'optional rename for the loop id when landing')).action((options) => {
+        const asJson = options.json === true;
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
+            }
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
+            try {
+                const result = readBundle({
+                    db,
+                    blobsDir: join(projectRoot, '.peaks', 'blobs'),
+                    inPath: options.in,
+                    ...(options.as !== undefined ? { asName: options.as } : {}),
+                });
+                printResult(io, ok('loop.import', {
+                    assetId: result.assetId,
+                    kind: result.kind,
+                    importedAs: result.importedAs,
+                    warnings: result.warnings,
+                    evidenceBriefCount: result.evidenceBriefCount,
+                }, result.warnings, [
+                    `Run an independent evaluation against this release before promoting; peaks loop promote refuses without an evolution_evaluation row.`,
+                ]), asJson);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch (error) {
+            if (error instanceof BundleMajorVersionMismatchError) {
+                printResult(io, fail('loop.import', error.code, error.message, { ok: false, receivedMajor: error.receivedMajor }, [
+                    'Use the matching peaks.bundle/<major> reader; this peaks build only supports major=1.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleSchemaVersionsMismatchError) {
+                printResult(io, fail('loop.import', error.code, error.message, { ok: false }, [
+                    'Source bundle did not declare the canonical schema versions; refuse the bundle.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleImportToStableForbiddenError) {
+                printResult(io, fail('loop.import', error.code, error.message, { ok: false }, [
+                    'Bundles always land as candidate; promotion to stable requires an evolution_evaluation row (AC-26).',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof BundleMalformedError) {
+                printResult(io, fail('loop.import', error.code, error.message, { ok: false, inPath: options.in }, [
+                    'Re-export from the source via `peaks loop export`.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('loop.import', 'LOOP_IMPORT_FAILED', getErrorMessage(error), { ok: false, inPath: options.in }, ['Verify the bundle path and integrity.']), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,20 @@
+/**
+ * peaks-workflow v3.0.0 — Slice A.3 + Slice B.2
+ *
+ * CLI surface for the workflow primitive + the loop evaluator dispatcher.
+ *
+ * New commands (added under the existing `peaks workflow` group and the
+ * existing `peaks loop` group — never as new top-level commands, per the
+ * peaks-loop add-a-new-subcommand-check-for-existing-top-level-first rule):
+ *
+ *   peaks workflow run <id> --session <sid> --project <repo> --json
+ *   peaks workflow plan <id> --session <sid> --json   (dry-run)
+ *   peaks workflow lint <id> --session <sid> --json
+ *   peaks loop eval <rid> --evaluator <name> [--project <repo>] [--json]
+ *
+ * Karpathy §2: separate file from workflow-commands.ts to stay under
+ * the 800-line budget.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerWorkflowEvalCommands(program: Command, io: ProgramIO): void;