peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/cli/commands/session-24h-mode.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `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 type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSession24hModeCommand(session: Command, io: ProgramIO): void;
+export declare const SESSION_24H_MODE_CONSTANTS: {
+    readonly STATES: readonly ["IDLE", "BRAINSTORM", "USER_CONFIRM", "24H_ACTIVE", "WAITING_USER", "HANDOFF"];
+    readonly HANDOFF_EXIT_CONDITIONS: readonly ["user_abort", "all_triggers_resolved", "b3_unresolvable"];
+};

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/session-checkpoint-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `peaks session checkpoint` — slice 011.
+ *
+ * Writes a JSON snapshot of the current session's state to
+ * `_runtime/<sessionId>/checkpoints/<iso>.json`. Designed for skill
+ * invocation; the CLI is the muscle, the LLM decides the cadence.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSessionCheckpointCommand(session: Command, _io: ProgramIO): void;

package/dist/cli/commands/session-checkpoint-command.js

@@ -0,0 +1,100 @@
+/**
+ * `peaks session checkpoint` — slice 011.
+ *
+ * Writes a JSON snapshot of the current session's state to
+ * `_runtime/<sessionId>/checkpoints/<iso>.json`. Designed for skill
+ * invocation; the CLI is the muscle, the LLM decides the cadence.
+ */
+import { CHECKPOINT_CONSTANTS, CHECKPOINT_REASONS, writeCheckpoint, } from '../../services/session/session-checkpoint-service.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerSessionCheckpointCommand(session, _io) {
+    session
+        .command('checkpoint')
+        .description(`Write a JSON snapshot of the current session to ` +
+        `_runtime/<sessionId>/checkpoints/<iso>.json (max ${CHECKPOINT_CONSTANTS.MAX_CHECKPOINTS} retained). ` +
+        'Designed for skill-level invocation.')
+        .option('--reason <reason>', `one of: ${CHECKPOINT_REASONS.join(', ')} (default: periodic)`, 'periodic')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--session-id <sid>', 'explicit session id (defaults to canonical binding from .peaks/_runtime/session.json)')
+        .option('--current-plan <text>', 'current plan summary')
+        .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')
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action(async (opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            let sid = opts.sessionId;
+            if (!sid) {
+                const { getSessionIdCanonical } = await import('../../services/session/session-manager.js');
+                sid = getSessionIdCanonical(projectRoot) ?? undefined;
+            }
+            if (!sid) {
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({
+                        ok: false,
+                        error: 'NO_ACTIVE_SESSION: run `peaks workspace init` first or pass --session-id'
+                    }) + '\n');
+                }
+                else {
+                    process.stderr.write('NO_ACTIVE_SESSION: run `peaks workspace init` first or pass --session-id\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            const reasonRaw = opts.reason ?? 'periodic';
+            if (!CHECKPOINT_REASONS.includes(reasonRaw)) {
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({
+                        ok: false,
+                        error: `INVALID_REASON: --reason must be one of ${CHECKPOINT_REASONS.join(', ')} (got "${reasonRaw}")`
+                    }) + '\n');
+                }
+                else {
+                    process.stderr.write(`INVALID_REASON: --reason must be one of ${CHECKPOINT_REASONS.join(', ')} (got "${reasonRaw}")\n`);
+                }
+                process.exitCode = 1;
+                return;
+            }
+            const reason = reasonRaw;
+            const result = writeCheckpoint(projectRoot, {
+                sessionId: sid,
+                reason,
+                ...(opts.currentPlan !== undefined ? { currentPlan: opts.currentPlan } : {}),
+                ...(opts.gitStatus !== undefined ? { gitStatus: opts.gitStatus } : {}),
+                openQuestions: splitList(opts.openQuestions),
+                recentDecisions: splitList(opts.recentDecisions),
+                recentArtifactPaths: splitList(opts.recentArtifactPaths),
+                skillsActive: splitList(opts.skillsActive),
+                todoState: splitList(opts.todoState)
+            });
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: result }) + '\n');
+            }
+            else {
+                process.stdout.write(`checkpoint: ${result.path} (reason=${result.reason}, retained=${result.totalRetained})\n`);
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/session-migrate-skill-name.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Slice 2 of the peaks-code → peaks-code rename plan.
+ *
+ * `peaks session migrate-skill-name --from <old> --to <new> [--apply]
+ * [--project <path>] [--json]` — idempotent string-rewrite across
+ * `.peaks/_runtime/**`. Dry-run by default; pass `--apply` to write
+ * through. Skip-paths (`.peaks/memory/**`,
+ * `.peaks/skills/.system/bees/<old>/`) are recorded in `skipped`
+ * and never opened, so older memory capsules and the bee manifest
+ * for the old skill stay untouched.
+ *
+ * JSON envelope shape is owned by `MigrateResultSchema` in
+ * `src/services/migrate-skill-name/schema.ts`. Plain-text mode is
+ * a one-screen counter summary; `--json` mode is for tools.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionMigrateSkillNameCommand(session: Command): void;

package/dist/cli/commands/session-migrate-skill-name.js

@@ -0,0 +1,41 @@
+import { resolve } from 'node:path';
+import { migrateSkillName } from '../../services/migrate-skill-name/migrate.js';
+import { getErrorMessage } from '../cli-helpers.js';
+export function registerSessionMigrateSkillNameCommand(session) {
+    session
+        .command('migrate-skill-name')
+        .description('Rewrite skill-name strings under .peaks/_runtime/** (idempotent, dry-run by default). ' +
+        'Use --apply to write through. Skips .peaks/memory/** and .peaks/skills/.system/bees/.')
+        .requiredOption('--from <old>', 'old skill name (e.g. peaks-code)')
+        .requiredOption('--to <new>', 'new skill name (e.g. peaks-code)')
+        .option('--apply', 'write through (default is dry-run)', false)
+        .option('--project <path>', 'project root (defaults to current directory)', '.')
+        .option('--json', 'emit a JSON envelope to stdout', false)
+        .action((opts) => {
+        try {
+            const projectRoot = resolve(process.cwd(), opts.project ?? '.');
+            const result = migrateSkillName({
+                projectRoot,
+                from: opts.from,
+                to: opts.to,
+                apply: opts.apply === true,
+            });
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+            }
+            else {
+                process.stdout.write(`Scanned: ${result.scannedFiles}\n` +
+                    `Modified: ${result.modifiedFiles}\n` +
+                    `Key-value replacements: ${result.keyValueReplacements}\n` +
+                    `String replacements: ${result.stringReplacements}\n` +
+                    `Skipped: ${result.skipped.length} path(s)\n` +
+                    `Errors: ${result.errors.length}\n`);
+            }
+            process.exitCode = result.ok ? 0 : 1;
+        }
+        catch (error) {
+            process.stderr.write(getErrorMessage(error) + '\n');
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `peaks session resume` — slice 011.
+ *
+ * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
+ * emits a structured markdown "resume context" block the skill can
+ * prepend to its own prompt. Default behavior writes the block to
+ * stdout so the skill (LLM) can pick it up directly.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSessionResumeCommand(session: Command, _io: ProgramIO): void;

package/dist/cli/commands/session-resume-command.js

@@ -0,0 +1,83 @@
+/**
+ * `peaks session resume` — slice 011.
+ *
+ * Reads a checkpoint JSON (written by `peaks session checkpoint`) and
+ * emits a structured markdown "resume context" block the skill can
+ * prepend to its own prompt. Default behavior writes the block to
+ * stdout so the skill (LLM) can pick it up directly.
+ */
+import { buildResumeContext } from '../../services/session/session-resume-service.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+export function registerSessionResumeCommand(session, _io) {
+    session
+        .command('resume')
+        .description('Read a checkpoint JSON and emit a markdown "resume context" block ' +
+        '(LLM-friendly structured format). Wire to peaks session * namespace.')
+        .option('--from <path>', 'path to a checkpoint JSON file (required, or use --session-id for latest)')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--session-id <sid>', 'use the latest checkpoint for this session id (alternative to --from)')
+        .option('--json', 'emit a JSON envelope { ok, data: { markdown, ... } }')
+        .action(async (opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            let fromPath = opts.from;
+            if (!fromPath && opts.sessionId) {
+                const { latestCheckpointPath } = await import('../../services/session/session-checkpoint-service.js');
+                const latest = latestCheckpointPath(projectRoot, opts.sessionId);
+                if (!latest) {
+                    if (opts.json === true) {
+                        process.stdout.write(JSON.stringify({
+                            ok: false,
+                            error: `NO_CHECKPOINTS: no checkpoints found for session ${opts.sessionId}`
+                        }) + '\n');
+                    }
+                    else {
+                        process.stderr.write(`NO_CHECKPOINTS: no checkpoints found for session ${opts.sessionId}\n`);
+                    }
+                    process.exitCode = 1;
+                    return;
+                }
+                fromPath = latest;
+            }
+            if (!fromPath) {
+                if (opts.json === true) {
+                    process.stdout.write(JSON.stringify({
+                        ok: false,
+                        error: 'MISSING_PATH: pass --from <path> or --session-id <sid>'
+                    }) + '\n');
+                }
+                else {
+                    process.stderr.write('MISSING_PATH: pass --from <path> or --session-id <sid>\n');
+                }
+                process.exitCode = 1;
+                return;
+            }
+            const ctx = buildResumeContext({ checkpointPath: fromPath });
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({
+                    ok: true,
+                    data: {
+                        sourcePath: ctx.sourcePath,
+                        relativeAgeLabel: ctx.relativeAgeLabel,
+                        checkpointAgeMs: ctx.checkpointAgeMs,
+                        markdown: ctx.markdown,
+                        snapshot: ctx.snapshot
+                    }
+                }) + '\n');
+            }
+            else {
+                process.stdout.write(ctx.markdown + '\n');
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,36 @@
+/**
+ * `peaks sub-agent share | shared-read | await` — G8.4 + 2.7.0 await barrier.
+ *
+ * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split)
+ * to honor the 800-line file cap. These three commands share the G8.4
+ * dispatcher-mediated cross-sub-agent signal channel:
+ *   - `share` writes a `<role>.<event>` entry (≤ 1KB soft warn, ≥ 64KB reject).
+ *   - `shared-read` returns sibling entries (filtered by `--since` / `--key` glob).
+ *   - `await` joins a batch barrier (slice 2.7.0 MVP, claude-code only).
+ *
+ * Not peer-to-peer — pseudo-swarm property 3 preserved.
+ */
+import type { Command } from 'commander';
+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;