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

package/dist/cli/commands/session-auto-compact-hook-command.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import type { Command } from 'commander';
+export declare function registerSessionAutoCompactHookCommand(session: Command): void;

package/dist/cli/commands/session-auto-compact-hook-command.js

@@ -0,0 +1,127 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * Red-line ratio threshold. Must match the orchestrator's
+ * AUTO_COMPACT_RED_LINE_RATIO constant (0.95). Kept here as a
+ * literal so the hook command stays self-contained — a future
+ * slice may move this to a shared constant module if the value
+ * starts drifting.
+ */
+const RED_LINE_RATIO = 0.95;
+/**
+ * Parse `CLAUDE_CONTEXT_USAGE_PERCENT` (or the adapter-declared
+ * env-var) into a ratio in [0, 1]. Returns null on missing /
+ * malformed input. Mirrors `readEnvPercent` in
+ * `auto-compact-reader.ts` so the hook command and the
+ * orchestrator agree on parsing semantics.
+ */
+function readRatioFromEnv(env) {
+    const detected = detectIdeFromEnv(env);
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    if (!adapter.compact)
+        return null;
+    const varName = adapter.compact.envVarForContextPercent;
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Allow either "0..1" or "0..100" encoding. Claude Code writes
+    // "0..1" today; statusline tools sometimes write "0..100". Normalize.
+    const ratio = parsed > 1.5 ? parsed / 100 : Math.max(0, Math.min(1, parsed));
+    return { ratio, varName };
+}
+export function registerSessionAutoCompactHookCommand(session) {
+    session
+        .command('auto-compact-hook')
+        .description('PreToolUse hook entrypoint — read CLAUDE_CONTEXT_USAGE_PERCENT and, ' +
+        'at ratio ≥ 0.95, in-band spawn `claude --compact` against the current ' +
+        'runner. Designed for invocation from `.claude/settings.local.json` ' +
+        'PreToolUse hooks; safe to re-run.')
+        .action(() => {
+        const probe = readRatioFromEnv(process.env);
+        if (probe === null) {
+            // No signal → exit 0 silent. The hook must never block the
+            // runner's normal flow on a missing env-var.
+            return;
+        }
+        if (probe.ratio < RED_LINE_RATIO) {
+            // Below red line → exit 0 silent. The orchestrator's
+            // pre-compact zone (0.85–0.95) is handled out-of-band by
+            // the LLM firing `peaks code auto-compact --execute`; the
+            // hook only fires on the synchronous red-line path.
+            return;
+        }
+        // Red line reached — compact the current runner in-band.
+        // The `detached: true` + `unref()` pair lets the hook return
+        // immediately while Claude Code's own slash-command processor
+        // picks up `claude --compact` against the runner's session.
+        // This is the fix for the shell-exec-spawns-a-child-process
+        // bug documented in `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`.
+        //
+        // Dogfood 2026-07-02 fix: when `claude` is not on PATH (the
+        // user runs Claude Code as an MCP rather than via the CLI
+        // binary), `spawn` raises ENOENT. Catching this MUST NOT crash
+        // the runner's tool call — the hook must exit 0 silently with
+        // a one-line stderr hint so the runner keeps working. The user
+        // can then run `/compact` manually (or `peaks code auto-compact`
+        // from another terminal).
+        try {
+            const child = spawn('claude', ['--compact'], {
+                stdio: 'ignore',
+                detached: true,
+                env: process.env
+            });
+            child.on('error', () => {
+                // Spawn failed (ENOENT or EPERM). Exit 0 silently with a
+                // stderr hint — the hook contract is "never crash the
+                // runner's tool call".
+                process.stderr.write('[peaks:auto-compact-hook] claude CLI not on PATH; cannot fire in-band. Run `/compact` manually or set up the Claude Code CLI binary.\n');
+            });
+            child.unref();
+            process.stderr.write(`[peaks:auto-compact-hook] ratio=${(probe.ratio * 100).toFixed(1)}% ≥ ${(RED_LINE_RATIO * 100).toFixed(0)}%; firing claude --compact in-band\n`);
+        }
+        catch {
+            // Defensive: `spawn` can throw synchronously on some platforms.
+            process.stderr.write('[peaks:auto-compact-hook] failed to spawn claude --compact; run `/compact` manually.\n');
+        }
+    });
+}

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,17 @@
+/**
+ * `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;