peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/cli/commands/session-24h-mode.js

@@ -0,0 +1,196 @@
+/**
+ * `peaks session 24h-mode` — state-only CLI for the 24h mode backbone.
+ *
+ * Rid-020a (state-only slice). Exposes four sub-actions so the LLM
+ * orchestrator can introspect, transition, audit retry attempts, and
+ * reset the 24h state machine without touching the JSON file
+ * directly. The LLM is the decision-maker; the CLI is the muscle
+ * (same contract as `peaks session checkpoint`).
+ *
+ * Sub-actions (all accept --json for machine-readable envelopes):
+ *   - `peaks session 24h-mode state`        — read snapshot
+ *   - `peaks session 24h-mode transition`   — move to a new state
+ *   - `peaks session 24h-mode attempts`     — read attempts map
+ *   - `peaks session 24h-mode reset`        — wipe the snapshot
+ *
+ * peaks-code is the skill that should drive this CLI; we do not
+ * add a new top-level verb (peaks-loop is enhancement, not a new
+ * CLI surface — see `.peaks/memory/peaks-loop-is-enhancement-not-new-cli.md`).
+ */
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { HANDOFF_EXIT_CONDITIONS, STATES, emptySnapshot, isHandoffExitCondition, isState, read24hState, write24hState } from '../../services/24h-mode/index.js';
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/[,\r\n]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function printJson(io, payload, options) {
+    if (options.json === true) {
+        io.stdout(JSON.stringify(payload) + '\n');
+    }
+    else {
+        io.stdout(JSON.stringify(payload, null, 2) + '\n');
+    }
+}
+function printError(io, code, message, options) {
+    if (options.json === true) {
+        io.stderr(JSON.stringify({ ok: false, code, error: message }) + '\n');
+    }
+    else {
+        io.stderr(`${code}: ${message}\n`);
+    }
+}
+/**
+ * Resolve the session id from the parent options; falls back to the
+ * canonical session-manager binding if `--session-id` is not set.
+ * The dynamic import keeps the static dependency graph clean (no
+ * top-level cycle with `session-manager.ts`).
+ */
+async function resolveSessionIdAsync(opts) {
+    if (opts.sessionId)
+        return opts.sessionId;
+    const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+    const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+    return getSessionIdCanonical(projectRoot);
+}
+export function registerSession24hModeCommand(session, io) {
+    const cmd = session
+        .command('24h-mode')
+        .description('24h mode state machine (rid-020a). Sub-actions: state, transition, attempts, reset. ' +
+        'persists to .peaks/_runtime/<sessionId>/24h-state.json.')
+        .option('--json', 'emit machine-readable JSON envelope')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--session-id <sessionId>', 'explicit session id (defaults to canonical binding)');
+    // sub-action: state (read snapshot)
+    cmd
+        .command('state')
+        .description('Read the current 24h mode state snapshot')
+        .action(async (subOpts) => {
+        const parentOpts = cmd.opts();
+        const merged = { ...parentOpts, ...subOpts };
+        const projectRoot = resolveCanonicalProjectRoot(merged.project ?? process.cwd());
+        const sid = await resolveSessionIdAsync(merged);
+        if (!sid) {
+            printError(io, 'NO_ACTIVE_SESSION', 'no --session-id and no canonical binding', merged);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const snapshot = read24hState(projectRoot, sid);
+            printJson(io, { ok: true, data: snapshot }, merged);
+        }
+        catch (error) {
+            printError(io, '24H_STATE_READ_FAILED', getErrorMessage(error), merged);
+            process.exitCode = 1;
+        }
+    });
+    // sub-action: transition (move to a new state)
+    cmd
+        .command('transition')
+        .description('Move the state machine to a new state')
+        .requiredOption('--state <state>', `target state (one of: ${STATES.join(', ')})`)
+        .option('--reason <text>', 'human-readable reason for the transition')
+        .option('--exit-condition <condition>', `HANDOFF exit condition (one of: ${HANDOFF_EXIT_CONDITIONS.join(', ')})`)
+        .option('--active-slices <list>', 'comma-separated active slice ids (e.g. "rid-020a,rid-020b")')
+        .action(async (subOpts) => {
+        const parentOpts = cmd.opts();
+        const merged = { ...parentOpts, ...subOpts };
+        const projectRoot = resolveCanonicalProjectRoot(merged.project ?? process.cwd());
+        const sid = await resolveSessionIdAsync(merged);
+        if (!sid) {
+            printError(io, 'NO_ACTIVE_SESSION', 'no --session-id and no canonical binding', merged);
+            process.exitCode = 1;
+            return;
+        }
+        if (!merged.state || !isState(merged.state)) {
+            printError(io, 'INVALID_STATE', `--state must be one of ${STATES.join(', ')} (got ${JSON.stringify(merged.state)})`, merged);
+            process.exitCode = 1;
+            return;
+        }
+        const target = merged.state;
+        if (merged.exitCondition !== undefined && !isHandoffExitCondition(merged.exitCondition)) {
+            printError(io, 'INVALID_EXIT_CONDITION', `--exit-condition must be one of ${HANDOFF_EXIT_CONDITIONS.join(', ')}`, merged);
+            process.exitCode = 1;
+            return;
+        }
+        if (target === 'HANDOFF' && !merged.exitCondition) {
+            printError(io, 'HANDOFF_REQUIRES_EXIT_CONDITION', 'transitioning to HANDOFF requires --exit-condition', merged);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const current = read24hState(projectRoot, sid);
+            const now = new Date().toISOString();
+            const sliceList = splitList(merged.activeSlices);
+            const next = {
+                ...current,
+                state: target,
+                enteredAt: now,
+                enteredFrom: current.state,
+                activeSlices: sliceList.length > 0 ? sliceList : current.activeSlices,
+                exitCondition: target === 'HANDOFF' ? (merged.exitCondition ?? null) : current.exitCondition
+            };
+            const result = write24hState(projectRoot, sid, next);
+            printJson(io, { ok: true, data: { ...next, path: result.path } }, merged);
+        }
+        catch (error) {
+            printError(io, '24H_STATE_WRITE_FAILED', getErrorMessage(error), merged);
+            process.exitCode = 1;
+        }
+    });
+    // sub-action: attempts (read attempts map)
+    cmd
+        .command('attempts')
+        .description('Read the B3 attempts map (per-key retry counts)')
+        .action(async (subOpts) => {
+        const parentOpts = cmd.opts();
+        const merged = { ...parentOpts, ...subOpts };
+        const projectRoot = resolveCanonicalProjectRoot(merged.project ?? process.cwd());
+        const sid = await resolveSessionIdAsync(merged);
+        if (!sid) {
+            printError(io, 'NO_ACTIVE_SESSION', 'no --session-id and no canonical binding', merged);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const snapshot = read24hState(projectRoot, sid);
+            printJson(io, { ok: true, data: { state: snapshot.state, attempts: snapshot.attempts } }, merged);
+        }
+        catch (error) {
+            printError(io, '24H_STATE_READ_FAILED', getErrorMessage(error), merged);
+            process.exitCode = 1;
+        }
+    });
+    // sub-action: reset (wipe the snapshot)
+    cmd
+        .command('reset')
+        .description('Reset the 24h state snapshot to IDLE (fresh start)')
+        .action(async (subOpts) => {
+        const parentOpts = cmd.opts();
+        const merged = { ...parentOpts, ...subOpts };
+        const projectRoot = resolveCanonicalProjectRoot(merged.project ?? process.cwd());
+        const sid = await resolveSessionIdAsync(merged);
+        if (!sid) {
+            printError(io, 'NO_ACTIVE_SESSION', 'no --session-id and no canonical binding', merged);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const fresh = emptySnapshot();
+            const result = write24hState(projectRoot, sid, fresh);
+            printJson(io, { ok: true, data: { ...fresh, path: result.path } }, merged);
+        }
+        catch (error) {
+            printError(io, '24H_STATE_WRITE_FAILED', getErrorMessage(error), merged);
+            process.exitCode = 1;
+        }
+    });
+}
+export const SESSION_24H_MODE_CONSTANTS = {
+    STATES,
+    HANDOFF_EXIT_CONDITIONS
+};

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

@@ -15,3 +15,22 @@ import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerShareCommand(parent: Command, io: ProgramIO): void;
 export declare function registerSharedReadCommand(parent: Command, io: ProgramIO): void;
 export declare function registerAwaitCommand(parent: Command, io: ProgramIO): void;
+/**
+ * Slice 2026-07-17-D21: peaks sub-agent finalize — LLM-side completion
+ * signal. Without this, dispatch records stay queued forever.
+ *
+ * Contract:
+ *   - LLM MUST call once per dispatched Task, in post-completion branch.
+ *   - --all-stale bulk-marks every queued record for this session (crash recovery).
+ */
+export interface FinalizeOptions {
+    batch?: string;
+    requestId?: string;
+    outcome?: string;
+    error?: string;
+    allStale?: boolean;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+export declare function registerFinalizeCommand(parent: Command, io: ProgramIO): void;

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

@@ -1,6 +1,7 @@
-import { fail, getErrorMessage, ok } from '../../shared/result.js';
+import { resolve } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from '../../services/context/shared-channel.js';
+import { readSharedChannel, writeSharedEntry, SHARED_CHANNEL_SOFT_VALUE_WARN } from 'peaks-loop-shared-channel';
 import { writeLogEntry } from '../../services/log/logger.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { summarizeBatchResults } from './sub-agent-shared.js';
@@ -294,3 +295,121 @@ function awaitErrorNextActions(code) {
     }
     return 'See error message; check that --batch matches the dispatch envelope and --timeout is a positive integer ms.';
 }
+export function registerFinalizeCommand(parent, io) {
+    addJsonOption(parent
+        .command('finalize')
+        .description('D21: signal that a dispatched sub-agent has finished (success/failure/cancellation). Pass --all-stale for crash-recovery sweep.')
+        .option('--batch <batchId>', 'batchId from dispatch envelope')
+        .option('--request-id <rid>', 'requestId from dispatch envelope')
+        .option('--outcome <state>', 'done | failed | cancelled (default: done)')
+        .option('--error <msg>', 'error message (when --outcome=failed)')
+        .option('--all-stale', 'bulk-mark every queued record for this session as done')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'override active session id')).action((options) => {
+        void (async () => {
+            const asJson = options.json === true;
+            try {
+                const projectRoot = resolve(options.project ?? process.cwd());
+                const sessionId = options.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+                if (!options.allStale && !options.requestId && !options.batch) {
+                    printResult(io, fail('sub-agent.finalize', 'MISSING_TARGET', 'Pass --request-id or --batch (or --all-stale)', { ok: false }, ['Call finalize after each Task completes.']), asJson);
+                    process.exitCode = 1;
+                    return;
+                }
+                const outcome = (options.outcome ?? 'done');
+                const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
+                const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
+                // map outcome -> (status, outcome)
+                const outcomeMap = {
+                    done: { status: 'done', outcome: 'success' },
+                    failed: { status: 'failed', outcome: 'failed' },
+                    cancelled: { status: 'cancelled', outcome: 'cancelled' },
+                };
+                const mapped = outcomeMap[outcome] ?? outcomeMap['done'];
+                const finalized = [];
+                const skipped = [];
+                const errors = [];
+                const applyOutcome = (recordPath, rid) => {
+                    markCompleted({ recordPath, now: () => new Date(), status: mapped.status, outcome: mapped.outcome, projectRoot });
+                    finalized.push({ recordPath, requestId: rid, status: mapped.status });
+                };
+                if (options.allStale) {
+                    const index = readActiveDispatchIndex(projectRoot, sessionId);
+                    for (const [recordPath, entry] of Object.entries(index)) {
+                        if (entry.status !== 'queued') {
+                            skipped.push({ recordPath, reason: 'status is ' + entry.status });
+                            continue;
+                        }
+                        try {
+                            applyOutcome(recordPath, entry.requestId);
+                        }
+                        catch (e) {
+                            errors.push({ recordPath, error: getErrorMessage(e) });
+                        }
+                    }
+                }
+                else if (options.requestId) {
+                    const fs2 = await import('node:fs');
+                    const path2 = await import('node:path');
+                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
+                    let resolvedPath = null;
+                    if (fs2.existsSync(dir)) {
+                        for (const f of fs2.readdirSync(dir)) {
+                            if (!f.endsWith('.json'))
+                                continue;
+                            const p = path2.join(dir, f);
+                            const r = readRecord(p);
+                            if (r.requestId === options.requestId) {
+                                resolvedPath = p;
+                                break;
+                            }
+                        }
+                    }
+                    if (!resolvedPath) {
+                        printResult(io, fail('sub-agent.finalize', 'RECORD_NOT_FOUND', 'No dispatch record for requestId=' + options.requestId, { ok: false }, ['Check --request-id matches the dispatch envelope.']), asJson);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    try {
+                        applyOutcome(resolvedPath, options.requestId);
+                    }
+                    catch (e) {
+                        errors.push({ recordPath: resolvedPath, error: getErrorMessage(e) });
+                    }
+                }
+                else {
+                    const fs2 = await import('node:fs');
+                    const path2 = await import('node:path');
+                    const dir = path2.resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
+                    if (fs2.existsSync(dir)) {
+                        for (const f of fs2.readdirSync(dir)) {
+                            if (!f.startsWith('dispatch-') || !f.endsWith('.json'))
+                                continue;
+                            const p = path2.join(dir, f);
+                            const r = readRecord(p);
+                            if (r.batchId !== options.batch)
+                                continue;
+                            if (r.status !== 'queued') {
+                                skipped.push({ recordPath: p, reason: 'status is ' + r.status });
+                                continue;
+                            }
+                            try {
+                                applyOutcome(p, r.requestId);
+                            }
+                            catch (e) {
+                                errors.push({ recordPath: p, error: getErrorMessage(e) });
+                            }
+                        }
+                    }
+                }
+                printResult(io, ok('sub-agent.finalize', { finalized, skipped, errors, sessionId, outcome }, errors.length > 0 ? [errors.length + ' failed'] : [], errors.length > 0 ? ['Re-run after fixing.'] : ['All targeted records transitioned out of queued.']), asJson);
+                if (errors.length > 0)
+                    process.exitCode = 1;
+            }
+            catch (error) {
+                printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, ['Inspect the error.']), asJson);
+                process.exitCode = 1;
+            }
+        })();
+    });
+}

package/dist/cli/commands/skill-conformance-commands.js

@@ -6,7 +6,7 @@
  */
 import { auditSkillConformance } from '../../services/skills/skill-conformance-service.js';
 import { getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export function registerSkillConformanceCommands(program, io) {
     program
         .command('skills:audit-conformance')

package/dist/cli/commands/skill-loop-engineering-readiness-commands.js

@@ -36,7 +36,7 @@ import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { lintSkillLoopEngineeringReadiness, } from '../../services/standards/loop-engineering-readiness-lint.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 export const LOOP_ENGINEERING_READINESS_CATEGORY = 'loop-engineering-readiness';
 /**
  * Resolve the SKILL.md file path from a `--path <skill-dir>` value.

package/dist/cli/commands/skill-search-commands.js

@@ -1,5 +1,5 @@
 import { searchSkills, SkillSearchInputSchema } from '../../services/skill/skill-search-service.js';
-import { getErrorMessage } from '../../shared/result.js';
+import { getErrorMessage } from 'peaks-loop-shared/result';
 /**
  * Validate the raw CLI flags, call the service, and emit a JSON
  * envelope on stdout. Errors flow through stderr + non-zero exit
@@ -28,6 +28,7 @@ export function registerSkillSearchCommand(program, io) {
         .option('-t, --tag <tag>', 'exact match on metadata.tags (e.g. "orchestrator", "loop-engineering")')
         .option('-d, --domain <domain>', 'exact match on metadata.domain (locked enum: code | content | doctor | research | triage | sop | audit | final-review | resume | status | test | ide | slice-decompose | issue-fix-orchestrator | perf-audit | security-audit | reviewer)')
         .option('-l, --limit <n>', 'max results returned (1..100, default 20)', (v) => Number.parseInt(v, 10))
+        .option('--include-internal', 'include skills with visibility: internal (default: hide them)')
         .action(async (options) => {
         // 1) Coerce + validate input via the service's Zod schema.
         //    The schema's refine rejects empty input — that is the
@@ -41,6 +42,8 @@ export function registerSkillSearchCommand(program, io) {
             raw['domain'] = options.domain;
         if (options.limit !== undefined)
             raw['limit'] = options.limit;
+        if (options.includeInternal === true)
+            raw['includeInternal'] = true;
         const parsed = SkillSearchInputSchema.safeParse(raw);
         if (!parsed.success) {
             // Exit code 1 = invalid args. Emit a human-readable message

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

@@ -7,7 +7,7 @@ import { decomposeSlicesWithBenchmark } from '../../services/slice/slice-benchma
 import { pickSlicesInteractive } from '../../services/slice/slice-pick-service.js';
 import { decompose as multiPassDecompose } from '../../services/slice/multi-pass-orchestrator.js';
 import { readResult as readDecompositionResult, writeResult as writeSchemaResult } from '../../services/slice/schema-router.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerSliceCommands(program, io) {
     const slice = program.command('slice').description('Slice lifecycle: check (boundary), decompose (PRD -> 6-stage algorithm), ' +

package/dist/cli/commands/slice-integrate-commands.js

@@ -10,7 +10,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { integrateSlices } from '../../services/slice/slice-integration.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 function loadContractsForSlices(projectRoot, sessionId, sliceIds) {
     const dir = resolve(projectRoot, '.peaks', '_runtime', sessionId, 'dispatch', 'contracts');

package/dist/cli/commands/slice-review-commands.js

@@ -21,7 +21,7 @@
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
 import { acceptReview, buildEmptySliceReview, DEFAULT_REVIEW_ITEMS, deriveDecision, readSliceReview, rejectReview, renderChecklist, scoreItem, writeSliceReview } from '../../services/slice/slice-review-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerSliceReviewCommands(program, io) {
     // G1 commands registered as TOP-LEVEL commands prefixed with `slice-review-`

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

@@ -18,7 +18,7 @@ import { readFileSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { addCriticalPath, CRITICAL_PATH_SOURCES, EMPTY_SMOKE_STATE, isCriticalPathSource, makeCriticalPathId, readSmokeState, recordRun, summarizeState, writeSmokeState } from '../../services/smoke/smoke-paths-state.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 const RUN_STATUSES = ['pending', 'pass', 'fail'];
 export function registerSmokeCommands(program, io) {

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

@@ -6,7 +6,7 @@ import { advanceSop, SopAdvanceError, SopGateBlockedError, SopPhaseSkipError } f
 import { sopStateDir } from '../../services/sop/sop-paths.js';
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
 import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerSopCommands(program, io) {
     const sop = program.command('sop').description('Author and validate user-defined SOP skills');

package/dist/cli/commands/spill-demo-command.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rid-032: opt-in spill/hydrate round-trip for 24h mode.
+ * This demo command is additive; existing deferral behavior is unchanged.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSpillDemoCommand(parent: Command, io: ProgramIO): void;

package/dist/cli/commands/spill-demo-command.js

@@ -0,0 +1,29 @@
+import { ok } from 'peaks-loop-shared/result';
+import { hydrate, listSpills, spill, spillDir } from '../../services/context/spillover-store.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerSpillDemoCommand(parent, io) {
+    addJsonOption(parent
+        .command('spill-demo')
+        .description('Demonstrate the opt-in spill/hydrate round-trip for 24h mode.')
+        .option('--session-id <sessionId>', 'explicit session id (defaults to canonical binding)')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--batch-id <batchId>', 'optional in-flight batch id')).action((options) => {
+        const sessionId = options.sessionId ?? getSessionIdCanonical(options.project);
+        if (sessionId === null) {
+            throw new Error('No active session; provide --session-id or bind a canonical session');
+        }
+        const spilled = spill({
+            sessionId,
+            projectRoot: options.project,
+            ...(options.batchId === undefined ? {} : { batchId: options.batchId })
+        }, { llm: { turn: 1, context: ['sample'] } });
+        const allSpills = listSpills(options.project, sessionId);
+        const hydrated = hydrate(options.project, sessionId, spilled.spillId);
+        printResult(io, ok('session.spill-demo', {
+            spilled: spilled.spillId,
+            totalSpills: allSpills.length,
+            hydrated
+        }, [], [`Spill directory: ${spillDir(options.project, sessionId)}`]), options.json === true);
+    });
+}

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

@@ -1,3 +1,15 @@
 import { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
+type RenderOptions = {
+    project?: string;
+    json?: boolean;
+};
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export declare function runDefaultStatuslineRender(options: RenderOptions, io: ProgramIO): Promise<void>;
 export declare function registerStatusLineCommands(program: Command, io: ProgramIO): void;
+export {};

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

@@ -1,4 +1,4 @@
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { buildStatusLineModel, parseStatusLineStdin } from '../../services/skills/skill-statusline-service.js';
@@ -6,6 +6,8 @@ import { renderStatusLine } from '../../services/skills/skill-statusline-rendere
 import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
 import { readHookStatus as readSettingsStatus } from '../../services/skills/hooks-settings-service.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+import { decideCompactStatusline, renderCompactStatusline, } from '../../services/compact-statusline/compact-statusline-service.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
 const STDIN_READ_TIMEOUT_MS = 250;
 /** Read piped stdin if present; resolve quickly with '' when attached to a TTY. */
 function readStdin() {
@@ -54,6 +56,26 @@ function resolveIdeForCommand(options, projectRoot) {
     }
     return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
 }
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export async function runDefaultStatuslineRender(options, io) {
+    const raw = await readStdin();
+    const stdin = parseStatusLineStdin(raw);
+    const seeded = options.project
+        ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
+        : stdin;
+    const model = buildStatusLineModel(seeded, Date.now());
+    const text = renderStatusLine(model);
+    if (options.json === true) {
+        io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
+        return;
+    }
+    io.stdout(text);
+}
 export function registerStatusLineCommands(program, io) {
     // Top-level `peaks statusline` — register as a group with subcommands
     // (install | uninstall | status). When the user runs `peaks statusline` with
@@ -65,27 +87,31 @@ export function registerStatusLineCommands(program, io) {
     // option-shadowing bug.
     const statusline = addJsonOption(program
         .command('statusline')
-        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.'));
-    // Hidden render subcommand. This is the default behavior when the user types
-    // `peaks statusline` with no subcommand. We mark it hidden so `peaks
-    // statusline --help` does not show "render" as a subcommand.
+        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)'));
+    // Default behavior: when the user types `peaks statusline` with no
+    // subcommand, render the status line. Without this default action,
+    // commander falls back to printing usage (Bug-02, ice-cola surface check
+    // 2026-07-22). The hidden `render` subcommand is preserved so callers
+    // can still invoke it explicitly.
+    //
+    // Note (commander 12.x): when both a top-level `.action(...)` and
+    // subcommands exist, commander's option parser can conflate parent and
+    // child flags. We therefore parse `process.argv` for the bare `statusline`
+    // invocation here, and otherwise let the subcommand machinery handle the
+    // rest. The implementation is wrapped in `peekDefaultStatuslineRender` so
+    // it can be exercised in isolation by unit tests.
+    statusline.action(async (_parentOptions, command) => {
+        await runDefaultStatuslineRender(command.opts(), io);
+    });
+    // Hidden render subcommand. Preserved for callers that want to invoke
+    // render explicitly without going through the default-action dispatch.
     statusline
         .command('render', { hidden: true })
         .description('Render the Peaks skill status line for the current session (reads session JSON on stdin; honors --project for the project label).')
         .option('--project <path>', 'project root path (used to label the status line when stdin is absent)')
         .action(async (options) => {
-        const raw = await readStdin();
-        const stdin = parseStatusLineStdin(raw);
-        const seeded = options.project
-            ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
-            : stdin;
-        const model = buildStatusLineModel(seeded, Date.now());
-        const text = renderStatusLine(model);
-        if (options.json === true) {
-            io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
-            return;
-        }
-        io.stdout(text);
+        await runDefaultStatuslineRender(options, io);
     });
     addJsonOption(statusline
         .command('install')
@@ -166,4 +192,40 @@ export function registerStatusLineCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // peaks statusline compact (slice 2026-07-30-compact-visibility)
+    addJsonOption(statusline
+        .command('compact')
+        .description('Render the single-line auto-compact indicator the LLM embeds ' +
+        "in Claude Code's statusline. Default output is plain text; " +
+        'pass --json for the structured envelope.')
+        .option('--project <path>', 'project root (auto-detected from cwd when omitted)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')
+        .action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const sid = options.sessionId ?? getSessionIdCanonical(projectRoot) ?? null;
+            const state = decideCompactStatusline({
+                projectRoot,
+                sessionId: sid,
+                now: Date.now(),
+            });
+            const label = renderCompactStatusline(state);
+            // For non-JSON mode we print the LABEL DIRECTLY to stdout
+            // (no envelope wrapping) because the consumer is the IDE
+            // statusline, not a peaks-Loop caller.
+            if (options.json === true) {
+                printResult(io, ok('statusline.compact', { label, state }), options.json);
+            }
+            else {
+                process.stdout.write(`${label}\n`);
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.compact', 'STATUSLINE_COMPACT_FAILED', message, {}, [message]), options.json);
+            process.exitCode = 1;
+        }
+    }));
 }

package/dist/cli/commands/sub-agent-commands.js

@@ -1,6 +1,6 @@
 import { registerDispatchCommand } from './dispatch-commands.js';
 import { registerHeartbeatCommand } from './heartbeat-commands.js';
-import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand } from './share-commands.js';
+import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand, registerFinalizeCommand } from './share-commands.js';
 // Re-export `validateRole` for backward compat — the integration test
 // suite and any external callers still import it from this entry file.
 // The canonical implementation now lives in `sub-agent-shared.ts`.
@@ -16,4 +16,5 @@ export function registerSubAgentCommands(program, io) {
     registerShareCommand(subAgent, io);
     registerSharedReadCommand(subAgent, io);
     registerAwaitCommand(subAgent, io);
+    registerFinalizeCommand(subAgent, io); // D21
 }