peaks-loop 4.0.0-beta → 4.0.0-beta.10

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

@@ -0,0 +1,155 @@
+import { existsSync } from 'node:fs';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { PolyrepoService } from '../../services/polyrepo/polyrepo-service.js';
+function parseChildren(raw) {
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function resolveRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerPolyrepoCommands(program, io) {
+    const polyrepo = program
+        .command('polyrepo')
+        .description('Polyrepo workflow (parent dir + child git repos with their own .peaks/ subsets)');
+    // -----------------------------------------------------------------
+    // 1. peaks polyrepo init [--children <dir1,dir2>] [--root <dir>]
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('init')
+        .description('Scan the parent dir for child git repos and write .peaks/polyrepo.json')
+        .option('--children <list>', 'comma-separated child directory names (defaults to auto-discovery)')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const svc = new PolyrepoService();
+            const children = parseChildren(options.children);
+            const result = children === undefined
+                ? svc.init({ root })
+                : svc.init({ root, children });
+            printResult(io, ok('polyrepo.init', {
+                root: result.manifest.root,
+                detectedAt: result.manifest.detectedAt,
+                children: result.manifest.children,
+                manifestPath: `${result.manifest.root}/.peaks/polyrepo.json`,
+                created: result.created
+            }, [], [
+                result.manifest.children.length === 0
+                    ? 'No child git repos detected. Pass --children <dir1,dir2> to override.'
+                    : `Run \`peaks polyrepo dispatch --rid <rid> --to <child-id>\` to mirror an artifact into one or more children.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.init', 'POLYREPO_INIT_FAILED', getErrorMessage(error), {}, ['Verify --root exists and is a directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks polyrepo status [--root <dir>]
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('status')
+        .description('Report the persisted polyrepo manifest + children')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const svc = new PolyrepoService();
+            const result = svc.status(root);
+            if (!result.manifestExists) {
+                printResult(io, ok('polyrepo.status', { ...result, initialized: false }, [], [
+                    'No polyrepo manifest found. Run `peaks polyrepo init [--children <list>]` first.'
+                ]), options.json);
+                return;
+            }
+            printResult(io, ok('polyrepo.status', { ...result, initialized: true }, [], [
+                result.children.length === 0
+                    ? 'Manifest exists but has no children. Re-run `peaks polyrepo init --children <list>`.'
+                    : `Run \`peaks polyrepo dispatch --rid <rid> --to <child-id>\` to mirror an artifact.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.status', 'POLYREPO_STATUS_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks polyrepo dispatch --rid <rid> [--to <child-id>] --role <prd|rd|qa> --artifact <path>
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('dispatch')
+        .description('Mirror a PRD/RD/QA artifact from the parent into one or more children')
+        .requiredOption('--rid <rid>', 'request id (used in the on-disk filename)')
+        .option('--to <list>', 'comma-separated child ids (defaults to all children in the manifest)')
+        .requiredOption('--role <role>', 'artifact role: prd | rd | qa')
+        .requiredOption('--artifact <path>', 'source artifact path (relative to --root or absolute)')
+        .option('--sid <sid>', 'session id override (defaults to the canonical binding)')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const sid = options.sid ?? 'default';
+            const rid = options.rid ?? '';
+            const role = options.role;
+            if (role !== 'prd' && role !== 'rd' && role !== 'qa') {
+                printResult(io, fail('polyrepo.dispatch', 'INVALID_ROLE', `--role must be prd | rd | qa (got "${role}")`, {}, [
+                    'Re-run with --role prd (or rd / qa).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const artifact = options.artifact ?? '';
+            if (!existsSync(artifact)) {
+                printResult(io, fail('polyrepo.dispatch', 'ARTIFACT_NOT_FOUND', `source artifact does not exist: ${artifact}`, {}, [
+                    'Verify the path or pass an absolute path.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve targets from the manifest first so we can default to
+            // "all children" when --to is omitted.
+            const svc = new PolyrepoService();
+            const status = svc.status(root);
+            if (!status.manifestExists) {
+                printResult(io, fail('polyrepo.dispatch', 'NO_MANIFEST', `no polyrepo manifest at ${root}/.peaks/polyrepo.json`, {}, [
+                    'Run `peaks polyrepo init` first.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let targets;
+            if (options.to !== undefined && options.to.length > 0) {
+                targets = options.to.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            }
+            else {
+                targets = status.children.map((c) => c.id);
+            }
+            const result = svc.dispatch(root, {
+                sid, rid, targets, role, artifactPath: artifact
+            });
+            const allOk = result.perChild.every((c) => c.ok);
+            printResult(io, ok('polyrepo.dispatch', {
+                root,
+                sid,
+                rid,
+                role,
+                artifact,
+                dispatch: result.dispatch,
+                perChild: result.perChild,
+                allOk
+            }, result.warnings, [
+                allOk
+                    ? `Mirrored artifact to ${result.perChild.length} child(ren).`
+                    : `One or more child mirrors failed; inspect perChild[].ok.`
+            ]), options.json);
+            if (!allOk)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.dispatch', 'POLYREPO_DISPATCH_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,253 @@
+import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
+import { extractSessionMemories, readMemoryIndex, readProjectMemories, readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
+import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerProjectCommands(program, io) {
+    const project = program.command('project').description('Aggregate Peaks state for a target project (read-only)');
+    addJsonOption(project
+        .command('dashboard')
+        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / Understand Anything / capabilities for a project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--strict', 'ok follows the doctor aggregate (legacy semantics). Default: workspace-only (ok tracks the runbook health)', false)).action(async (options) => {
+        try {
+            const dashboard = await loadProjectDashboard({
+                projectRoot: options.project,
+                okPolicy: options.strict === true ? 'strict' : 'workspace-only'
+            });
+            if (!dashboard.runbookHealth.ok) {
+                const suggestions = [
+                    dashboard.runbookHealth.missingRunbook.length > 0
+                        ? `Add a ## Default runbook section to: ${dashboard.runbookHealth.missingRunbook.join(', ')}`
+                        : null,
+                    dashboard.runbookHealth.applyNoteFailed.length > 0
+                        ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${dashboard.runbookHealth.applyNoteFailed.join(', ')}`
+                        : null
+                ].filter((line) => line !== null);
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${dashboard.runbookHealth.healthy}/${dashboard.runbookHealth.required} healthy`, dashboard, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (dashboard.skillPresence.active && !dashboard.skillPresence.fresh) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_STALE_SKILL_PRESENCE', `Active Peaks skill presence ${dashboard.skillPresence.skill ?? '<unknown>'} is stale (set ${dashboard.skillPresence.setAt ?? '<unknown>'})`, dashboard, ['Run `peaks skill presence:clear` if the role has ended, or `peaks skill presence:set <skill>` to refresh it']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!dashboard.doctor.ok && options.strict === true) {
+                printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_STRICT_FAIL', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed) — --strict mode requires the doctor aggregate to pass`, dashboard, ['Run `peaks doctor --json` and resolve the failing checks, or drop --strict to use the workspace-only policy']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('project.dashboard', dashboard), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(project
+        .command('context')
+        .description('Generate or read persistent project context for cross-session Peaks understanding. Generates BOTH `.peaks/PROJECT.md` (session history) AND `.peaks/project-scan/project-scan.md` (tech stack + archetypes) — see `peaks workspace init` for the full 5-template boot (G4b/AC9).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--read', 'read existing PROJECT.md without regenerating')).action(async (options) => {
+        try {
+            if (options.read) {
+                const content = readProjectContext(options.project);
+                if (content === null) {
+                    printResult(io, ok('project.context', { exists: false, path: `${options.project}/.peaks/PROJECT.md` }), options.json);
+                    return;
+                }
+                printResult(io, ok('project.context', { exists: true, path: `${options.project}/.peaks/PROJECT.md`, content }), options.json);
+                return;
+            }
+            const result = await generateProjectContext(options.project);
+            printResult(io, ok('project.context', {
+                path: result.path,
+                sessionCount: result.sessionCount,
+                content: result.content,
+                // Slice 2026-07-15-project-scan-bootstrap (G1 + G2): the
+                // context command also bootstraps the project-scan tree.
+                // The envelope surfaces write counts + duration so the LLM
+                // (and the user) see what landed.
+                projectScan: result.projectScan
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.context', 'PROJECT_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Extract memories from a session's artifacts into .peaks/memory ---
+    addJsonOption(project
+        .command('memories:extract')
+        .description('Scan a session artifact directory and extract <!-- peaks-memory:start --> blocks into .peaks/memory/')
+        .requiredOption('--session-id <id>', 'session id (e.g. 2026-05-29-session-89ff35)')
+        .requiredOption('--project <path>', 'target project root')
+        // Slice #015: drop the `--dry-run true` default. With the default
+        // set to true, `options.dryRun === true && options.apply === true`
+        // fired on every `--apply` call (because dryRun was true by
+        // default), permanently breaking `--apply`. `--dry-run` is now
+        // opt-in; the mutual-exclusion check below is correct without a
+        // special-case.
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into .peaks/memory/')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('project.memories:extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', { sessionId: options.sessionId, projectRoot: options.project }, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = extractSessionMemories({
+                projectRoot: options.project,
+                sessionId: options.sessionId,
+                apply: options.apply === true
+            });
+            printResult(io, ok('project.memories:extract', {
+                scannedFiles: result.scannedFiles,
+                extractedCount: result.extractedCount,
+                writtenFiles: result.writtenFiles,
+                memoryDir: result.primaryMemoryDir,
+                indexUpdated: result.updatedIndex
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), { sessionId: options.sessionId, projectRoot: options.project }, ['Check the session-id and project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Read memory index (lightweight, always-safe to load) ---
+    addJsonOption(project
+        .command('memory-index')
+        .description('Read the memory index — lightweight hot/warm分层 view of all project memories')
+        .requiredOption('--project <path>', 'target project root')).action((options) => {
+        try {
+            const index = readMemoryIndex(options.project);
+            if (!index) {
+                printResult(io, ok('project.memory-index', { exists: false, message: 'No memory index found. Run `peaks project memories:extract` first.' }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memory-index', { exists: true, index }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memory-index', 'MEMORY_INDEX_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Structured project memory (durable, LLM-authored, stored under .peaks/memory) ---
+    addJsonOption(project
+        .command('memories')
+        .description('Read durable project memories (decisions, conventions, modules, rules) from .peaks/memory for LLM consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--kind <kind>', 'filter by kind: project, rule, decision, reference, feedback, convention, module, lesson')).action((options) => {
+        try {
+            const result = readProjectMemories(options.project);
+            if (options.kind) {
+                const memories = result.memories.filter((memory) => memory.kind === options.kind);
+                printResult(io, ok('project.memories', {
+                    memoryDir: result.memoryDir,
+                    kind: options.kind,
+                    total: memories.length,
+                    memories
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('project.memories', {
+                memoryDir: result.memoryDir,
+                total: result.total,
+                byKind: result.byKind,
+                memories: result.memories
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories', 'PROJECT_MEMORIES_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Show one project memory's body (R3: default = compact) ---
+    addJsonOption(project
+        .command('memories:show <name>')
+        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
+        .option('--include-stale', 'include stale entries (the default excludes them)')
+        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => {
+        try {
+            const memory = readProjectMemoryBody(options.project, name);
+            if (memory === null) {
+                printResult(io, fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: options.project }, ['Run `peaks project memories --json` to see available names']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Compute the stale decision. R4: stale is computed at CLI load time
+            // only; the source `.md` file is never modified.
+            const updatedAt = memory.updatedAt;
+            const thresholdDays = options.staleDays !== undefined && Number.isFinite(options.staleDays) && options.staleDays > 0
+                ? options.staleDays
+                : DEFAULT_STALE_DAYS;
+            const policy = applyStalePolicy([{ name: memory.name, updatedAt }], {
+                thresholdDays,
+                includeStale: options.includeStale === true
+            });
+            if (policy.entries.length === 0) {
+                const ageDays = policy.entries.length === 0 && policy.droppedCount > 0
+                    ? applyStalePolicy([{ name: memory.name, updatedAt }], { thresholdDays, includeStale: true }).entries[0]?.ageDays ?? 0
+                    : 0;
+                printResult(io, fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, ['Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const ageDays = policy.entries[0]?.ageDays ?? 0;
+            const isStale = policy.entries[0]?.stale ?? false;
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
+            printResult(io, ok('project.memories:show', {
+                name: memory.name,
+                title: memory.title,
+                kind: memory.kind,
+                sourcePath: memory.filePath,
+                updatedAt,
+                ageDays,
+                stale: isStale,
+                body,
+                format,
+                bodyBytes: Buffer.byteLength(body, 'utf8')
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // --- Read business-knowledge sediment (v2.11.0 Group B — D3) ---
+    addJsonOption(project
+        .command('knowledge')
+        .description('Read .peaks/project-scan/business-knowledge.md (the schema-sedimented concept table). LLM-consumable; use --filter for a concept substring.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--filter <glob>', 'substring filter on the concept name (case-insensitive)')).action(async (options) => {
+        try {
+            const knowledge = await readBusinessKnowledge(options.project);
+            if (knowledge === null) {
+                printResult(io, ok('project.knowledge', { exists: false, projectRoot: options.project, path: `${options.project}/.peaks/project-scan/business-knowledge.md` }), options.json);
+                return;
+            }
+            const concepts = options.filter
+                ? knowledge.concepts.filter((c) => c.concept.toLowerCase().includes(options.filter.toLowerCase()))
+                : knowledge.concepts;
+            printResult(io, ok('project.knowledge', {
+                exists: true,
+                schemaVersion: knowledge.schemaVersion,
+                total: knowledge.concepts.length,
+                matched: concepts.length,
+                filter: options.filter ?? null,
+                concepts
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('project.knowledge', 'PROJECT_KNOWLEDGE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/project-scan directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,52 @@
+/**
+ * `peaks runtime *` — vendor-runtime detection + compact CLI surface.
+ *
+ * Slice S2-a of RD-2 (2026-07-08 session). Four subcommands:
+ *
+ *   detect    — print which vendor is the active AI runtime
+ *               (claude-code / codex / copilot / unknown).
+ *   list      — list the built-in vendor adapters registered by
+ *               RuntimeService (Claude Code / Codex / Copilot).
+ *   compact   — invoke a vendor's compact verb via the adapter. The
+ *               adapter (NOT this file) chooses the vendor verb;
+ *               see src/services/runtime/vendors/<vendor>.ts.
+ *
+ * Vendor verb strings (`claude --compact`, `codex --compact`,
+ * `copilot compact`) MUST live ONLY in `src/services/runtime/vendors/`
+ * — verified by AC-1: `rg -n "claude --compact|codex --compact|copilot
+ * compact" src/services/code/` returns 0 matches.
+ *
+ * `peaks runtime compact --via <id>` first consults the user
+ * adapter registry (`.peaks/runtime/adapters.json`) for the id, then
+ * falls back to the built-in adapter list. Missing vendor CLI
+ * surfaces as exitCode=127 + warning, NOT as a fatal error — vendor
+ * neutrality demands peaks-loop stay alive.
+ */
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RuntimeDetectOptions {
+    json?: boolean;
+}
+export interface RuntimeListOptions {
+    json?: boolean;
+}
+export interface RuntimeCompactOptions {
+    json?: boolean;
+    /** Vendor adapter id (built-in or registered). */
+    via?: string;
+    force?: boolean;
+    /** Override the project root (defaults to .peaks runtime lookup). */
+    project?: string;
+}
+export declare function registerRuntimeCommands(program: Command, io: ProgramIO): void;
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export declare function ensureRegistryDir(registryFile: string): void;
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export declare function registryFileFor(projectRoot: string): string;
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };

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

@@ -0,0 +1,150 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { getErrorMessage } from '../../shared/result.js';
+import { detectRuntime } from '../../services/runtime/runtime-detector.js';
+import { RuntimeService } from '../../services/runtime/runtime-service.js';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+function resolveProjectRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerRuntimeCommands(program, io) {
+    const runtime = program
+        .command('runtime')
+        .description('Vendor runtime detection + compact via adapter (--via <vendor-id>)');
+    // -----------------------------------------------------------------
+    // 1. peaks runtime detect [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('detect')
+        .description('Print the active AI runtime vendor (claude-code / codex / copilot / unknown)')).action((options) => {
+        try {
+            const result = detectRuntime();
+            printResult(io, ok('runtime.detect', result, [], [
+                result.vendor === 'unknown'
+                    ? 'No vendor sentinel detected. Use `peaks adapter register --id <vendor> --binary <cmd>` to wire a custom one.'
+                    : `Run \`peaks runtime compact --via ${result.vendor}\` to invoke its compact verb.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.detect', 'RUNTIME_DETECT_FAILED', getErrorMessage(error), {}, ['Retry with a clean env']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks runtime list [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('list')
+        .description('List the built-in vendor adapters registered by RuntimeService')).action((options) => {
+        try {
+            const svc = new RuntimeService();
+            const adapters = svc.listBuiltInAdapters().map((a) => ({ id: a.id, displayName: a.displayName }));
+            printResult(io, ok('runtime.list', { builtIn: adapters }, [], [
+                `Run \`peaks adapter register --id <vendor> --binary <cmd>\` to add a custom adapter (persists to .peaks/runtime/adapters.json).`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.list', 'RUNTIME_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks runtime compact [--via <id>] [--force] [--json] [--project <root>]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('compact')
+        .description('Compact the active vendor via the chosen adapter (--via <vendor-id>); vendor verbs live ONLY in adapter files')
+        .option('--via <id>', 'vendor adapter id (built-in or user-registered)')
+        .option('--force', 'ask the vendor to compact unconditionally')
+        .option('--project <path>', 'project root (defaults to cwd)')).action(async (options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const requested = options.via;
+            if (requested === undefined || requested.length === 0) {
+                // No explicit --via: try to detect first, then fall back.
+                const detected = detectRuntime();
+                if (detected.vendor === 'unknown') {
+                    printResult(io, fail('runtime.compact', 'NO_VENDOR_SPECIFIED', 'No --via <id> provided and no vendor detected.', { detected }, [
+                        'Pass --via <vendor-id>, or run `peaks runtime detect` to see what was detected.'
+                    ]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                await runCompact(projectRoot, detected.vendor, options.force === true, io, options.json);
+                return;
+            }
+            await runCompact(projectRoot, requested, options.force === true, io, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.compact', 'RUNTIME_COMPACT_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+async function runCompact(projectRoot, viaId, force, io, asJson) {
+    // Layer 1: user-registered adapter (via AdapterRegistry).
+    const registryFile = AdapterRegistry.defaultFile(projectRoot);
+    const registry = new AdapterRegistry();
+    if (existsSync(registryFile)) {
+        try {
+            registry.load(registryFile);
+        }
+        catch { // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
+            // Treat corrupt registry as empty — vendor-neutrality: a corrupt
+            // .peaks/runtime/adapters.json must NOT block peaks runtime.
+            // We still try the built-in path below.
+        }
+    }
+    const registered = registry.resolve(viaId);
+    if (registered !== undefined) {
+        const r = await registered.compact({ force });
+        const warnings = [];
+        if (r.exitCode === 127) {
+            warnings.push(`binary for adapter "${viaId}" not found on PATH; compact is a no-op`);
+        }
+        printResult(io, ok('runtime.compact', { via: viaId, source: 'registry', compact: r }, warnings, [
+            r.exitCode === 0
+                ? 'Compact completed.'
+                : `Compact exited with code ${r.exitCode}. Check stderr above.`
+        ]), asJson);
+        if (r.exitCode !== 0)
+            process.exitCode = 1;
+        return;
+    }
+    // Layer 2: built-in adapter (via RuntimeService).
+    const svc = new RuntimeService();
+    const r = await svc.compactVia(viaId, force);
+    const warnings = [];
+    if (r.warning !== undefined)
+        warnings.push(r.warning);
+    if (r.exitCode === 127) {
+        warnings.push(`built-in adapter "${viaId}" binary not found on PATH; compact is a no-op`);
+    }
+    printResult(io, ok('runtime.compact', { via: viaId, source: 'built-in', compact: { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr } }, warnings, [
+        r.exitCode === 0
+            ? 'Compact completed.'
+            : `Compact exited with code ${r.exitCode}. Check stderr above.`
+    ]), asJson);
+    if (r.exitCode !== 0)
+        process.exitCode = 1;
+}
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export function ensureRegistryDir(registryFile) {
+    mkdirSync(dirname(registryFile), { recursive: true });
+}
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export function registryFileFor(projectRoot) {
+    const f = AdapterRegistry.defaultFile(projectRoot);
+    ensureRegistryDir(f);
+    return f;
+}
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };