peaks-loop 4.1.2 → 4.1.3

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

@@ -0,0 +1,87 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { dryRunCompact } from '../../services/compact/suggest-service.js';
+import { PHASES, isPhase } from '../../services/compact/decision-tables.js';
+import { resolveSessionId } from './compact-shared.js';
+export function registerCompactDryRunCommand(compact, io) {
+    // -----------------------------------------------------------------
+    // 4. peaks compact dry-run [--from <phase>] [--to <phase>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('dry-run')
+        .description('Composite preview of (suggest + recommend + survival). ' +
+        'No writes. The LLM calls this every tool-call cycle to stay informed.')
+        .option('--from <phase>', `optional source phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--to <phase>', `optional target phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')).action((options) => runCompactDryRun(options, io));
+}
+function runCompactDryRun(options, io) {
+    try {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(projectRoot, options.sessionId);
+        if (session.error !== null) {
+            printCompactDryRunSessionError(session.error, projectRoot, io, options.json);
+            return;
+        }
+        if ((options.from === undefined) !== (options.to === undefined)) {
+            printCompactDryRunPhasePairIncomplete(options, io);
+            return;
+        }
+        if (options.from !== undefined && !isPhase(options.from)) {
+            printCompactDryRunInvalidFrom(options.from, io, options.json);
+            return;
+        }
+        if (options.to !== undefined && !isPhase(options.to)) {
+            printCompactDryRunInvalidTo(options.to, io, options.json);
+            return;
+        }
+        const hasPhasePair = options.from !== undefined && options.to !== undefined;
+        const dryRunInput = {
+            projectRoot,
+            sessionId: session.sid
+        };
+        if (hasPhasePair) {
+            dryRunInput.from = options.from;
+            dryRunInput.to = options.to;
+        }
+        const result = dryRunCompact(dryRunInput);
+        printCompactDryRunResult(result, io, options.json);
+    }
+    catch (error) {
+        reportCompactDryRunFailure(io, error, options.json);
+    }
+}
+function printCompactDryRunSessionError(error, projectRoot, io, json) {
+    printResult(io, fail('compact.dry-run', error.code, error.message, { projectRoot }, error.nextActions), json);
+    process.exitCode = 1;
+}
+function printCompactDryRunPhasePairIncomplete(options, io) {
+    printResult(io, fail('compact.dry-run', 'PHASE_PAIR_INCOMPLETE', 'Both --from and --to must be provided together', { from: options.from, to: options.to }, ['Pass both --from and --to, or omit both for a suggest-only dry-run']), options.json);
+    process.exitCode = 1;
+}
+function printCompactDryRunInvalidFrom(from, io, json) {
+    printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${from}")`, { from }, [`Use --from ${PHASES.join('|')}`]), json);
+    process.exitCode = 1;
+}
+function printCompactDryRunInvalidTo(to, io, json) {
+    printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${to}")`, { to }, [`Use --to ${PHASES.join('|')}`]), json);
+    process.exitCode = 1;
+}
+function printCompactDryRunResult(result, io, json) {
+    printResult(io, ok('compact.dry-run', result, [], [
+        result.action === 'compact'
+            ? `Action=compact: run \`peaks compact force --reason "<note>"\`, then /compact.`
+            : `Action=skip: continue without compacting.`
+    ]), json);
+}
+function reportCompactDryRunFailure(io, error, json) {
+    printResult(io, fail('compact.dry-run', 'COMPACT_DRY_RUN_FAILED', getErrorMessage(error), {}, [
+        'Verify project root, session binding, and phase pair before retrying'
+    ]), json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/compact-force-command.d.ts

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

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

@@ -0,0 +1,98 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { writeCheckpoint } from '../../services/session/session-checkpoint-service.js';
+import { resolveSessionId } from './compact-shared.js';
+const COMPACT_FORCE_NEXT_ACTIONS = [
+    'After the LLM fires the IDE-side /compact, call `peaks compact survival` to see what to persist before the next compact.'
+];
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerCompactForceCommand(compact, io) {
+    // -----------------------------------------------------------------
+    // 5. peaks compact force [--reason <text>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('force')
+        .description('Write a pre-compact checkpoint via `peaks session checkpoint --reason context-fill`. ' +
+        "The IDE-side `/compact` is still the LLM's call; this primitive guarantees " +
+        'the pre-compact state is persisted. NO sleep, NO wait for IDE response.')
+        .option('--reason <text>', 'human-readable reason for the pre-compact checkpoint', 'pre-force-compact')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')
+        .option('--current-plan <text>', 'current plan summary (forwarded to the checkpoint snapshot)')
+        .option('--open-questions <list>', 'newline-separated open questions')
+        .option('--recent-decisions <list>', 'newline-separated recent decisions')
+        .option('--recent-artifact-paths <list>', 'newline-separated recent artifact paths')
+        .option('--git-status <text>', 'recent git status')
+        .option('--skills-active <list>', 'newline-separated active skill names')
+        .option('--todo-state <list>', 'newline-separated todo lines')).action((options) => runCompactForce(options, io));
+}
+function runCompactForce(options, io) {
+    try {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(projectRoot, options.sessionId);
+        if (session.error !== null) {
+            printCompactForceSessionError(session.error, projectRoot, io, options.json);
+            return;
+        }
+        const reason = (options.reason ?? 'pre-force-compact').slice(0, 200);
+        // The session-checkpoint-service restricts `reason` to a fixed
+        // enum. The strategic-compact `force` primitive uses
+        // 'context-fill' (the closest semantic match: the LLM is
+        // compacting because of context pressure) and records the
+        // caller's free-form reason in `gitStatus` so the snapshot
+        // is self-describing without inventing a new enum value.
+        const checkpointOptions = {
+            sessionId: session.sid,
+            reason: 'context-fill',
+            gitStatus: `compact.force: ${reason}`,
+            openQuestions: splitList(options.openQuestions),
+            recentDecisions: splitList(options.recentDecisions),
+            recentArtifactPaths: splitList(options.recentArtifactPaths),
+            skillsActive: splitList(options.skillsActive),
+            todoState: splitList(options.todoState)
+        };
+        if (options.currentPlan !== undefined) {
+            checkpointOptions.currentPlan = options.currentPlan;
+        }
+        const result = writeCheckpoint(projectRoot, checkpointOptions);
+        printCompactForceResult(result, reason, io, options.json);
+    }
+    catch (error) {
+        reportCompactForceFailure(io, error, options.json);
+    }
+}
+function printCompactForceSessionError(error, projectRoot, io, json) {
+    printResult(io, fail('compact.force', error.code, error.message, { projectRoot }, error.nextActions), json);
+    process.exitCode = 1;
+}
+function buildCompactForceData(result, reason) {
+    return {
+        checkpointPath: result.path,
+        reason: 'pre-force-compact',
+        callerReason: reason,
+        sessionId: result.sessionId,
+        createdAt: result.createdAt,
+        totalRetained: result.totalRetained,
+        message: "Pre-compact checkpoint written. The IDE-side /compact is still the LLM's call; this CLI does NOT invoke the IDE slash command."
+    };
+}
+function printCompactForceResult(result, reason, io, json) {
+    printResult(io, ok('compact.force', buildCompactForceData(result, reason), [], COMPACT_FORCE_NEXT_ACTIONS), json);
+}
+function reportCompactForceFailure(io, error, json) {
+    printResult(io, fail('compact.force', 'COMPACT_FORCE_FAILED', getErrorMessage(error), {}, [
+        'Verify the project path is writable and a session is bound'
+    ]), json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/compact-harness-window-command.d.ts

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

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

@@ -0,0 +1,174 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readHarnessWindowState, resolveHarnessWindowLocation } from '../../services/context/auto-compact-reader.js';
+import { disableHarnessWindowSync, reenableHarnessWindowSync, resetHarnessWindow } from '../../services/context/harness-window-config.js';
+const HARNESS_WINDOW_DESCRIPTION = 'Report / roll back the auto-compact window peaks-loop writes into the ' +
+    "harness's own machine-local settings (the adapter-declared " +
+    'autoCompactWindowEnvVar, e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW in ' +
+    '.claude/settings.local.json). peaks-loop computes its context ratio ' +
+    'against exactly this number, so the value it reports as "85%" and the ' +
+    'point the harness compacts at are the same. Context probes ' +
+    '(`peaks code context-now`, `peaks code auto-compact`) materialize it ' +
+    'automatically. Two different intentions, two verbs: --reset removes ' +
+    'the key AND opts the project out so later probes do not put it back ' +
+    '(when the file holds no peaks-loop row at all there is nothing to ' +
+    'roll back, so --reset writes nothing); --disable records the opt-out ' +
+    'only, leaving whatever value is already there untouched, so "stop ' +
+    'managing this key" works on a project peaks-loop has never written ' +
+    'to; --reenable undoes either opt-out.';
+function resolveHarnessWindowProject(options) {
+    return options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+}
+function reportUnmanagedHarnessWindow(io, project, json) {
+    printResult(io, ok('compact.harness-window', {
+        projectRoot: project,
+        managed: false,
+        message: 'The active IDE adapter declares no auto-compact window key, so peaks-loop cannot tie ' +
+            'the harness window to its own ratio. Nothing was written and there is nothing to roll back.'
+    }), json);
+}
+function buildResetWindowActions(result, location) {
+    return [
+        result.action === 'removed'
+            ? `Removed ${location.envVar} from ${result.settingsPath} and opted this project out, so later probes stop writing it. Undo with \`peaks compact harness-window --reenable\`.`
+            : `Nothing to remove — ${location.envVar} was already absent from ${result.settingsPath}, so nothing was written and no opt-out row was recorded: if a probe writes a window here later, run --reset again to remove it. To say "never manage this key here" WITHOUT waiting for that first write, run \`peaks compact harness-window --disable\`.`
+    ];
+}
+function reportResetHarnessWindow(io, project, location, json) {
+    const result = resetHarnessWindow({ location, env: process.env });
+    printResult(io, ok('compact.harness-window', {
+        projectRoot: project,
+        action: result.action,
+        key: location.envVar,
+        settingsPath: result.settingsPath,
+        previousTokens: result.previousTokens
+    }, [], buildResetWindowActions(result, location)), json);
+}
+function buildDisableWindowActions(result, location) {
+    return [
+        result.action === 'disabled'
+            ? `Recorded the opt-out in ${result.settingsPath}: peaks-loop will not write ${location.envVar} here, and left any value already in the file exactly as it was. Undo with \`peaks compact harness-window --reenable\`.`
+            : result.action === 'already-opted-out'
+                ? `Already opted out — ${result.settingsPath} carries ${location.envVar}'s opt-out, so nothing was written. Undo with \`peaks compact harness-window --reenable\`.`
+                : result.action === 'refused-unsafe-project-root'
+                    ? `Nothing written: the resolved project root is the user's own home directory, so ${result.settingsPath} is their PERSONAL harness settings, not a project's. peaks-loop already refuses to write ${location.envVar} there, so an opt-out would change nothing except which refusal you see. Point --project at a project (a subdirectory of home is fine) and the opt-out lands there.`
+                    : `Nothing written — ${result.settingsPath} is not a JSON object peaks-loop can safely edit, so the opt-out could not be recorded there.`
+    ];
+}
+function reportDisableHarnessWindow(io, project, location, json) {
+    const result = disableHarnessWindowSync({ location });
+    printResult(io, ok('compact.harness-window', {
+        projectRoot: project,
+        action: result.action,
+        key: location.envVar,
+        settingsPath: result.settingsPath
+    }, [], buildDisableWindowActions(result, location)), json);
+}
+function buildReenableWindowActions(result) {
+    return [
+        result.action === 'reenabled'
+            ? 'Opt-out cleared; the next context probe will materialize the window again.'
+            : 'No opt-out was recorded for this project.'
+    ];
+}
+function reportReenableHarnessWindow(io, project, location, json) {
+    const result = reenableHarnessWindowSync({ location });
+    printResult(io, ok('compact.harness-window', {
+        projectRoot: project,
+        action: result.action,
+        key: location.envVar,
+        settingsPath: result.settingsPath
+    }, [], buildReenableWindowActions(result)), json);
+}
+function buildHarnessWindowStateActions(state) {
+    return [
+        state?.tokens === null || state?.tokens === undefined
+            ? 'No window is set yet. The next `peaks code context-now` probe materializes the window it computes its ratio against.'
+            : `peaks-loop computes its context ratio against ${state.tokens} tokens; the harness fires near the end of that window. ${state.peakWritten
+                ? 'peaks-loop wrote this value; it may raise it if a session outgrows it.'
+                : "This value is not peaks-loop's own write, so peaks-loop will not raise it — it is treated as your setting."}`,
+        'Rollback: `peaks compact harness-window --reset`.',
+        'Intent-vs-observed calibration: `peaks compact history --json` → windowCalibration.'
+    ];
+}
+function buildHarnessWindowStateData(project, location, state) {
+    return {
+        projectRoot: project,
+        managed: true,
+        key: location.envVar,
+        settingsPath: location.settingsPath,
+        tokens: state?.tokens ?? null,
+        raw: state?.raw ?? null,
+        source: state?.source ?? null,
+        optedOut: state?.optedOut ?? false,
+        // Provenance: whether this value is peaks-loop's own write or
+        // one the user set by hand. It decides whether the late 1M
+        // rescue may override it, so it is not just diagnostics.
+        peakWritten: state?.peakWritten ?? false
+    };
+}
+function reportHarnessWindowState(io, project, location, json) {
+    const state = readHarnessWindowState({ projectRoot: project, env: process.env });
+    printResult(io, ok('compact.harness-window', buildHarnessWindowStateData(project, location, state), [], buildHarnessWindowStateActions(state)), json);
+}
+function reportHarnessWindowFailure(io, error, json) {
+    printResult(io, fail('compact.harness-window', 'COMPACT_HARNESS_WINDOW_FAILED', getErrorMessage(error), {}, [
+        'Verify the project path is writable and a session is bound'
+    ]), json);
+    process.exitCode = 1;
+}
+function runCompactHarnessWindow(options, io) {
+    try {
+        const project = resolveHarnessWindowProject(options);
+        const location = resolveHarnessWindowLocation({
+            projectRoot: project,
+            env: process.env
+        });
+        if (location === null) {
+            reportUnmanagedHarnessWindow(io, project, options.json);
+            return;
+        }
+        if (options.reset === true) {
+            reportResetHarnessWindow(io, project, location, options.json);
+            return;
+        }
+        if (options.disable === true) {
+            reportDisableHarnessWindow(io, project, location, options.json);
+            return;
+        }
+        if (options.reenable === true) {
+            reportReenableHarnessWindow(io, project, location, options.json);
+            return;
+        }
+        reportHarnessWindowState(io, project, location, options.json);
+    }
+    catch (error) {
+        reportHarnessWindowFailure(io, error, options.json);
+    }
+}
+export function registerCompactHarnessWindowCommand(compact, io) {
+    // 7. peaks compact harness-window [--reset | --disable | --reenable]
+    //
+    // The window peaks-loop divides by and the window the harness compacts
+    // against must be ONE number, or "95%" lands at two different token counts.
+    // This command is the visible half of that write: the default reports what
+    // is in force, `--reset` removes it, `--disable` stops managing it.
+    //
+    // There is deliberately NO `--sync` flag. Materializing the window requires
+    // the ratio's own denominator, which only a probe has (it is the only place
+    // the active model is known). A `--sync` that re-derived the window here
+    // would be the second, independent resolution this slice exists to delete —
+    // `peaks code context-now` and `peaks code auto-compact` already sync.
+    addJsonOption(compact
+        .command('harness-window')
+        .description(HARNESS_WINDOW_DESCRIPTION)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--reset', 'rollback: remove the window key and stop managing it')
+        .option('--disable', 'record the opt-out only (do not manage this key), without removing a value that is already there; expressible before the first write')
+        .option('--reenable', 'undo a --reset or --disable opt-out (peaks-loop manages it again)')
+        .action((options) => runCompactHarnessWindow(options, io)));
+}

package/dist/cli/commands/compact-history-command.d.ts

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

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

@@ -0,0 +1,89 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { computeWindowCalibration, readCompactHistory, summarizeCompactHistory } from '../../services/compact-history/compact-history-service.js';
+import { resolveSessionId } from './compact-shared.js';
+const COMPACT_HISTORY_DESCRIPTION = 'Read the per-session compact-history.jsonl and emit a structured ' +
+    'summary of every auto-compact dispatch in the current session.';
+function reportCompactHistorySessionFailure(io, error, project, json) {
+    printResult(io, fail('compact.history', error.code, error.message, { projectRoot: project }, error.nextActions), json);
+    process.exitCode = 1;
+}
+function reportCompactHistoryMissing(io, sessionId, historyPath, json) {
+    printResult(io, ok('compact.history', {
+        sessionId,
+        totalCompacts: 0,
+        message: 'No compact-history.jsonl yet; auto-compact has not fired in this session.',
+        historyPath
+    }), json);
+}
+function reportCompactHistoryEmpty(io, sessionId, historyPath, json) {
+    printResult(io, ok('compact.history', {
+        sessionId,
+        totalCompacts: 0,
+        message: 'compact-history.jsonl exists but is empty.',
+        historyPath
+    }), json);
+}
+function reportCompactHistorySummary(io, sessionId, result, json) {
+    const summary = summarizeCompactHistory(result.events);
+    // intent-vs-observed record. `pairs[i].requestedTokens` is the token
+    // point peaks-loop asked for; `observedTokens` is what the next real
+    // session actually measured. Unmeasured pairs are reported as such —
+    // this instrument states what happened, it does not predict.
+    const windowCalibration = computeWindowCalibration(result.events);
+    printResult(io, ok('compact.history', {
+        sessionId,
+        ...summary,
+        windowCalibration,
+        events: result.events,
+        parseErrors: result.parseErrors,
+        historyPath: result.path
+    }), json);
+}
+function reportCompactHistoryFailure(io, error, json) {
+    printResult(io, fail('compact.history', 'COMPACT_HISTORY_READ_FAILED', getErrorMessage(error), {}, [
+        'Verify the project path is readable and a session is bound'
+    ]), json);
+    process.exitCode = 1;
+}
+function runCompactHistory(options, io) {
+    try {
+        const project = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(project, options.sessionId);
+        if (session.error !== null) {
+            reportCompactHistorySessionFailure(io, session.error, project, options.json);
+            return;
+        }
+        const result = readCompactHistory({
+            projectRoot: project,
+            sessionId: session.sid
+        });
+        if (result.kind === 'file-missing') {
+            reportCompactHistoryMissing(io, session.sid, result.path, options.json);
+            return;
+        }
+        if (result.kind === 'empty') {
+            reportCompactHistoryEmpty(io, session.sid, result.path, options.json);
+            return;
+        }
+        reportCompactHistorySummary(io, session.sid, result, options.json);
+    }
+    catch (error) {
+        reportCompactHistoryFailure(io, error, options.json);
+    }
+}
+export function registerCompactHistoryCommand(compact, io) {
+    // -----------------------------------------------------------------
+    // 6. peaks compact history [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('history')
+        .description(COMPACT_HISTORY_DESCRIPTION)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')
+        .action((options) => runCompactHistory(options, io)));
+}

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

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

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

@@ -0,0 +1,123 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { buildRecommendEnvelopePure, suggestCompact } from '../../services/compact/suggest-service.js';
+import { PHASES, SURVIVAL_TABLE, isPhase, lookupPhaseTransition } from '../../services/compact/decision-tables.js';
+import { resolveSessionId } from './compact-shared.js';
+const COMPACT_SUGGEST_DESCRIPTION = 'Two-signal suggestion (context-size + tool-call-count). ' +
+    'Honor COMPACT_THRESHOLD / COMPACT_CONTEXT_THRESHOLD / COMPACT_CONTEXT_INTERVAL env vars. ' +
+    'Read-only by default; pass --apply to also append a one-line info row to the session log.';
+const COMPACT_RECOMMEND_DESCRIPTION = `Strategic-compact "Compaction Decision Guide" lookup. ` +
+    `Valid phases: ${PHASES.join(', ')}. Pure function over (from, to); no I/O.`;
+const COMPACT_SURVIVAL_DESCRIPTION = 'Strategic-compact "What Survives Compaction" table. Pure static data; no I/O.';
+function reportCompactSuggestSessionFailure(io, error, projectRoot, json) {
+    printResult(io, fail('compact.suggest', error.code, error.message, { projectRoot }, error.nextActions), json);
+    process.exitCode = 1;
+}
+function buildCompactSuggestNextActions(result) {
+    return [
+        result.shouldSuggest
+            ? `Run \`peaks compact force --reason "<short note>"\` to checkpoint, then /compact.`
+            : `Context at ${(result.ratio * 100).toFixed(1)}% (${result.tokensUsed} of ${result.windowKind === '1m' ? '1M' : '200k'}); below threshold.`
+    ];
+}
+function reportCompactSuggestFailure(io, error, json) {
+    printResult(io, fail('compact.suggest', 'COMPACT_SUGGEST_FAILED', getErrorMessage(error), {}, [
+        'Verify project root and session binding before retrying'
+    ]), json);
+    process.exitCode = 1;
+}
+function runCompactSuggest(options, io) {
+    try {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        const session = resolveSessionId(projectRoot, options.sessionId);
+        if (session.error !== null) {
+            reportCompactSuggestSessionFailure(io, session.error, projectRoot, options.json);
+            return;
+        }
+        const result = suggestCompact({
+            projectRoot,
+            sessionId: session.sid
+        });
+        printResult(io, ok('compact.suggest', result, [], buildCompactSuggestNextActions(result)), options.json);
+    }
+    catch (error) {
+        reportCompactSuggestFailure(io, error, options.json);
+    }
+}
+function reportRecommendInvalidFrom(io, value, json) {
+    printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${value}")`, { from: value }, [`Use --from ${PHASES.join('|')}`]), json);
+    process.exitCode = 1;
+}
+function reportRecommendInvalidTo(io, value, json) {
+    printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${value}")`, { to: value }, [`Use --to ${PHASES.join('|')}`]), json);
+    process.exitCode = 1;
+}
+function reportCompactRecommendFailure(io, error, options) {
+    printResult(io, fail('compact.recommend', 'COMPACT_RECOMMEND_FAILED', getErrorMessage(error), { from: options.from, to: options.to }, ['Verify the phase pair against the documented transitions']), options.json);
+    process.exitCode = 1;
+}
+function runCompactRecommend(options, io) {
+    try {
+        if (!isPhase(options.from)) {
+            reportRecommendInvalidFrom(io, options.from, options.json);
+            return;
+        }
+        if (!isPhase(options.to)) {
+            reportRecommendInvalidTo(io, options.to, options.json);
+            return;
+        }
+        const envelope = buildRecommendEnvelopePure(options.from, options.to);
+        const lookup = lookupPhaseTransition(options.from, options.to);
+        printResult(io, ok('compact.recommend', {
+            from: envelope.from,
+            to: envelope.to,
+            shouldCompact: envelope.shouldCompact,
+            severity: envelope.severity,
+            rationale: envelope.rationale,
+            suggestedMessage: envelope.suggestedMessage,
+            notInTable: lookup.notInTable
+        }, lookup.notInTable
+            ? [
+                `Transition ${options.from} → ${options.to} is not in the strategic-compact table; defaulting to severity=no.`
+            ]
+            : []), options.json);
+    }
+    catch (error) {
+        reportCompactRecommendFailure(io, error, options);
+    }
+}
+function runCompactSurvival(options, io) {
+    printResult(io, ok('compact.survival', {
+        persists: [...SURVIVAL_TABLE.persists],
+        lost: [...SURVIVAL_TABLE.lost]
+    }, [], [
+        'Persists = guaranteed across `/compact`. Lost = not preserved; persist to disk before compacting.'
+    ]), options.json);
+}
+export function registerCompactReadCommands(compact, io) {
+    // -----------------------------------------------------------------
+    // 1. peaks compact suggest [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('suggest')
+        .description(COMPACT_SUGGEST_DESCRIPTION)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')
+        .option('--apply', 'append a one-line info row to .peaks/_runtime/<sid>/session.json (default: dry-run)')).action((options) => runCompactSuggest(options, io));
+    // -----------------------------------------------------------------
+    // 2. peaks compact recommend --from <phase> --to <phase> [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('recommend')
+        .description(COMPACT_RECOMMEND_DESCRIPTION)
+        .requiredOption('--from <phase>', `source phase (one of ${PHASES.join(', ')})`)
+        .requiredOption('--to <phase>', `target phase (one of ${PHASES.join(', ')})`)).action((options) => runCompactRecommend(options, io));
+    // -----------------------------------------------------------------
+    // 3. peaks compact survival [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact.command('survival').description(COMPACT_SURVIVAL_DESCRIPTION)).action((options) => runCompactSurvival(options, io));
+}

package/dist/cli/commands/compact-settle-command.d.ts

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