peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,322 @@
+// src/cli/commands/job-commands.ts
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { writeJobProgress, readJobProgress, tryReadJobProgress } from '../../services/job/job-progress-store.js';
+import { JobRotation } from '../../services/job/job-rotation.js';
+import { SubAgentJobWrapper } from '../../services/job/subagent-job-wrapper.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { buildCostCheckEnvelope, runKarpathyCostCheck, } from '../../services/karpathy-cost/karpathy-cost-check-service.js';
+import { read24hState } from '../../services/24h-mode/store.js';
+function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order:
+ * 1. `--session-id` flag (explicit override)
+ * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-code
+ * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ */
+function resolveJobStateRoot(opts) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-code session via peaks workspace init');
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    return { rootDir, sessionId, projectRoot: project };
+}
+export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
+    const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-code Step 0.8+)');
+    job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+        // a random UUID would scatter state across dirs and break resume/auto-compact.
+        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-code session via peaks workspace init)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first'
+            ]), opts);
+        }
+        const parsed = JobInitInputSchema.safeParse({
+            jobId: opts.jobId,
+            sessionId,
+            sliceList: opts.sliceList.split(',').map((s) => s.trim()).filter(Boolean),
+            parallelismHint: opts.parallelismHint,
+            exitPolicy: opts.exitPolicy,
+            mainLoopStrategy: opts.mainLoopStrategy,
+            rotateEvery: Number(opts.rotateEvery),
+            project,
+            json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        const state = orch.init({
+            jobId: parsed.data.jobId,
+            sessionId: parsed.data.sessionId,
+            sliceList: parsed.data.sliceList,
+            parallelismHint: parsed.data.parallelismHint,
+            exitPolicy: parsed.data.exitPolicy,
+            mainLoopStrategy: parsed.data.mainLoopStrategy,
+            rotateEvery: parsed.data.rotateEvery,
+        });
+        try {
+            emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job init
+            void e;
+        }
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'init'));
+    job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        if (opts.watch) {
+            const draw = () => {
+                const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+                process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+            };
+            draw();
+            const iv = setInterval(() => { const u = orch.status(opts.jobId); Object.assign(s, u); draw(); if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv); }, 3000);
+            process.on('SIGINT', () => { clearInterval(iv); process.stdout.write('\n'); process.exit(0); });
+            return;
+        }
+        try {
+            emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job status
+            void e;
+        }
+        printResult(io, ok('status', s), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'status'));
+    // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
+    job.command('rotate-now')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
+        const r = await rotation.rotateNow(opts.jobId);
+        printResult(io, ok('rotate-now', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
+    job.command('subagent-cleanup')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--batch-id <bid>')
+        .option('--force')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
+        printResult(io, ok('subagent-cleanup', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
+    // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
+    job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobCheckpointInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, state: opts.state,
+            commitSha: opts.commitSha, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        if (parsed.data.state === 'done') {
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+            // v3.1.2: after each --state done, mirror slice progress to
+            // .peaks/_runtime/<sessionId>/job/<jid>/progress.json so the
+            // next LLM turn (or peaks code gate-step-08 hook) can read it.
+            const project = projectRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const state = orch.status(parsed.data.jobId);
+            writeJobProgress(project, sessId, {
+                jobId: parsed.data.jobId,
+                done: state.done,
+                total: state.total,
+                currentSlice: state.currentSlice ?? `slice-${state.done + 1}`,
+                lastCommitSha: parsed.data.commitSha ?? null,
+                updatedAt: new Date().toISOString()
+            });
+        }
+        else if (parsed.data.state === 'skipped') {
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        else {
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
+    job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobBlockInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        await orch.blockSlice(parsed.data);
+        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'block'));
+    job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const r = orch.continueNow(opts.jobId);
+        printResult(io, ok('continue', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'continue'));
+    job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    // v3.1.2: read the on-disk slice progress mirror written by `peaks
+    // job checkpoint --state done`. Used by peaks code gate-step-08 and
+    // by peaks-code Step 0.7 (resume) to surface `Next: slice #N of M
+    // (<currentSlice>)` without re-deriving from state.json.
+    job
+        .command('progress')
+        .description('v3.1.2: read the on-disk slice progress mirror (.peaks/_runtime/<sid>/job/<jid>/progress.json). ' +
+        'Returns { jobId, done, total, currentSlice, lastCommitSha, updatedAt }.')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .option('--allow-missing', 'return done=0/total=0 envelope instead of failing when progress.json is absent')
+        .action(async (opts) => {
+        try {
+            const jobRoot = resolveJobStateRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const project = projectRoot(opts);
+            const progress = opts.allowMissing === true
+                ? tryReadJobProgress(project, sessId, opts.jobId)
+                : readJobProgress(project, sessId, opts.jobId);
+            if (progress === null) {
+                printResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
+                    'Run `peaks job checkpoint --state done ...` at least once to seed progress.json.',
+                    'Or pass --allow-missing to return a zero-progress envelope.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('progress', progress, [], [
+                `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'progress'));
+    job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'handoff'));
+    job
+        .command('karpathy-cost-check')
+        .description('Read the slice\'s rd/karpathy-review.md and decide whether to downgrade a block gateAction to warn (slice 2026-07-30-karpathy-cost-self-review).')
+        .requiredOption('--review-file <path>', 'path to rd/karpathy-review.md (or its .json sibling if the file is JSON)')
+        .option('--project <repo>')
+        .option('--session-id <sid>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('karpathy-cost-check', 'NO_ACTIVE_SESSION', 'karpathy-cost-check requires --session-id (or an active peaks-code session)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first',
+            ]), opts);
+        }
+        const is24hModeActive = () => {
+            try {
+                const snapshot = read24hState(project, sessionId);
+                return snapshot.state === '24H_ACTIVE';
+            }
+            catch {
+                return false;
+            }
+        };
+        const out = runKarpathyCostCheck({
+            reviewFilePath: opts.reviewFile,
+            is24hModeActive,
+        });
+        printResult(io, buildCostCheckEnvelope(out), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'karpathy-cost-check'));
+    program.addCommand(job);
+}

package/dist/cli/commands/lease-metrics-commands.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `peaks lease-metrics` — slice 2026-07-29-worktree-l2-extended Part 4.A + Part 5.
+ *
+ * Part 4.A: aggregate lease-kind observability events for one session,
+ * render per-kind counts + a 5-event chronological tail.
+ *
+ * Part 5 adds:
+ *   - `--rate`         : leak-rate computation (spawn - release - gc)
+ *                        plus lifetime stats (avg / p99) per lease id.
+ *   - `--all-sessions` : aggregate across every session under
+ *                        `.peaks/_runtime/<sid>/metrics/slices.jsonl`
+ *                        for the given project root. Useful for
+ *                        cross-session dashboards.
+ *
+ * Aggregation is pure (operates on already-read ObservabilityEvent[]);
+ * the IO layer is the JSONL read at the call site. The reader filters
+ * on `category === 'lease'`; the schema is the same as every other
+ * observability event (Part 4.A reused the existing schema v1).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type ObservabilityEvent } from '../../services/observability/observability-service.js';
+/**
+ * Part 5: leak-rate + lifetime statistics.
+ *
+ * Leaks are leases that were spawned but neither released (manual)
+ * nor auto-released nor gc'd. A naive count is
+ * `spawn - release - gc - autoRelease`; the result is the number
+ * of currently-alive leases in the absence of in-flight work
+ * (the on-disk lease files in `.peaks/_runtime/<sid>/worktree-leases/`
+ * are the canonical "alive" set; this aggregation is an estimate
+ * for sessions whose files have been pruned but the metrics
+ * stream survived).
+ *
+ * Lifetime: pair each spawn event with its first terminal event
+ * (release / gc / autoRelease / autoRelease-failed) for the same
+ * leaseId; the duration is the difference in milliseconds. The
+ * result is an avg / p99 across the completed leases. p99 is the
+ * 99th percentile; with 0-1 completed leases the field is null.
+ */
+export type RateStats = {
+    readonly totalSpawn: number;
+    readonly totalTerminal: number;
+    /** spawn - terminal — leases still "alive" per the metrics stream alone. */
+    readonly estimatedActive: number;
+    /** Estimated leaked = active - autoRelease-failed. Positive = worktrees
+     *  the user / CLI will need to gc manually. */
+    readonly estimatedLeaked: number;
+    readonly completedLifetimes: number;
+    readonly avgLifetimeMs: number | null;
+    readonly p99LifetimeMs: number | null;
+};
+export declare function recomputeRate(leaseEvents: ReadonlyArray<ObservabilityEvent>): RateStats;
+/**
+ * Part 5: enumerate every session under `.peaks/_runtime/` for a
+ * project root and aggregate their lease events. Sessions without
+ * a `metrics/slices.jsonl` are skipped silently (a clean project
+ * has no lease events to report; that's not an error).
+ */
+export declare function readAllSessionLeaseEvents(projectRoot: string): {
+    sessions: ReadonlyArray<{
+        sessionId: string;
+        events: ReadonlyArray<ObservabilityEvent>;
+    }>;
+    missingSessions: number;
+};
+export declare function registerLeaseMetricsCommand(parent: Command, io: ProgramIO): void;

package/dist/cli/commands/lease-metrics-commands.js

@@ -0,0 +1,231 @@
+/**
+ * `peaks lease-metrics` — slice 2026-07-29-worktree-l2-extended Part 4.A + Part 5.
+ *
+ * Part 4.A: aggregate lease-kind observability events for one session,
+ * render per-kind counts + a 5-event chronological tail.
+ *
+ * Part 5 adds:
+ *   - `--rate`         : leak-rate computation (spawn - release - gc)
+ *                        plus lifetime stats (avg / p99) per lease id.
+ *   - `--all-sessions` : aggregate across every session under
+ *                        `.peaks/_runtime/<sid>/metrics/slices.jsonl`
+ *                        for the given project root. Useful for
+ *                        cross-session dashboards.
+ *
+ * Aggregation is pure (operates on already-read ObservabilityEvent[]);
+ * the IO layer is the JSONL read at the call site. The reader filters
+ * on `category === 'lease'`; the schema is the same as every other
+ * observability event (Part 4.A reused the existing schema v1).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { readObservabilityEvents } from '../../services/observability/observability-service.js';
+const EMPTY_COUNTS = {
+    spawn: 0,
+    renew: 0,
+    release: 0,
+    gc: 0,
+    autoRelease: 0,
+    'autoRelease-failed': 0,
+    'autoRelease-skipped': 0
+};
+/** Compute per-kind counts + chronological tail from a list of events. */
+function aggregateLeaseEvents(leaseEvents) {
+    const counts = { ...EMPTY_COUNTS };
+    const recent = [];
+    for (const ev of leaseEvents) {
+        const detail = (ev.detail ?? {});
+        const kind = typeof detail['kind'] === 'string' ? detail['kind'] : 'unknown';
+        const leaseId = typeof detail['leaseId'] === 'string' ? detail['leaseId'] : '';
+        const rid = typeof detail['rid'] === 'string' ? detail['rid'] : null;
+        const reason = typeof detail['reason'] === 'string' ? detail['reason'] : null;
+        if (kind in counts) {
+            counts[kind] = (counts[kind] ?? 0) + 1;
+        }
+        recent.push({ ts: ev.ts, kind, leaseId, rid, reason });
+    }
+    recent.sort((a, b) => b.ts.localeCompare(a.ts));
+    return { counts: counts, tail: recent.slice(0, 5) };
+}
+export function recomputeRate(leaseEvents) {
+    // Count per-kind in one pass.
+    const counts = { ...EMPTY_COUNTS };
+    for (const ev of leaseEvents) {
+        const detail = (ev.detail ?? {});
+        const kind = typeof detail['kind'] === 'string' ? detail['kind'] : 'unknown';
+        if (kind in counts) {
+            counts[kind] = (counts[kind] ?? 0) + 1;
+        }
+    }
+    const totalSpawn = counts['spawn'] ?? 0;
+    const totalRelease = (counts['release'] ?? 0) + (counts['gc'] ?? 0) + (counts['autoRelease'] ?? 0);
+    const estimatedActive = Math.max(0, totalSpawn - totalRelease);
+    const estimatedLeaked = Math.max(0, estimatedActive - (counts['autoRelease-failed'] ?? 0));
+    // Pair each lease id: first spawn → first terminal.
+    const firstSpawn = new Map();
+    const firstTerminal = new Map();
+    const tsOf = (ev) => Date.parse(ev.ts);
+    const leaseIdOf = (ev) => {
+        const d = (ev.detail ?? {});
+        return typeof d['leaseId'] === 'string' ? d['leaseId'] : '';
+    };
+    const kindOf = (ev) => {
+        const d = (ev.detail ?? {});
+        return typeof d['kind'] === 'string' ? d['kind'] : 'unknown';
+    };
+    for (const ev of leaseEvents) {
+        const id = leaseIdOf(ev);
+        if (id === '')
+            continue;
+        const t = tsOf(ev);
+        const k = kindOf(ev);
+        if (k === 'spawn' && !firstSpawn.has(id)) {
+            firstSpawn.set(id, t);
+        }
+        else if (k === 'release' || k === 'gc' || k === 'autoRelease' || k === 'autoRelease-failed') {
+            if (!firstTerminal.has(id))
+                firstTerminal.set(id, t);
+        }
+    }
+    const lifetimes = [];
+    for (const [id, start] of firstSpawn) {
+        const end = firstTerminal.get(id);
+        if (end === undefined)
+            continue;
+        const dt = end - start;
+        if (dt >= 0)
+            lifetimes.push(dt);
+    }
+    lifetimes.sort((a, b) => a - b);
+    const avg = lifetimes.length === 0 ? null : Math.round(lifetimes.reduce((s, v) => s + v, 0) / lifetimes.length);
+    const p99 = lifetimes.length === 0
+        ? null
+        : lifetimes[Math.min(lifetimes.length - 1, Math.floor(lifetimes.length * 0.99))] ?? null;
+    return {
+        totalSpawn,
+        totalTerminal: totalRelease,
+        estimatedActive,
+        estimatedLeaked,
+        completedLifetimes: lifetimes.length,
+        avgLifetimeMs: avg,
+        p99LifetimeMs: p99
+    };
+}
+/**
+ * Part 5: enumerate every session under `.peaks/_runtime/` for a
+ * project root and aggregate their lease events. Sessions without
+ * a `metrics/slices.jsonl` are skipped silently (a clean project
+ * has no lease events to report; that's not an error).
+ */
+export function readAllSessionLeaseEvents(projectRoot) {
+    const runtimeDir = join(projectRoot, '.peaks', '_runtime');
+    if (!existsSync(runtimeDir))
+        return { sessions: [], missingSessions: 0 };
+    let entries;
+    try {
+        entries = readdirSync(runtimeDir);
+    }
+    catch {
+        return { sessions: [], missingSessions: 0 };
+    }
+    const sessions = [];
+    let missing = 0;
+    for (const sid of entries) {
+        const sessionDir = join(runtimeDir, sid);
+        try {
+            if (!statSync(sessionDir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        try {
+            const all = readObservabilityEvents(projectRoot, sid);
+            const leaseEvents = all.filter((e) => e.category === 'lease');
+            if (leaseEvents.length === 0) {
+                missing++;
+                continue;
+            }
+            sessions.push({ sessionId: sid, events: leaseEvents });
+        }
+        catch {
+            missing++;
+        }
+    }
+    return { sessions, missingSessions: missing };
+}
+export function registerLeaseMetricsCommand(parent, io) {
+    addJsonOption(parent
+        .command('lease-metrics')
+        .description('Aggregate lease-kind observability events. Default: per-kind counts + 5-event tail for the current session. --rate: leak rate + lifetime stats. --all-sessions: aggregate across every session under .peaks/_runtime/.')
+        .option('--session <sid>', 'override session id (default: read .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: findProjectRoot(cwd))')
+        .option('--rate', 'compute leak rate (spawn - terminal) + lifetime stats (avg / p99)')
+        .option('--all-sessions', 'aggregate across every session under .peaks/_runtime/ (ignores --session)')).action((options) => {
+        try {
+            const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const allSessions = options.allSessions === true;
+            const showRate = options.rate === true;
+            if (allSessions) {
+                // Aggregate across every session.
+                const { sessions, missingSessions } = readAllSessionLeaseEvents(projectRoot);
+                const allEvents = sessions.flatMap((s) => s.events);
+                const { counts, tail } = aggregateLeaseEvents(allEvents);
+                const rate = showRate ? recomputeRate(allEvents) : null;
+                const envelope = {
+                    mode: 'all-sessions',
+                    projectRoot,
+                    sessionCount: sessions.length,
+                    missingSessions,
+                    sessions: sessions.map((s) => ({ sessionId: s.sessionId, leaseEvents: s.events.length })),
+                    totalEvents: allEvents.length,
+                    counts,
+                    tail
+                };
+                if (rate !== null)
+                    envelope['rate'] = rate;
+                printResult(io, ok('lease.metrics', envelope, [], [
+                    `${sessions.length} session(s) reported lease events; ${missingSessions} session(s) had no events.`,
+                    showRate && rate !== null
+                        ? `${rate.estimatedActive} estimated active, ${rate.estimatedLeaked} estimated leaked across sessions.`
+                        : 'Pass --rate to see leak-rate + lifetime stats.'
+                ]), options.json);
+                return;
+            }
+            // Single-session path (the Part 4.A default).
+            const sessionId = options.session ?? process.env.PEAKS_SESSION_ID ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+            const allEvents = readObservabilityEvents(projectRoot, sessionId);
+            const leaseEvents = allEvents.filter((e) => e.category === 'lease');
+            const { counts, tail } = aggregateLeaseEvents(leaseEvents);
+            const rate = showRate ? recomputeRate(leaseEvents) : null;
+            const envelope = {
+                mode: 'single-session',
+                sessionId,
+                projectRoot,
+                totalEvents: allEvents.length,
+                leaseEvents: leaseEvents.length,
+                counts,
+                tail
+            };
+            if (rate !== null)
+                envelope['rate'] = rate;
+            printResult(io, ok('lease.metrics', envelope, [], [
+                `${leaseEvents.length} lease-kind events recorded for session ${sessionId}.`,
+                showRate && rate !== null
+                    ? `${rate.estimatedActive} estimated active, ${rate.estimatedLeaked} estimated leaked.`
+                    : 'Run `peaks audit metrics --project .` for the full observability dashboard, or pass --rate / --all-sessions.'
+            ]), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('lease.metrics', 'METRICS_READ_FAILED', err instanceof Error ? err.message : String(err), { sessionId: options.session }, [
+                'Verify the project root + session id are correct.',
+                'For the full observability stream, run `peaks audit metrics --project .`.'
+            ]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}