peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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

@@ -0,0 +1,114 @@
+import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { writeContract } from '../../services/dispatch/contract-store.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+const INPUT_LIMIT_BYTES = 256 * 1024;
+/** Split a comma-separated flag value into a trimmed string array. */
+function splitCsv(value) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerContractCommands(program, io) {
+    const contract = program
+        .command('contract')
+        .description('Slice contract store (skill-first / CLI-auxiliary). These commands ' +
+        'are primitives that peaks-code / peaks-rd SKILL.md compose. The LLM-side ' +
+        'runner (the IDE-resident sub-agent that finished a slice) calls ' +
+        '`peaks contract write` to persist the slice\'s public surface; the ' +
+        'orchestrator picks it up on the next dispatch run via listContracts() ' +
+        'and splices it into downstream prompts via formatContractInjection().');
+    // ─────────────────────────────────────────────────────────────────
+    // peaks contract write --project <root> --session-id <sid>
+    //   --slice-id <id> --exports <a,b> --types <x,y> --signatures <s1,s2>
+    //   [--broadcast-to <b1,b2>] [--completed-at <iso>]
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(contract
+        .command('write')
+        .description('2.7.0 slice-dag-dispatcher MVP: persist a finished slice\'s public ' +
+        'surface (exports / types / publicSignatures) to disk at ' +
+        '.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json. ' +
+        'The orchestrator picks it up on the next dispatch run. Idempotent: ' +
+        're-running with the same inputs overwrites in place; the SHA-256 ' +
+        'contractHash is content-derived so a contract write from a different ' +
+        'runner (re-execution) is detected as a content change.')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .requiredOption('--slice-id <id>', 'slice id; must be non-empty; used as the contract filename basename')
+        .option('--exports <list>', 'comma-separated public export names (e.g. "validateDag,topologicalLevels")')
+        .option('--types <list>', 'comma-separated public type names (e.g. "SliceDag,SliceNode")')
+        .option('--signatures <list>', 'comma-separated public function/method signatures (e.g. "validateDag(dag: SliceDag): void")')
+        .option('--broadcast-to <list>', 'comma-separated downstream slice ids that should auto-inherit this contract (e.g. "B,C,D")')
+        .option('--completed-at <iso>', 'ISO 8601 timestamp; defaults to now()')).action((options) => {
+        const asJson = options.json === true;
+        const projectRoot = options.project ?? process.cwd();
+        // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
+        const sid = options.sessionId
+            ?? process.env.PEAKS_SESSION_ID
+            ?? getCurrentSessionId(projectRoot)
+            ?? 'unknown-sid';
+        const sliceId = options.sliceId;
+        if (sliceId === undefined || sliceId.length === 0) {
+            printResult(io, fail('contract.write', 'MISSING_SLICE_ID', '--slice-id is required', { path: null, contract: null }, [
+                'Re-run with --slice-id <id> (must be non-empty; used as the contract filename basename).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const exports = splitCsv(options.exports);
+        const types = splitCsv(options.types);
+        const signatures = splitCsv(options.signatures);
+        const broadcastTo = splitCsv(options.broadcastTo);
+        // Cap the combined input to protect the file IO from runaway values
+        // (e.g. a 10MB comma-separated --signatures flag).
+        const inputSize = sliceId.length +
+            sid.length +
+            exports.join(',').length +
+            types.join(',').length +
+            signatures.join(',').length +
+            broadcastTo.join(',').length +
+            (options.completedAt?.length ?? 0);
+        if (inputSize > INPUT_LIMIT_BYTES) {
+            printResult(io, fail('contract.write', 'INPUT_TOO_LARGE', `combined input size ${inputSize} bytes exceeds ${INPUT_LIMIT_BYTES} (likely oversized --exports/--types/--signatures lists)`, { path: null, contract: null }, [
+                'Split the slice into smaller surfaces or omit optional fields.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const input = {
+                sliceId,
+                sessionId: sid,
+                exports,
+                types,
+                publicSignatures: signatures,
+                ...(broadcastTo.length > 0 ? { broadcastTo } : {}),
+                ...(options.completedAt !== undefined ? { completedAt: options.completedAt } : {})
+            };
+            const result = writeContract(projectRoot, sid, input);
+            printResult(io, ok('contract.write', {
+                path: result.path,
+                contractHash: result.contract.contractHash,
+                sliceId: result.contract.sliceId,
+                sessionId: result.contract.sessionId,
+                completedAt: result.contract.completedAt,
+                exportCount: result.contract.exports.length,
+                typeCount: result.contract.types.length,
+                signatureCount: result.contract.publicSignatures.length,
+                broadcastTo: result.contract.broadcastTo ?? []
+            }, [], [
+                `Contract written; orchestrator will pick it up on the next \`peaks sub-agent dispatch --from-dag\` run.`,
+                `Re-running with the same inputs is idempotent (overwrites in place).`
+            ]), asJson);
+        }
+        catch (err) {
+            printResult(io, fail('contract.write', 'WRITE_ERROR', getErrorMessage(err), { path: null, contract: null }, [
+                'See error message; check that --project is a writable directory and --slice-id is a valid filename basename (no path separators).'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/core/artifacts-command.d.ts

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

package/dist/cli/commands/core/artifacts-command.js

@@ -0,0 +1,62 @@
+import { createArtifactInitPlan, getArtifactStatus, createGuidedArtifactSetup } from '../../../services/artifacts/artifact-service.js';
+import { getArtifactWorkspaceStatus, planArtifactSync } from '../../../services/artifacts/workspace-service.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, failUnsupportedNonDryRun, isArtifactProvider, isArtifactSetupStep, printResult } from '../../cli-helpers.js';
+export function registerArtifactsCommand(program, io) {
+    const artifacts = program.command('artifacts').description('Manage intermediate artifact repositories');
+    addJsonOption(artifacts.command('status').description('Show artifact repository status')).action((options) => {
+        printResult(io, ok('artifacts.status', getArtifactStatus()), options.json);
+    });
+    addJsonOption(artifacts
+        .command('init')
+        .description('Plan remote-first artifact repository initialization')
+        .requiredOption('--provider <provider>', 'artifact provider: github or gitlab')
+        .requiredOption('--name <name>', 'remote repository name')
+        .option('--path <path>', 'local artifact working copy path', '.peaks-artifacts')
+        .option('--dry-run', 'preview without creating repositories or files', true)
+        .option('--no-dry-run', 'unsupported: do not create repositories or files from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'artifacts.init', options.json);
+            return;
+        }
+        if (!isArtifactProvider(options.provider)) {
+            printResult(io, fail('artifacts.init', 'UNSUPPORTED_ARTIFACT_PROVIDER', `Unsupported provider ${options.provider}`, {}, ['Use --provider github or --provider gitlab']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('artifacts.init', createArtifactInitPlan({
+            provider: options.provider,
+            name: options.name,
+            localPath: options.path,
+            dryRun: true
+        })), options.json);
+    });
+    addJsonOption(artifacts
+        .command('sync')
+        .description('Plan sync between local artifact workspace and remote repository')
+        .option('--workspace <id>', 'workspace identifier (uses current if not specified)')
+        .option('--dry-run', 'preview sync plan without executing', true)
+        .option('--no-dry-run', 'unsupported: do not sync from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'artifacts.sync', options.json);
+            return;
+        }
+        printResult(io, ok('artifacts.sync', planArtifactSync(options.workspace, true)), options.json);
+    });
+    addJsonOption(artifacts.command('workspace').description('Show artifact workspace status for current or specified workspace').option('--workspace <id>', 'workspace identifier')).action((options) => {
+        printResult(io, ok('artifacts.workspace', getArtifactWorkspaceStatus(options.workspace)), options.json);
+    });
+    addJsonOption(artifacts.command('setup').description('Interactive guided artifact repository setup').option('--step <step>', 'start from specific step: detect, configure, validate, complete')).action((options) => {
+        const requestedStep = options.step;
+        const setup = createGuidedArtifactSetup();
+        if (requestedStep) {
+            if (!isArtifactSetupStep(requestedStep)) {
+                printResult(io, fail('artifacts.setup', 'INVALID_ARTIFACT_SETUP_STEP', `Invalid artifact setup step ${requestedStep}`, {}, ['Use one of: detect, configure, validate, complete']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            setup.step = requestedStep;
+        }
+        printResult(io, ok('artifacts.setup', setup), options.json);
+    });
+}

package/dist/cli/commands/core/binding-commands.d.ts

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

package/dist/cli/commands/core/binding-commands.js

@@ -0,0 +1,58 @@
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { loadBindingStatus, formatTable, formatJson } from '../../../services/session/binding-status-service.js';
+import { fail, ok } from '../../../shared/result.js';
+// v2.18.2 PATCH scope (follow-up issues #2). Read-only introspection
+// CLI. Surface is intentionally minimal: one subcommand
+// (`peaks binding status`), two output modes (table + json), one
+// project-root override (`--project`). The `--stale` warning is
+// non-fatal: it prints to stderr and is also surfaced as a `stale`
+// field in the JSON envelope, so downstream automation can act on it
+// without parsing CLI prose.
+export function registerBindingCommands(program, io) {
+    const binding = program.command('binding').description('Inspect and manage the project-level binding store (v2.18.2)');
+    addJsonOption(binding
+        .command('status')
+        .description('Print the current binding-store contents (sids, callerIds, pids, lastHeartbeat, roles). Read-only.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--format <format>', 'output format: table (default for non-TTY) | json', 'table')).action((options) => {
+        const projectRoot = options.project ?? (findProjectRoot(process.cwd()) ?? process.cwd());
+        const view = loadBindingStatus(projectRoot);
+        // Mode resolution priority: --json flag beats --format. The
+        // double-flag form is intentional: `--json` keeps back-compat
+        // with the v2.18.0 doctor envelope shape, `--format json` is the
+        // explicit opt-in for users who want the table-by-default
+        // behaviour but script-friendly output.
+        const useJson = options.json === true || options.format === 'json';
+        const format = useJson ? 'json' : 'table';
+        if (useJson) {
+            const payload = formatJson(view);
+            const result = view.binding === null
+                ? ok('binding.status', { ...payload, note: 'no binding found; run `peaks workspace init --project <repo>` to create one' })
+                : ok('binding.status', payload);
+            printResult(io, result, true);
+        }
+        else {
+            if (view.binding === null) {
+                const result = fail('binding.status', 'NO_BINDING', 'no binding found for the project', { projectRoot }, [
+                    `Run \`peaks workspace init --project <repo>\` to create one`
+                ]);
+                printResult(io, result, false);
+                process.exitCode = 1;
+                return;
+            }
+            const table = formatTable(view);
+            if (table === '') {
+                io.stdout('  (binding has no instances)');
+            }
+            else {
+                io.stdout(table);
+            }
+            io.stdout(`\n  source: ${view.source}`);
+            io.stdout(`  instances: ${Object.keys(view.binding.instances).length}`);
+            if (view.stale) {
+                io.stderr(`\n  warning: current outer-session-id (${view.outerSessionId}) does not match any binding callerId; this binding is stale (v2.15.0 sticky-mode contract)`);
+            }
+        }
+    });
+}

package/dist/cli/commands/core/doctor-command.d.ts

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export type BindingSource = 'canonical' | 'legacy';
+export type DoctorLogsSection = {
+    logDir: string;
+    todayFile: string;
+    sizeBytes: number;
+    retentionDays: number;
+    level: string;
+};
+export declare function registerDoctorCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/core/doctor-command.js

@@ -0,0 +1,204 @@
+import { runDoctor } from '../../../services/doctor/doctor-service.js';
+import { readBinding, dropStale, rebuildBindingFromLegacy } from '../../../services/session/binding-store.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+import { fail, ok } from '../../../shared/result.js';
+// Slice v2.16.0 AC-10: stale binding TTL is 5 minutes by default. The
+// threshold is exposed as a CLI flag so users can tune it for
+// long-running sessions.
+const STALE_TTL_MS = 5 * 60 * 1000;
+// Slice v2.16.0 AC-10: identify stale instances (lastHeartbeat > 5min)
+// in the project-level binding. Used by `peaks doctor` and surfaced as
+// a warning in the report. Returns the stale entry descriptors.
+function listStaleInstances(projectRoot, ttlMs = STALE_TTL_MS) {
+    const binding = readBinding(projectRoot);
+    if (!binding)
+        return [];
+    const cutoff = Date.now() - ttlMs;
+    const stale = [];
+    for (const [sid, inst] of Object.entries(binding.instances)) {
+        const t = Date.parse(inst.lastHeartbeat);
+        if (Number.isFinite(t) && t < cutoff) {
+            stale.push({ sid, callerId: inst.callerId, lastHeartbeat: inst.lastHeartbeat });
+        }
+    }
+    return stale;
+}
+// Slice 2026-06-16-cli-logging (AC6) — `peaks doctor --log` section.
+//
+// `buildDoctorLogsSection` reads the on-disk log dir and returns the
+// metadata the doctor needs to render the "logs" block. It is
+// extracted from the inline `peaks doctor --log` action so the
+// command stays small and the helper is unit-testable without
+// spinning up the full program.
+async function buildDoctorLogsSection() {
+    // Lazy imports to avoid a circular dep at module-load time
+    // (core-artifact-commands is imported very early in program.ts).
+    const { resolveLogDir, buildLogFileName } = await import('../../../services/log/logger.js');
+    const { statSync, existsSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const logDir = resolveLogDir();
+    const todayFile = buildLogFileName(new Date());
+    const fullPath = join(logDir, todayFile);
+    let sizeBytes = 0;
+    if (existsSync(fullPath)) {
+        try {
+            sizeBytes = statSync(fullPath).size;
+        }
+        catch {
+            sizeBytes = 0;
+        }
+    }
+    return {
+        logDir,
+        todayFile,
+        sizeBytes,
+        retentionDays: 7,
+        level: process.env.PEAKS_LOG_LEVEL ?? 'info'
+    };
+}
+// Slice 2026-06-16-cli-logging (AC6): `peaks doctor --log` adds a
+// "logs" section to the doctor output (logDir, today's file name,
+// size, retention policy, level). Useful for the user when they
+// want to attach a quick log snapshot to a bug report without
+// running `peaks log tail` first. The flag is opt-in so the
+// existing doctor output is preserved (P4).
+export function registerDoctorCommand(program, io) {
+    addJsonOption(program
+        .command('doctor')
+        .description('Run repository doctor checks')
+        .option('--log', 'include a "logs" section in the doctor output (slice 2026-06-16-cli-logging, AC6)')
+        .option('--cleanup-stale', 'drop stale instance entries from the project-level binding (v2.16.0 AC-10)')
+        .option('--stale-ttl-ms <ms>', 'stale-binding TTL in milliseconds (default 300000 = 5 minutes, v2.16.0 AC-10)')
+        // v2.18.2 PATCH scope (follow-up issue #1): rewrite legacy
+        // v2.16.0 / v2.17.0 binding files in place so every existing
+        // callerId gets the `${envSignal}#${pid}` suffix introduced in
+        // v2.18.0. Mutually exclusive with --cleanup-stale to keep the
+        // semantics unambiguous (rebuild = structural change,
+        // cleanup-stale = TTL-based prune).
+        .option('--rebuild-binding', 'rewrite legacy v2.16.0 / v2.17.0 callerId entries to the v2.18.0+ `#${pid}` format (v2.18.2, follow-up issue #1)')
+        // v2.18.2 cycle 2: --project makes the project-root-bound
+        // flags (--rebuild-binding, --cleanup-stale, stale-binding
+        // scan) addressable for non-current projects. The doctor was
+        // hardcoded to findProjectRoot(process.cwd()) which is the
+        // wrong default for users inspecting a sibling project.
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (options) => {
+        // v2.18.2 cycle 2 (Q2 arbitration): --rebuild-binding and
+        // --cleanup-stale BOTH mutate the binding file. Running them
+        // together is ambiguous (rebuild rewrites callerIds; cleanup
+        // prunes entries). Hard-reject the combination so the user
+        // gets an actionable error instead of a silent short-circuit.
+        if (options.rebuildBinding === true && options.cleanupStale === true) {
+            const envelope = fail('doctor.rebuild-binding', 'CONFLICTING_FLAGS', '--rebuild-binding and --cleanup-stale are mutually exclusive', { rebuildBinding: true, cleanupStale: true }, ['Run them in separate `peaks doctor` invocations']);
+            printResult(io, envelope, options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        // v2.18.2 cycle 2: --project override, applies to BOTH the
+        // --rebuild-binding short-circuit AND the binding-stale scan.
+        const projectRoot = options.project !== undefined
+            ? options.project
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        // v2.18.2: short-circuit on --rebuild-binding so the doctor
+        // checks don't run when the user is asking for a single targeted
+        // migration. The rebuild is observable in its own right
+        // (rewritten/preserved counts) and does not benefit from running
+        // the full doctor surface first.
+        if (options.rebuildBinding === true) {
+            const result = rebuildBindingFromLegacy(projectRoot);
+            if (result.errors.length > 0) {
+                for (const err of result.errors) {
+                    io.stderr(`  warning: ${err}`);
+                }
+            }
+            const data = {
+                rebuilt: !result.noop,
+                rewritten: result.rewritten,
+                preserved: result.preserved,
+                errors: result.errors,
+                projectRoot
+            };
+            const envelope = result.rewritten === 0
+                ? ok('doctor.rebuild-binding', data, [], result.noop ? ['no legacy callerId entries found — nothing to rewrite'] : [])
+                : fail('doctor.rebuild-binding', result.noop ? 'BINDING_REBUILD_NOOP' : 'BINDING_REBUILD_OK', result.noop
+                    ? 'No legacy callerId entries to rewrite'
+                    : `Rewrote ${result.rewritten} legacy callerId entry/entries (preserved ${result.preserved})`, data, ['Re-run `peaks binding status` to verify the rewritten entries']);
+            printResult(io, envelope, options.json === true);
+            if (result.errors.length > 0 && result.rewritten === 0) {
+                process.exitCode = 1;
+            }
+            return;
+        }
+        const report = await runDoctor();
+        let logsSection = null;
+        if (options.log === true) {
+            logsSection = await buildDoctorLogsSection();
+        }
+        // v2.16.0 AC-10: scan binding for stale instances.
+        const ttl = options.staleTtlMs !== undefined ? Number(options.staleTtlMs) : STALE_TTL_MS;
+        const staleInstances = listStaleInstances(projectRoot, ttl);
+        let droppedStale = [];
+        if (options.cleanupStale === true) {
+            const { dropped } = dropStale(projectRoot, ttl);
+            droppedStale = dropped;
+        }
+        const staleBindingSection = {
+            ttlMs: ttl,
+            staleCount: staleInstances.length,
+            staleInstances,
+            droppedCount: droppedStale.length,
+            droppedSids: droppedStale
+        };
+        const data = logsSection === null
+            ? { ...report, staleBinding: staleBindingSection }
+            : { ...report, logs: logsSection, staleBinding: staleBindingSection };
+        const result = report.summary.ok && staleInstances.length === 0
+            ? ok('doctor', data)
+            : fail('doctor', 'DOCTOR_FAILED', staleInstances.length > 0
+                ? `Found ${staleInstances.length} stale binding instance(s); rerun with --cleanup-stale to drop them`
+                : 'One or more doctor checks failed', data, staleInstances.length > 0
+                ? ['Run `peaks doctor --cleanup-stale` to drop stale entries']
+                : ['Fix failed checks and rerun peaks doctor']);
+        if (options.json === true) {
+            printResult(io, result, true);
+        }
+        else {
+            // Human-readable: one line per check, green/red indicators, no JSON.
+            for (const check of report.checks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            if (logsSection !== null) {
+                io.stdout('\n  logs:');
+                io.stdout(`    logDir:        ${logsSection.logDir}`);
+                io.stdout(`    todayFile:     ${logsSection.todayFile}`);
+                io.stdout(`    sizeBytes:     ${logsSection.sizeBytes}`);
+                io.stdout(`    retentionDays: ${logsSection.retentionDays}`);
+                io.stdout(`    level:         ${logsSection.level}`);
+            }
+            io.stdout('\n  stale-binding (v2.16.0 AC-10):');
+            if (staleInstances.length === 0) {
+                io.stdout('    + no stale instances');
+            }
+            else {
+                io.stdout(`    × ${staleInstances.length} stale instance(s):`);
+                for (const s of staleInstances) {
+                    io.stdout(`      - sid=${s.sid} caller=${s.callerId} lastSeen=${s.lastHeartbeat}`);
+                }
+                if (droppedStale.length > 0) {
+                    io.stdout(`    cleaned up: ${droppedStale.length}`);
+                }
+                else {
+                    io.stdout('    rerun with --cleanup-stale to drop them');
+                }
+            }
+            io.stdout(`\n  ${report.summary.passed} passed, ${report.summary.failed} failed`);
+            if (!report.summary.ok || staleInstances.length > 0) {
+                io.stderr(`\nDOCTOR_FAILED: ${staleInstances.length > 0 ? 'stale binding present' : `${report.summary.failed} check(s) failed`}.`);
+            }
+        }
+        if (!report.summary.ok || staleInstances.length > 0) {
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/core/memory-command.d.ts

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

package/dist/cli/commands/core/memory-command.js

@@ -0,0 +1,98 @@
+import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../../services/memory/project-memory-service.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerMemoryCommand(program, io) {
+    const memory = program.command('memory').description('Manage project-local Peaks memory');
+    addJsonOption(memory
+        .command('extract')
+        .description('Extract stable project memory from skill artifacts into project .peaks/memory')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
+            printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('memory.extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), {}, ['Check artifact paths and remove secrets before extracting memory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(memory
+        .command('sync')
+        .description('Back up project .peaks/memory into the artifact workspace')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--workspace <path>', 'artifact workspace path')
+        .option('--dry-run', 'preview copies without changing files')
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.sync', 'INVALID_MEMORY_SYNC_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview copies, or pass --apply to back up memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: options.apply === true });
+            printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('memory.sync', 'MEMORY_SYNC_FAILED', getErrorMessage(error), {}, ['Use an artifact workspace outside the project root']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(memory
+        .command('list')
+        .description('List all memory entries from .peaks/memory/index.json. Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/memory/picked.json.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
+        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        void import('../memory-commands.js').then(({ runMemoryList }) => {
+            void runMemoryList(io, {
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.pick === true ? { pick: true } : {}),
+                ...(options.fzfBin ? { fzfBin: options.fzfBin } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            const msg = /brew install fzf|apt-get install fzf|older than required/.test(getErrorMessage(error))
+                ? 'fzf binary not found or too old. Install with: brew install fzf (or apt: apt-get install fzf). peaks memory list --pick requires fzf >= 0.38.'
+                : getErrorMessage(error);
+            const code = /brew install fzf|apt-get install fzf|older than required/.test(msg) ? 'FZF_UNAVAILABLE' : 'MEMORY_LIST_BOOTSTRAP_FAILED';
+            printResult(io, fail('memory.list', code, msg, {}, ['Install fzf or run without --pick to list entries as JSON']), options.json);
+            if (code === 'FZF_UNAVAILABLE')
+                process.exitCode = 127;
+            else
+                process.exitCode = 1;
+        });
+    });
+    addJsonOption(memory
+        .command('search <query>')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6. Pass --compress-results to also emit a headroom-compressed text view of the matches for LLM-side prompt assembly.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--compress-results', 'compress joined match text via headroom-ai (uses preferences.headroom.perTouchpoint.memorySearch mode)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        // Lazy import avoids a top-of-file import cycle (memory-commands.ts
+        // imports services that the rest of this file may also touch).
+        void import('../memory-commands.js').then(({ runMemorySearch }) => {
+            void runMemorySearch(io, {
+                query,
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.compressResults === true ? { compressResults: true } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.search', 'MEMORY_SEARCH_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
+}

package/dist/cli/commands/core/profile-command.d.ts

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

package/dist/cli/commands/core/profile-command.js

@@ -0,0 +1,9 @@
+import { listProfiles } from '../../../services/profiles/profile-service.js';
+import { ok } from '../../../shared/result.js';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+export function registerProfileCommand(program, io) {
+    const profile = program.command('profile').description('Manage runtime profiles');
+    addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
+        printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);
+    });
+}

package/dist/cli/commands/core/proxy-command.d.ts

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

package/dist/cli/commands/core/proxy-command.js

@@ -0,0 +1,26 @@
+import { planProxyTest } from '../../../services/proxy/proxy-service.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerProxyCommand(program, io) {
+    const proxy = program.command('proxy').description('Manage proxy settings');
+    addJsonOption(proxy
+        .command('test')
+        .description('Plan or run a proxy connectivity test')
+        .requiredOption('--proxy <url>', 'proxy URL')
+        .option('--target <url>', 'target URL', 'https://www.google.com')
+        .option('--dry-run', 'only print the planned command', true)
+        .option('--no-dry-run', 'unsupported: do not execute connectivity tests from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'proxy.test', options.json);
+            return;
+        }
+        try {
+            const plan = planProxyTest(options.proxy, options.target, true);
+            printResult(io, ok('proxy.test', plan), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('proxy.test', 'INVALID_PROXY', getErrorMessage(error), {}, ['Use a proxy URL starting with http:// or https://']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/core/session-command.d.ts

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