peaks-loop 3.1.2 → 4.0.0-beta.10

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

@@ -0,0 +1,21 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
+ *   - L0: full read (every SKILL.md in full)
+ *   - L1: summary (one paragraph per skill + the skill list)
+ *   - L2: index (just names + paths)
+ *   - L3: fuzzy search by query (delegates to peaks memory search)
+ *
+ * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
+ * on the L1a task level:
+ *   - typo:     L0 only (a few lines)
+ *   - bug:     L0 + L1
+ *   - feature: L0 + L1 + L2 + L3(按需)
+ *   - refactor: L0 + L1 + L2 + L3
+ *   - migration: L0 + L1 + L2 + L3 + codegraph
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+export declare function registerContextCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,254 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
+ *   - L0: full read (every SKILL.md in full)
+ *   - L1: summary (one paragraph per skill + the skill list)
+ *   - L2: index (just names + paths)
+ *   - L3: fuzzy search by query (delegates to peaks memory search)
+ *
+ * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
+ * on the L1a task level:
+ *   - typo:     L0 only (a few lines)
+ *   - bug:     L0 + L1
+ *   - feature: L0 + L1 + L2 + L3(按需)
+ *   - refactor: L0 + L1 + L2 + L3
+ *   - migration: L0 + L1 + L2 + L3 + codegraph
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { evaluateMainSessionThreshold, pickMainSessionTrigger, formatMainSessionTriggerLogLine, detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+const SKILLS_DIR = 'skills';
+function readSkillsDir(projectRoot) {
+    const skillsRoot = join(projectRoot, SKILLS_DIR);
+    if (!existsSync(skillsRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const skillMd = join(skillsRoot, entry.name, 'SKILL.md');
+        if (existsSync(skillMd)) {
+            out.push(`skills/${entry.name}/SKILL.md`);
+        }
+    }
+    return out;
+}
+function readSkillFile(projectRoot, relPath) {
+    const abs = join(projectRoot, relPath);
+    try {
+        return readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+async function fetchL0(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        content += `## ${rel}\n\n${body}\n\n`;
+        sizes.push({ path: rel, bytes: body.length });
+        byteSize += body.length;
+    }
+    return { layer: 'L0', description: 'full read: every SKILL.md concatenated', files: sizes, content, byteSize, warnings };
+}
+async function fetchL1(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        const firstPara = body.split(/\r?\n\r?\n/, 2)[0] ?? body.slice(0, 400);
+        content += `## ${rel}\n\n${firstPara}\n\n`;
+        sizes.push({ path: rel, bytes: firstPara.length });
+        byteSize += firstPara.length;
+    }
+    return { layer: 'L1', description: 'summary: first paragraph per skill', files: sizes, content, byteSize, warnings };
+}
+async function fetchL2(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const content = files.map((f) => `- ${f}`).join('\n') + '\n';
+    const byteSize = content.length;
+    return {
+        layer: 'L2',
+        description: 'index: skill paths only (no body)',
+        files: files.map((f) => ({ path: f, bytes: 0 })),
+        content,
+        byteSize,
+        warnings: [],
+    };
+}
+async function fetchL3(projectRoot, query) {
+    const warnings = [];
+    if (query.trim().length === 0) {
+        warnings.push('empty query; L3 requires a --query string for fuzzy search');
+        return { layer: 'L3', description: 'fuzzy search (empty query)', files: [], content: '', byteSize: 0, warnings };
+    }
+    try {
+        const hits = searchMemory({ projectRoot, query, limit: 10 });
+        const lines = [];
+        for (const hit of hits) {
+            lines.push(`- [${hit.score.toFixed(2)}] ${hit.sourcePath}: ${hit.description.slice(0, 120)}`);
+        }
+        const content = lines.join('\n') + '\n';
+        return {
+            layer: 'L3',
+            description: 'fuzzy search: top 10 hits from memory index',
+            files: hits.map((h) => ({ path: h.sourcePath, bytes: h.description.length })),
+            content,
+            byteSize: content.length,
+            warnings,
+        };
+    }
+    catch (error) {
+        return {
+            layer: 'L3',
+            description: 'fuzzy search (failed)',
+            files: [],
+            content: '',
+            byteSize: 0,
+            warnings: [`L3 search failed: ${getErrorMessage(error)}`],
+        };
+    }
+}
+export function registerContextCommands(program, io) {
+    const context = program
+        .command('context')
+        .description('Slice L1c: context 4-layer loader (L0 full / L1 summary / L2 index / L3 fuzzy)');
+    addJsonOption(context
+        .command('layer')
+        .description('Fetch a context layer (L0 = full SKILL.md; L1 = first paragraph; L2 = index; L3 = fuzzy search by --query)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--level <L0|L1|L2|L3>', 'context layer to load')
+        .option('--query <text>', 'fuzzy search query (required for L3)')).action(async (options) => {
+        try {
+            const level = options.level;
+            if (level !== 'L0' && level !== 'L1' && level !== 'L2' && level !== 'L3') {
+                printResult(io, fail('context.layer', 'INVALID_LEVEL', `level must be one of L0, L1, L2, L3 (got ${level})`, { provided: level }, ['Pass --level L0|L1|L2|L3']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let payload;
+            if (level === 'L0')
+                payload = await fetchL0(options.project);
+            else if (level === 'L1')
+                payload = await fetchL1(options.project);
+            else if (level === 'L2')
+                payload = await fetchL2(options.project);
+            else
+                payload = await fetchL3(options.project, options.query ?? '');
+            printResult(io, ok('context.layer', payload, [], [
+                `${payload.layer} loaded: ${payload.byteSize} bytes across ${payload.files.length} file(s)`,
+                payload.warnings.length > 0 ? `${payload.warnings.length} warning(s); see envelope.warnings` : null
+            ].filter((x) => typeof x === 'string')), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('context.layer', 'CONTEXT_LAYER_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path and --level value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(context
+        .command('status')
+        .description('v2.11.0 D6: report main-session threshold tier for a given prompt size (no trigger dispatched). Useful for `--json` probes before invoking `peaks context check --auto-trigger`.')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')).action((opts) => {
+        try {
+            const promptSize = Number(opts.promptSize);
+            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
+            if (!Number.isFinite(promptSize) || promptSize < 0) {
+                printResult(io, fail('context.status', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const evaluation = evaluateMainSessionThreshold(promptSize, capacity);
+            printResult(io, ok('context.status', { ...evaluation, ide: detectIdeFromEnv() }, [...evaluation.warnings], [
+                `Main-session tier=${evaluation.tier} (${(evaluation.ratio * 100).toFixed(0)}%)`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.status', 'CONTEXT_STATUS_FAILED', getErrorMessage(err), null, ['Verify --prompt-size is a non-negative number']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(context
+        .command('check')
+        .description('v2.11.0 D6: threshold check + IDE-aware trigger dispatch. With --auto-trigger, returns the trigger path the LLM should follow; without, returns a dry-run recommendation. The LLM is responsible for actually invoking the trigger (slash command, self-compress, or escalation).')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')
+        .option('--in-flight-batch', 'a sub-agent batch is in flight (defer trigger per D6.e)', false)
+        .option('--auto-trigger', 'return the trigger path the LLM should follow', false)).action((opts) => {
+        try {
+            const promptSize = Number(opts.promptSize);
+            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
+            if (!Number.isFinite(promptSize) || promptSize < 0) {
+                printResult(io, fail('context.check', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const trigger = pickMainSessionTrigger({
+                promptSize,
+                capacityBytes: capacity,
+                inFlightBatch: opts.inFlightBatch === true ? { hasInFlightBatch: true, sharedChannelEntries: 1 } : undefined
+            });
+            // Slice C of v2.11.1 — observability hook #5/7. Fire-and-forget
+            // per PRD Q4. The synchronous emit never throws.
+            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+            const sid = getSessionIdCanonical(projectRoot) ?? '';
+            if (sid.length > 0) {
+                emitObservabilityEvent({
+                    schemaVersion: 1,
+                    ts: new Date().toISOString(),
+                    sessionId: sid,
+                    category: 'context-trigger',
+                    detail: {
+                        kind: trigger.kind,
+                        promptSize,
+                        ...(trigger.kind === 'soft-warn' || trigger.kind === 'compact'
+                            ? { ratio: trigger.ratio }
+                            : {})
+                    }
+                }, { projectRoot });
+            }
+            const logLine = formatMainSessionTriggerLogLine(trigger, 'main');
+            const payload = {
+                ...trigger,
+                autoTrigger: opts.autoTrigger === true,
+                logLine
+            };
+            printResult(io, ok('context.check', payload, [], [
+                trigger.kind === 'compact'
+                    ? `Tier reached → trigger ${trigger.path} on ${trigger.ide} (code=${trigger.code})`
+                    : trigger.kind === 'defer'
+                        ? `Deferred: ${trigger.reason}`
+                        : trigger.kind === 'soft-warn'
+                            ? `Soft warning at ${(trigger.ratio * 100).toFixed(0)}% (no trigger yet)`
+                            : 'Below threshold; no trigger'
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.check', 'CONTEXT_CHECK_FAILED', getErrorMessage(err), null, ['Verify --prompt-size is a non-negative number']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * `peaks contract` CLI commands — 2.7.0 slice-dag-dispatcher MVP
+ * (slice 1.2.c — LLM-side contract writer).
+ *
+ * Round-2 fix #5 (upgrade placeholder prompt) tells the LLM-side
+ * runner to execute `peaks contract write --project <root> ...` to
+ * persist its slice's public surface so the orchestrator can splice
+ * the contract into downstream dispatch prompts via
+ * `formatContractInjection`. This file is the actual implementation
+ * of that command — without it, the round-2 prompt would direct the
+ * LLM to a CLI that doesn't exist (the round-5 audit caught this).
+ *
+ * The command is a thin wrapper over `writeContract` from
+ * `src/services/dispatch/contract-store.ts`; it accepts the same
+ * shape, splits the comma-separated `--exports` / `--types` /
+ * `--signatures` flag values into arrays, and surfaces the result
+ * via the standard `ok` / `fail` envelope used across peaks-loop.
+ *
+ * Skill-first / CLI-auxiliary red line: users do not invoke this
+ * directly. The peaks-code / peaks-rd LLM-side runner (the
+ * IDE-resident sub-agent that finished a slice) calls this command
+ * after the slice completes.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContractCommands(program: Command, io: ProgramIO): void;

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

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

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

@@ -0,0 +1,241 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionMeta, rotateSessionBinding, setSessionTitle, listSessionMetas } from '../../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { fail, ok } from '../../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+// Slice 2026-07-01-strategic-compact-cli fix: register the
+// `peaks session checkpoint` and `peaks session resume` subcommands
+// EAGERLY so they appear in `peaks session --help` output. The
+// previous lazy import ran AFTER commander had already produced
+// the help text, so an LLM calling `peaks <TAB>`-discovery never
+// saw them — they were effectively hidden.
+import { registerSessionCheckpointCommand } from '../session-checkpoint-command.js';
+import { registerSessionResumeCommand } from '../session-resume-command.js';
+import { registerSessionAutoCompactHookCommand } from '../session-auto-compact-hook-command.js';
+// Slice 2 of the peaks-code → peaks-code rename plan: register the
+// `peaks session migrate-skill-name` subcommand eagerly alongside
+// checkpoint / resume / auto-compact-hook so it appears in
+// `peaks session --help` for LLM `<TAB>`-discovery. See
+// src/services/migrate-skill-name/.
+import { registerSessionMigrateSkillNameCommand } from '../session-migrate-skill-name.js';
+export function registerSessionCommand(program, io) {
+    const session = program.command('session').description('Manage Peaks session directories');
+    addJsonOption(session
+        .command('list')
+        .description('List all session directories with titles and metadata')).action((options) => {
+        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        const metas = listSessionMetas(projectRoot);
+        printResult(io, ok('session.list', { sessions: metas, total: metas.length }), options.json);
+    });
+    addJsonOption(session
+        .command('info [sessionId]')
+        .description('Show full metadata for a session directory. Pass --active to resolve the canonical binding from .peaks/_runtime/session.json (the "one command a sub-agent runs to find the parent\'s sid" primitive). Slice 021: --active is the SOLE authoritative way to look up the active session id; the on-disk file path is internal and must NOT be `cat`-ed directly.')
+        .option('--active', 'resolve the canonical session id from .peaks/_runtime/session.json (ignores [sessionId] when set)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd). Slice 021: lets sub-agents skip the cwd heuristic and look up the binding for a specific repo.')
+        // Slice 020 — caller-keyed session binding. The --caller-id flag
+        // overrides the per-process PEAKS_CALLER_ID env var and the
+        // PLATFORM_FALLBACKS table (D4 priority). The resolved callerId is
+        // surfaced in the JSON envelope so callers can confirm what was
+        // resolved without re-deriving it.
+        .option('--caller-id <id>', 'Override the caller id for this invocation (D4 priority: flag beats env beats platform fallback). When set, the response envelope includes the resolved callerId.')).action(async (sessionId, options) => {
+        // Slice 021: --project wins; otherwise the git-root / cwd fallback
+        // (matches the pre-021 behaviour so the existing slice-020 / slice-007
+        // sub-agent flow keeps working unchanged).
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        // Slice 020 — resolve the callerId up front when the flag was passed.
+        // We use `resolveCallerId` for D1/D5 validation; an invalid flag
+        // throws CallerIdError (D5 → exit 65). A missing flag and no env
+        // and no fallback also throws (D2 → exit 64). The resolved id is
+        // surfaced in the envelope so the caller can audit.
+        if (options.callerId !== undefined) {
+            const { resolveCallerId, CallerIdError } = await import('../../../services/session/resolve-caller-id.js');
+            let callerId;
+            try {
+                callerId = resolveCallerId({ flagValue: options.callerId });
+            }
+            catch (error) {
+                if (error instanceof CallerIdError) {
+                    const code = error.code === 'EX_USAGE' ? 64 : 65;
+                    printResult(io, fail('session.info', 'CALLER_ID_INVALID', error.message, { source: error.source }, [`Set --caller-id to a value matching ^[a-zA-Z0-9._-]{1,200}$`, 'Or set PEAKS_CALLER_ID env var (or CLAUDE_CODE_SESSION_ID for Claude Code)']), options.json);
+                    process.exitCode = code;
+                    return;
+                }
+                throw error;
+            }
+            // Surface the resolved id in the envelope. When --active is also
+            // passed, look up the binding for this callerId; otherwise
+            // just emit the resolved id so the caller knows what was used.
+            if (options.active === true) {
+                const { getSessionIdCanonical } = await import('../../../services/session/session-manager.js');
+                const { getCallerBinding } = await import('../../../services/session/caller-binding-service.js');
+                const activeSid = getSessionIdCanonical(projectRoot);
+                const callerBinding = getCallerBinding(projectRoot, callerId);
+                // Slice 021: source is the enum that the unified --active primitive
+                // reports. Callers / migration tooling can detect pre-migration trees
+                // by inspecting `source === 'legacy'`.
+                const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                    ? 'canonical'
+                    : 'legacy';
+                printResult(io, ok('session.info', {
+                    active: true,
+                    sessionId: activeSid,
+                    callerId,
+                    callerBindingPeakSessionId: callerBinding?.peakSessionId ?? null,
+                    source: bindingSource
+                }), options.json);
+                return;
+            }
+            printResult(io, ok('session.info', { callerId, note: '--caller-id resolved; pass --active to also look up the bound peak session' }), options.json);
+            return;
+        }
+        // Slice 007 + slice 021 — sub-agent session sharing. A sub-agent that
+        // does not know the parent's sid reads it from the binding via
+        // `peaks session info --active`. Slice 021 turned this into the
+        // SOLE authoritative discovery primitive: it composes on
+        // getSessionIdCanonical (canonicalize-on-read; handles the stored
+        // "projectRoot: '.'" vs caller-passed absolute realpath mismatch
+        // that the F22 fix addressed) AND falls through to getSessionId
+        // (strict-equality) for callers on the original contract. NEITHER
+        // path may call ensureSession() — that would side-effect-create a
+        // fresh binding on miss, erasing the "no active session" signal
+        // sub-agents rely on.
+        if (options.active === true) {
+            // Import lazily to avoid a cycle with workspace-commands.
+            const { getSessionIdCanonical, getSessionId } = await import('../../../services/session/session-manager.js');
+            // 1. Canonicalize-on-read first.
+            let activeSid = getSessionIdCanonical(projectRoot);
+            // 2. Fall through to the strict-equality reader if the canonical
+            //    miss is a projectRoot-form mismatch (e.g. the binding was
+            //    written with the absolute realpath but the caller's form
+            //    normalizes differently). The 2-read fan-out mirrors the
+            //    fallback ensureSession() uses.
+            if (activeSid === null) {
+                activeSid = getSessionId(projectRoot);
+            }
+            if (activeSid === null) {
+                // 3. No binding at all — fail loudly, NO crash, NO side-effect,
+                //    exit 1, message must point at `peaks workspace init`
+                //    (the canonical "first action" command, not the legacy
+                //    "or `peaks skill presence:set`" hedge that the pre-021
+                //    wording used — presence:set would also need a binding to
+                //    resolve the parent sid, so it's not actually a bootstrap
+                //    path).
+                printResult(io, fail('session.info', 'NO_ACTIVE_SESSION', 'No session bound. Run `peaks workspace init --project <repo> --json` to bind one.', { projectRoot }, [`peaks workspace init --project ${projectRoot} --json`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // 4. Determine the on-disk source so callers (and future
+            //    migration tooling) can detect pre-migration trees. The
+            //    canonical file is preferred when both exist (slice 005
+            //    contract).
+            const bindingSource = existsSync(join(projectRoot, '.peaks', '_runtime', 'session.json'))
+                ? 'canonical'
+                : 'legacy';
+            // Slice 021: when only the legacy back-compat path is present,
+            // surface a warning so callers (and humans tailing the JSON)
+            // see "this tree has not been reconciled to the canonical
+            // home yet". The warning is informational; the binding is
+            // still valid for one minor release (slice 005 / 006
+            // contract). `warnings` is a top-level envelope field, not a
+            // data field, so it goes through ok()'s 3rd positional arg.
+            const legacyWarnings = bindingSource === 'legacy'
+                ? ['Read from legacy back-compat path .peaks/.session.json. Run `peaks workspace reconcile --apply` to migrate to the canonical home (.peaks/_runtime/session.json).']
+                : [];
+            printResult(io, ok('session.info', {
+                active: true,
+                sessionId: activeSid,
+                bindingPath: bindingSource === 'canonical'
+                    ? join(projectRoot, '.peaks', '_runtime', 'session.json')
+                    : join(projectRoot, '.peaks', '.session.json'),
+                projectRoot,
+                source: bindingSource
+            }, legacyWarnings), options.json);
+            return;
+        }
+        if (sessionId === undefined) {
+            printResult(io, fail('session.info', 'SESSION_ID_REQUIRED', 'session.info requires a <sessionId> or --active', {}, ['Pass a <sessionId> argument, or use --active to resolve the canonical binding']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const meta = getSessionMeta(projectRoot, sessionId);
+        if (meta === null) {
+            printResult(io, fail('session.info', 'SESSION_NOT_FOUND', `Session "${sessionId}" not found or has no metadata`, { sessionId }, ['Use `peaks session list` to see available sessions']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('session.info', meta), options.json);
+    });
+    addJsonOption(session
+        .command('title <sessionId> <title>')
+        .description('Set a human-readable title for a session directory')).action((sessionId, title, options) => {
+        const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+        try {
+            const meta = setSessionTitle(projectRoot, sessionId, title);
+            printResult(io, ok('session.title', meta), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('session.title', 'SESSION_TITLE_FAILED', getErrorMessage(error), { sessionId }, ['Verify the sessionId exists under .peaks/']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Slice 011: `peaks session checkpoint` and `peaks session resume`.
+    // Skill-level primitives — the LLM is the decision-maker; CLI is the muscle.
+    // Slice 2026-07-01-strategic-compact-cli fix: register EAGERLY (not
+    // via `void (async () => …)`) so commander walks the subcommand
+    // tree synchronously and `peaks session --help` includes both
+    // `checkpoint` and `resume`. The previous async-IIFE registered
+    // them on a microtask tick AFTER the program-level help builder
+    // had already serialised its output, so they were hidden from
+    // `<TAB>`-discovery and the LLM never saw them.
+    registerSessionCheckpointCommand(session, io);
+    registerSessionResumeCommand(session, io);
+    // Slice 2026-07-02-auto-compact-zero-pause: the Bash command the
+    // PreToolUse hook in `.claude/settings.local.json` fires. Keeping
+    // it eager (same fix as checkpoint + resume) so `peaks session --help`
+    // lists it for LLM `<TAB>`-discovery.
+    registerSessionAutoCompactHookCommand(session);
+    // Slice 2 of the peaks-code → peaks-code rename plan:
+    // `peaks session migrate-skill-name --from <old> --to <new>
+    // [--apply] [--project <path>] [--json]`. Idempotent rewrite of
+    // .peaks/_runtime/** for the rename; skipped paths recorded in
+    // the response envelope. See src/services/migrate-skill-name/.
+    registerSessionMigrateSkillNameCommand(session);
+    addJsonOption(session
+        .command('rotate')
+        .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--reason <text>', 'human-readable reason for the rotation, recorded in the response data')).action(async (options) => {
+        try {
+            // Canonicalise the project root before touching the binding.
+            // `peaks workspace init` writes the binding with the
+            // realpath-resolved projectRoot; if the caller passes a path
+            // through a symlink (notably /tmp on macOS, which is a
+            // symlink to /private/tmp) without canonicalising here,
+            // readSessionFile's strict projectRoot equality check fails
+            // and the rotate call reports "no prior binding" even
+            // though one exists. The same fix as `workspace init`
+            // (b193714): promote the path to the git root, falling back
+            // to the heuristic, falling back to cwd verbatim.
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const canonical = resolveCanonicalProjectRoot(projectRoot);
+            const previousSessionId = rotateSessionBinding(canonical);
+            printResult(io, ok('session.rotate', {
+                previousSessionId,
+                ...(options.reason !== undefined ? { reason: options.reason } : {}),
+                note: previousSessionId === null
+                    ? 'No prior binding was present; the project is already unbound.'
+                    : 'Next ensureSession() call will auto-generate a fresh id. The previous session directory is still on disk at .peaks/_runtime/<previousSessionId>/.'
+            }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('session.rotate', 'SESSION_ROTATE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}