peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

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

@@ -0,0 +1,264 @@
+import { runDoctor } from 'peaks-loop-doctor';
+import { readBinding, dropStale, rebuildBindingFromLegacy } from '../../../services/session/binding-store.js';
+import { findProjectRoot } from '../../../services/config/config-safety.js';
+import { loadSkillRegistry } from '../../../services/skills/skill-registry.js';
+import { planStatusLineInstall } from '../../../services/skills/statusline-settings-service.js';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+// slice-3b Option C: the doctor subpackage owns the check pipeline but
+// does NOT import cross-domain utils from the main package (avoids
+// circular deps). The CLI is the natural wiring point — every cross-
+// domain util the doctor used to import directly is now injected as a
+// probe on DoctorOptions at call-site:
+//
+//   loadSkills           ← loadSkillRegistry (main/services/skills/skill-registry.ts)
+//   skillPresenceProbe   ← leave as-is; doctor-command does not own the presence probe
+//   statusLineInstalledProbe ← defaults to a `planStatusLineInstall` wrapper below
+//   projectRootResolver  ← findProjectRoot (main/services/config/config-safety.ts)
+//   isValidSessionIdProbe ← the regex kept in main/services/workspace/sid-naming-guard.ts
+//
+// Inlining isValidSessionId via the doctor subpackage's default regex
+// (which mirrors the upstream file byte-for-byte) keeps the L3 orphan
+// check behaviour-identical without dragging sid-naming-guard into a
+// workspace package. If sid-naming-guard is ever moved into
+// peaks-loop-shared, swap this for a re-import.
+function doctorIsValidSessionId(sid) {
+    return /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-session-[0-9a-z]{3,6}$/.test(sid);
+}
+function statusLineAlreadyInstalledForScope(scope, projectRoot) {
+    try {
+        if (scope === 'project') {
+            if (projectRoot === undefined)
+                return false;
+            return planStatusLineInstall('project', projectRoot).alreadyInstalled;
+        }
+        return planStatusLineInstall('global').alreadyInstalled;
+    }
+    catch {
+        return false;
+    }
+}
+function doctorStatusLineInstalledProbe() {
+    const projectRoot = findProjectRoot(process.cwd());
+    // Check both scopes: a user may have installed the statusLine globally, which
+    // the project-only check would miss and falsely report as "not installed".
+    try {
+        if (projectRoot !== null && statusLineAlreadyInstalledForScope('project', projectRoot)) {
+            return true;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* fall through to global */
+    }
+    try {
+        return statusLineAlreadyInstalledForScope('global');
+    }
+    catch {
+        return false;
+    }
+}
+// Slice v2.16.0 AC-10: stale binding TTL is 5 minutes by default. The
+// threshold is exposed as a CLI flag so users can tune it for
+// long-running sessions.
+const STALE_TTL_MS = 5 * 60 * 1000;
+// Slice v2.16.0 AC-10: identify stale instances (lastHeartbeat > 5min)
+// in the project-level binding. Used by `peaks doctor` and surfaced as
+// a warning in the report. Returns the stale entry descriptors.
+function listStaleInstances(projectRoot, ttlMs = STALE_TTL_MS) {
+    const binding = readBinding(projectRoot);
+    if (!binding)
+        return [];
+    const cutoff = Date.now() - ttlMs;
+    const stale = [];
+    for (const [sid, inst] of Object.entries(binding.instances)) {
+        const t = Date.parse(inst.lastHeartbeat);
+        if (Number.isFinite(t) && t < cutoff) {
+            stale.push({ sid, callerId: inst.callerId, lastHeartbeat: inst.lastHeartbeat });
+        }
+    }
+    return stale;
+}
+// Slice 2026-06-16-cli-logging (AC6) — `peaks doctor --log` section.
+//
+// `buildDoctorLogsSection` reads the on-disk log dir and returns the
+// metadata the doctor needs to render the "logs" block. It is
+// extracted from the inline `peaks doctor --log` action so the
+// command stays small and the helper is unit-testable without
+// spinning up the full program.
+async function buildDoctorLogsSection() {
+    // Lazy imports to avoid a circular dep at module-load time
+    // (core-artifact-commands is imported very early in program.ts).
+    const { resolveLogDir, buildLogFileName } = await import('../../../services/log/logger.js');
+    const { statSync, existsSync } = await import('node:fs');
+    const { join } = await import('node:path');
+    const logDir = resolveLogDir();
+    const todayFile = buildLogFileName(new Date());
+    const fullPath = join(logDir, todayFile);
+    let sizeBytes = 0;
+    if (existsSync(fullPath)) {
+        try {
+            sizeBytes = statSync(fullPath).size;
+        }
+        catch {
+            sizeBytes = 0;
+        }
+    }
+    return {
+        logDir,
+        todayFile,
+        sizeBytes,
+        retentionDays: 7,
+        level: process.env.PEAKS_LOG_LEVEL ?? 'info'
+    };
+}
+// Slice 2026-06-16-cli-logging (AC6): `peaks doctor --log` adds a
+// "logs" section to the doctor output (logDir, today's file name,
+// size, retention policy, level). Useful for the user when they
+// want to attach a quick log snapshot to a bug report without
+// running `peaks log tail` first. The flag is opt-in so the
+// existing doctor output is preserved (P4).
+export function registerDoctorCommand(program, io) {
+    addJsonOption(program
+        .command('doctor')
+        .description('Run repository doctor checks')
+        .option('--log', 'include a "logs" section in the doctor output (slice 2026-06-16-cli-logging, AC6)')
+        .option('--cleanup-stale', 'drop stale instance entries from the project-level binding (v2.16.0 AC-10)')
+        .option('--stale-ttl-ms <ms>', 'stale-binding TTL in milliseconds (default 300000 = 5 minutes, v2.16.0 AC-10)')
+        // v2.18.2 PATCH scope (follow-up issue #1): rewrite legacy
+        // v2.16.0 / v2.17.0 binding files in place so every existing
+        // callerId gets the `${envSignal}#${pid}` suffix introduced in
+        // v2.18.0. Mutually exclusive with --cleanup-stale to keep the
+        // semantics unambiguous (rebuild = structural change,
+        // cleanup-stale = TTL-based prune).
+        .option('--rebuild-binding', 'rewrite legacy v2.16.0 / v2.17.0 callerId entries to the v2.18.0+ `#${pid}` format (v2.18.2, follow-up issue #1)')
+        // v2.18.2 cycle 2: --project makes the project-root-bound
+        // flags (--rebuild-binding, --cleanup-stale, stale-binding
+        // scan) addressable for non-current projects. The doctor was
+        // hardcoded to findProjectRoot(process.cwd()) which is the
+        // wrong default for users inspecting a sibling project.
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (options) => {
+        // v2.18.2 cycle 2 (Q2 arbitration): --rebuild-binding and
+        // --cleanup-stale BOTH mutate the binding file. Running them
+        // together is ambiguous (rebuild rewrites callerIds; cleanup
+        // prunes entries). Hard-reject the combination so the user
+        // gets an actionable error instead of a silent short-circuit.
+        if (options.rebuildBinding === true && options.cleanupStale === true) {
+            const envelope = fail('doctor.rebuild-binding', 'CONFLICTING_FLAGS', '--rebuild-binding and --cleanup-stale are mutually exclusive', { rebuildBinding: true, cleanupStale: true }, ['Run them in separate `peaks doctor` invocations']);
+            printResult(io, envelope, options.json === true);
+            process.exitCode = 1;
+            return;
+        }
+        // v2.18.2 cycle 2: --project override, applies to BOTH the
+        // --rebuild-binding short-circuit AND the binding-stale scan.
+        const projectRoot = options.project !== undefined
+            ? options.project
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        // v2.18.2: short-circuit on --rebuild-binding so the doctor
+        // checks don't run when the user is asking for a single targeted
+        // migration. The rebuild is observable in its own right
+        // (rewritten/preserved counts) and does not benefit from running
+        // the full doctor surface first.
+        if (options.rebuildBinding === true) {
+            const result = rebuildBindingFromLegacy(projectRoot);
+            if (result.errors.length > 0) {
+                for (const err of result.errors) {
+                    io.stderr(`  warning: ${err}`);
+                }
+            }
+            const data = {
+                rebuilt: !result.noop,
+                rewritten: result.rewritten,
+                preserved: result.preserved,
+                errors: result.errors,
+                projectRoot
+            };
+            const envelope = result.rewritten === 0
+                ? ok('doctor.rebuild-binding', data, [], result.noop ? ['no legacy callerId entries found — nothing to rewrite'] : [])
+                : fail('doctor.rebuild-binding', result.noop ? 'BINDING_REBUILD_NOOP' : 'BINDING_REBUILD_OK', result.noop
+                    ? 'No legacy callerId entries to rewrite'
+                    : `Rewrote ${result.rewritten} legacy callerId entry/entries (preserved ${result.preserved})`, data, ['Re-run `peaks binding status` to verify the rewritten entries']);
+            printResult(io, envelope, options.json === true);
+            if (result.errors.length > 0 && result.rewritten === 0) {
+                process.exitCode = 1;
+            }
+            return;
+        }
+        const report = await runDoctor({
+            // slice-3b Option C: wire cross-domain probes at call-site.
+            loadSkills: loadSkillRegistry,
+            projectRootResolver: () => findProjectRoot(process.cwd()),
+            isValidSessionIdProbe: doctorIsValidSessionId,
+            statusLineInstalledProbe: doctorStatusLineInstalledProbe
+        });
+        let logsSection = null;
+        if (options.log === true) {
+            logsSection = await buildDoctorLogsSection();
+        }
+        // v2.16.0 AC-10: scan binding for stale instances.
+        const ttl = options.staleTtlMs !== undefined ? Number(options.staleTtlMs) : STALE_TTL_MS;
+        const staleInstances = listStaleInstances(projectRoot, ttl);
+        let droppedStale = [];
+        if (options.cleanupStale === true) {
+            const { dropped } = dropStale(projectRoot, ttl);
+            droppedStale = dropped;
+        }
+        const staleBindingSection = {
+            ttlMs: ttl,
+            staleCount: staleInstances.length,
+            staleInstances,
+            droppedCount: droppedStale.length,
+            droppedSids: droppedStale
+        };
+        const data = logsSection === null
+            ? { ...report, staleBinding: staleBindingSection }
+            : { ...report, logs: logsSection, staleBinding: staleBindingSection };
+        const result = report.summary.ok && staleInstances.length === 0
+            ? ok('doctor', data)
+            : fail('doctor', 'DOCTOR_FAILED', staleInstances.length > 0
+                ? `Found ${staleInstances.length} stale binding instance(s); rerun with --cleanup-stale to drop them`
+                : 'One or more doctor checks failed', data, staleInstances.length > 0
+                ? ['Run `peaks doctor --cleanup-stale` to drop stale entries']
+                : ['Fix failed checks and rerun peaks doctor']);
+        if (options.json === true) {
+            printResult(io, result, true);
+        }
+        else {
+            // Human-readable: one line per check, green/red indicators, no JSON.
+            for (const check of report.checks) {
+                const icon = check.ok ? '+' : '×';
+                io.stdout(`  ${icon}  ${check.message}`);
+            }
+            if (logsSection !== null) {
+                io.stdout('\n  logs:');
+                io.stdout(`    logDir:        ${logsSection.logDir}`);
+                io.stdout(`    todayFile:     ${logsSection.todayFile}`);
+                io.stdout(`    sizeBytes:     ${logsSection.sizeBytes}`);
+                io.stdout(`    retentionDays: ${logsSection.retentionDays}`);
+                io.stdout(`    level:         ${logsSection.level}`);
+            }
+            io.stdout('\n  stale-binding (v2.16.0 AC-10):');
+            if (staleInstances.length === 0) {
+                io.stdout('    + no stale instances');
+            }
+            else {
+                io.stdout(`    × ${staleInstances.length} stale instance(s):`);
+                for (const s of staleInstances) {
+                    io.stdout(`      - sid=${s.sid} caller=${s.callerId} lastSeen=${s.lastHeartbeat}`);
+                }
+                if (droppedStale.length > 0) {
+                    io.stdout(`    cleaned up: ${droppedStale.length}`);
+                }
+                else {
+                    io.stdout('    rerun with --cleanup-stale to drop them');
+                }
+            }
+            io.stdout(`\n  ${report.summary.passed} passed, ${report.summary.failed} failed`);
+            if (!report.summary.ok || staleInstances.length > 0) {
+                io.stderr(`\nDOCTOR_FAILED: ${staleInstances.length > 0 ? 'stale binding present' : `${report.summary.failed} check(s) failed`}.`);
+            }
+        }
+        if (!report.summary.ok || staleInstances.length > 0) {
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,98 @@
+import { executeProjectMemoryBackup, executeProjectMemoryExtract, summarizeProjectMemoryBackupResult, summarizeProjectMemoryExtractResult } from '../../../services/memory/project-memory-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerMemoryCommand(program, io) {
+    const memory = program.command('memory').description('Manage project-local Peaks memory');
+    addJsonOption(memory
+        .command('extract')
+        .description('Extract stable project memory from skill artifacts into project .peaks/memory')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--artifact <path...>', 'skill artifact paths inside the project')
+        .option('--dry-run', 'preview writes without changing files')
+        .option('--apply', 'write extracted memories into project .peaks/memory')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.extract', 'INVALID_MEMORY_EXTRACT_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview writes, or pass --apply to write memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectMemoryExtract({ projectRoot: options.project, artifactPaths: options.artifact, apply: options.apply === true });
+            printResult(io, ok('memory.extract', summarizeProjectMemoryExtractResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('memory.extract', 'MEMORY_EXTRACT_FAILED', getErrorMessage(error), {}, ['Check artifact paths and remove secrets before extracting memory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(memory
+        .command('sync')
+        .description('Back up project .peaks/memory into the artifact workspace')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--workspace <path>', 'artifact workspace path')
+        .option('--dry-run', 'preview copies without changing files')
+        .option('--apply', 'copy project .peaks/memory into artifact workspace backup')).action((options) => {
+        if (options.dryRun === true && options.apply === true) {
+            printResult(io, fail('memory.sync', 'INVALID_MEMORY_SYNC_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview copies, or pass --apply to back up memories']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const result = executeProjectMemoryBackup({ projectRoot: options.project, artifactWorkspacePath: options.workspace, apply: options.apply === true });
+            printResult(io, ok('memory.sync', summarizeProjectMemoryBackupResult(result)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('memory.sync', 'MEMORY_SYNC_FAILED', getErrorMessage(error), {}, ['Use an artifact workspace outside the project root']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(memory
+        .command('list')
+        .description('List all memory entries from .peaks/memory/index.json. Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/memory/picked.json.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
+        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((options) => {
+        void import('../memory-commands.js').then(({ runMemoryList }) => {
+            void runMemoryList(io, {
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.pick === true ? { pick: true } : {}),
+                ...(options.fzfBin ? { fzfBin: options.fzfBin } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            const msg = /brew install fzf|apt-get install fzf|older than required/.test(getErrorMessage(error))
+                ? 'fzf binary not found or too old. Install with: brew install fzf (or apt: apt-get install fzf). peaks memory list --pick requires fzf >= 0.38.'
+                : getErrorMessage(error);
+            const code = /brew install fzf|apt-get install fzf|older than required/.test(msg) ? 'FZF_UNAVAILABLE' : 'MEMORY_LIST_BOOTSTRAP_FAILED';
+            printResult(io, fail('memory.list', code, msg, {}, ['Install fzf or run without --pick to list entries as JSON']), options.json);
+            if (code === 'FZF_UNAVAILABLE')
+                process.exitCode = 127;
+            else
+                process.exitCode = 1;
+        });
+    });
+    addJsonOption(memory
+        .command('search <query>')
+        .description('Fuzzy-search the memory index (deterministic, local, zero-token). Default --limit 6. Pass --compress-results to also emit a headroom-compressed text view of the matches for LLM-side prompt assembly.')
+        .option('--kind <kind>', 'filter by memory kind (one of: project, rule, decision, reference, feedback, convention, module, lesson)')
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--compress-results', 'compress joined match text via headroom-ai (uses preferences.headroom.perTouchpoint.memorySearch mode)')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        // Lazy import avoids a top-of-file import cycle (memory-commands.ts
+        // imports services that the rest of this file may also touch).
+        void import('../memory-commands.js').then(({ runMemorySearch }) => {
+            void runMemorySearch(io, {
+                query,
+                ...(options.kind !== undefined ? { kind: options.kind } : {}),
+                ...(options.limit !== undefined ? { limit: options.limit } : {}),
+                ...(options.compressResults === true ? { compressResults: true } : {}),
+                ...(options.project !== undefined ? { project: options.project } : {}),
+                ...(options.json !== undefined ? { json: options.json } : {}),
+            });
+        }).catch((error) => {
+            printResult(io, fail('memory.search', 'MEMORY_SEARCH_BOOTSTRAP_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        });
+    });
+}

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

@@ -0,0 +1,9 @@
+import { listProfiles } from '../../../services/profiles/profile-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../../cli-helpers.js';
+export function registerProfileCommand(program, io) {
+    const profile = program.command('profile').description('Manage runtime profiles');
+    addJsonOption(profile.command('list').description('List available profiles')).action((options) => {
+        printResult(io, ok('profile.list', { profiles: listProfiles() }), options.json);
+    });
+}

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

@@ -0,0 +1,26 @@
+import { planProxyTest } from '../../../services/proxy/proxy-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, failUnsupportedNonDryRun, getErrorMessage, printResult } from '../../cli-helpers.js';
+export function registerProxyCommand(program, io) {
+    const proxy = program.command('proxy').description('Manage proxy settings');
+    addJsonOption(proxy
+        .command('test')
+        .description('Plan or run a proxy connectivity test')
+        .requiredOption('--proxy <url>', 'proxy URL')
+        .option('--target <url>', 'target URL', 'https://www.google.com')
+        .option('--dry-run', 'only print the planned command', true)
+        .option('--no-dry-run', 'unsupported: do not execute connectivity tests from this CLI')).action((options) => {
+        if (options.dryRun === false) {
+            failUnsupportedNonDryRun(io, 'proxy.test', options.json);
+            return;
+        }
+        try {
+            const plan = planProxyTest(options.proxy, options.target, true);
+            printResult(io, ok('proxy.test', plan), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('proxy.test', 'INVALID_PROXY', getErrorMessage(error), {}, ['Use a proxy URL starting with http:// or https://']), options.json);
+            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 'peaks-loop-shared/result';
+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;
+        }
+    });
+}