peaks-loop 4.0.0-beta.9 → 4.0.1

package/dist/cli/commands/heartbeat-watch-command.d.ts

@@ -0,0 +1,31 @@
+import type { Command } from 'commander';
+import { type DispatchRecord } from '../../services/dispatch/dispatch-record-writer.js';
+import { summarize, viewSubAgent } from '../../services/code/status-line-renderer.js';
+import { type ProgramIO } from '../cli-helpers.js';
+declare const DEFAULT_INTERVAL_MS = 10000;
+declare const DEFAULT_STALE_THRESHOLD_MS: number;
+type WatchSnapshot = {
+    readonly records: readonly DispatchRecord[];
+    readonly line: string;
+    readonly summary: ReturnType<typeof summarize>;
+    readonly views: readonly ReturnType<typeof viewSubAgent>[];
+    readonly stale: {
+        readonly count: number;
+        readonly thresholdSec: number;
+        readonly customThresholdSec: number;
+        readonly views: readonly ReturnType<typeof viewSubAgent>[];
+    };
+};
+declare function parsePositiveMs(raw: string | undefined, fallback: number, flag: string): number;
+declare function findBatchRecords(projectRoot: string, sessionId: string, batchId: string): DispatchRecord[];
+declare function snapshot(records: readonly DispatchRecord[], batchId: string, staleThresholdMs: number, now?: () => Date): WatchSnapshot;
+declare function isTerminal(records: readonly DispatchRecord[]): boolean;
+/** Register the independently runnable `peaks heartbeat watch` daemon. */
+export declare function registerHeartbeatWatchCommand(parent: Command, io: ProgramIO): void;
+export declare const __test__: {
+    findBatchRecords: typeof findBatchRecords;
+    isTerminal: typeof isTerminal;
+    parsePositiveMs: typeof parsePositiveMs;
+    snapshot: typeof snapshot;
+};
+export { DEFAULT_INTERVAL_MS, DEFAULT_STALE_THRESHOLD_MS };

package/dist/cli/commands/heartbeat-watch-command.js

@@ -0,0 +1,146 @@
+import { existsSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { readRecords } from '../../services/dispatch/dispatch-record-writer.js';
+import { renderStatusLine, summarize, viewSubAgent } from '../../services/code/status-line-renderer.js';
+import { getErrorMessage } from '../cli-helpers.js';
+const DEFAULT_INTERVAL_MS = 10_000;
+const DEFAULT_STALE_THRESHOLD_MS = 5 * 60 * 1000;
+const TERMINAL_STATUSES = new Set([
+    'done',
+    'failed',
+    'cancelled',
+    'no-execution'
+]);
+function parsePositiveMs(raw, fallback, flag) {
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${flag} must be a positive integer (got ${raw})`);
+    }
+    return value;
+}
+function parseMaxTicks(raw) {
+    if (raw === undefined)
+        return Number.POSITIVE_INFINITY;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`--max-ticks must be a positive integer (got ${raw})`);
+    }
+    return value;
+}
+function findBatchRecords(projectRoot, sessionId, batchId) {
+    const sessionDir = resolve(projectRoot, '.peaks', '_sub_agents', sessionId);
+    if (!existsSync(sessionDir))
+        return [];
+    const paths = readdirSync(sessionDir)
+        .filter((name) => /^dispatch-[^/\\]+\.json$/.test(name))
+        .map((name) => join(sessionDir, name));
+    return readRecords(paths).filter((record) => record.batchId === batchId);
+}
+function snapshot(records, batchId, staleThresholdMs, now = () => new Date()) {
+    const prefix = `[peaks-heartbeat:${batchId}]`;
+    const summary = summarize(records);
+    const views = records.map((record) => viewSubAgent(record, now));
+    const customThresholdSec = Math.floor(staleThresholdMs / 1000);
+    const staleViews = views.filter((view) => view.lastBeatAgoSec !== null && view.lastBeatAgoSec > customThresholdSec);
+    let line = renderStatusLine(prefix, records, now);
+    if (staleThresholdMs > DEFAULT_STALE_THRESHOLD_MS) {
+        line = line.replaceAll(' ⚠ stale', '');
+    }
+    else if (staleThresholdMs < DEFAULT_STALE_THRESHOLD_MS) {
+        const staleRoles = new Set(staleViews.map((view) => view.role));
+        if (staleRoles.size > 0 && !line.includes('⚠ stale')) {
+            line += ` ⚠ stale (${[...staleRoles].join(', ')})`;
+        }
+    }
+    return {
+        records,
+        line,
+        summary,
+        views,
+        stale: {
+            count: staleViews.length,
+            thresholdSec: Math.floor(DEFAULT_STALE_THRESHOLD_MS / 1000),
+            customThresholdSec,
+            views: staleViews
+        }
+    };
+}
+function isTerminal(records) {
+    return records.length > 0 && records.every((record) => TERMINAL_STATUSES.has(record.status));
+}
+function emit(io, value, json) {
+    if (json) {
+        io.stdout(`${JSON.stringify({ ok: true, data: value })}\n`);
+    }
+    else {
+        io.stdout(`${value.line}\n`);
+    }
+}
+/** Register the independently runnable `peaks heartbeat watch` daemon. */
+export function registerHeartbeatWatchCommand(parent, io) {
+    parent
+        .command('watch')
+        .description('Watch persisted sub-agent heartbeat records for one batch')
+        .requiredOption('--batch-id <id>', 'batch id to watch')
+        .option('--interval-ms <n>', `poll interval in milliseconds (default ${DEFAULT_INTERVAL_MS})`)
+        .option('--stale-threshold-ms <n>', `stale threshold in milliseconds (default ${DEFAULT_STALE_THRESHOLD_MS})`)
+        .option('--max-ticks <n>', 'stop after n ticks (test/diagnostic seam)')
+        .option('--project <path>', 'project root (defaults to current directory)')
+        .option('--session-id <id>', 'session id (defaults to the active binding)')
+        .option('--json', 'emit one JSON envelope per poll tick')
+        .action(async (options) => {
+        try {
+            const intervalMs = parsePositiveMs(options.intervalMs, DEFAULT_INTERVAL_MS, '--interval-ms');
+            const staleThresholdMs = parsePositiveMs(options.staleThresholdMs, DEFAULT_STALE_THRESHOLD_MS, '--stale-threshold-ms');
+            const maxTicks = parseMaxTicks(options.maxTicks);
+            const projectRoot = resolveCanonicalProjectRoot(options.project ?? process.cwd());
+            const sessionId = options.sessionId ?? getSessionIdCanonical(projectRoot);
+            if (!sessionId)
+                throw new Error('no active session; pass --session-id');
+            const tick = () => {
+                const records = findBatchRecords(projectRoot, sessionId, options.batchId);
+                const current = snapshot(records, options.batchId, staleThresholdMs);
+                emit(io, current, options.json === true);
+                return isTerminal(records);
+            };
+            if (tick())
+                return;
+            let count = 1;
+            await new Promise((resolveWait, reject) => {
+                const timer = setInterval(() => {
+                    try {
+                        count += 1;
+                        if (tick() || count >= maxTicks) {
+                            clearInterval(timer);
+                            resolveWait();
+                        }
+                    }
+                    catch (error) {
+                        clearInterval(timer);
+                        reject(error);
+                    }
+                }, intervalMs);
+                timer.unref?.();
+            });
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            if (options.json === true)
+                io.stdout(`${JSON.stringify({ ok: false, code: 'HEARTBEAT_WATCH_FAILED', message })}\n`);
+            else
+                io.stderr(`HEARTBEAT_WATCH_FAILED: ${message}\n`);
+            process.exitCode = 1;
+        }
+    });
+}
+export const __test__ = {
+    findBatchRecords,
+    isTerminal,
+    parsePositiveMs,
+    snapshot
+};
+export { DEFAULT_INTERVAL_MS, DEFAULT_STALE_THRESHOLD_MS };

package/dist/cli/commands/hook-handle.js

@@ -6,7 +6,7 @@ import { evaluateCodeBan } from '../../services/audit/enforcers/code-ban.js';
 import { isRootWrite } from '../../services/audit/enforcers/no-root-pollution.js';
 import { checkLoginGate } from '../../services/audit/enforcers/login-gate.js';
 import { resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { emitDecision, emitHint } from '../../services/hooks/output.js';
 /**
  * Read the hook payload. `PEAKS_HOOK_STDIN` is a test seam (same convention as

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

@@ -1,8 +1,9 @@
-import { existsSync } from 'node:fs';
-import { fail, ok } from '../../shared/result.js';
+import { existsSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
-import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall } from '../../services/skills/hooks-settings-service.js';
+import { applyHookInstall, planHookInstall, readHookStatus, readInstalledEntriesFromSettings, removeHookInstall, listSuperpowersDenyEntries } from '../../services/skills/hooks-settings-service.js';
 import { readJsonObjectFile } from '../../services/ide/shared/atomic-json.js';
 import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
@@ -44,6 +45,59 @@ function listExpectedEntriesForIde(ide, _skipProgress = false) {
     }
     return [{ matcher: adapter.toolMatcher, sentinel: 'peaks gate enforce' }];
 }
+/**
+ * Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): copy the
+ * superpowers-bridge hook source from the peaks-loop repo
+ * (src/services/hooks/pre-tool-superpowers-bridge.sh) into the user-global
+ * `<userHome>/.claude/skills/peaks-code/hooks/` directory. The user-global
+ * copy is treated as a build artifact: it MUST be byte-identical to the
+ * repo source after install, and the source of truth is the repo file.
+ *
+ * Why this lives in the install command: the install is the single
+ * declared surface where the user-global directory is touched. Adding it
+ * here keeps the "hooks only ship from src/services/hooks/" invariant
+ * (G10 / AC10) — no other code path writes to `~/.claude/skills/peaks-code/hooks/`.
+ *
+ * Failure modes:
+ *   - Source file missing (build not run yet) → silently skip and emit a
+ *     warning. The settings.json install still succeeds; only the script
+ *     distribution is skipped. Matches the "release-pack silent skip
+ *     when tarball lacks dist/version.js" pattern from commit 08d93353.
+ *   - Target directory unwritable → throw so the user knows.
+ *   - Target file already exists with identical bytes → no-op.
+ *   - Target file exists with different bytes → overwrite (the repo
+ *     source is authoritative).
+ *
+ * Returns `{ copied, source, target }` so the install envelope can report
+ * it without forcing the caller to inspect the filesystem.
+ */
+/**
+ * Slice 2026-07-29-worktree-layer3-deny: read the on-disk
+ * `permissions.deny` block from a settings.json object and return
+ * every peaks-managed entry currently present. Used by `hooks status`
+ * to surface Layer 3 governance state without forcing the caller to
+ * re-read the file. Tolerant of missing / malformed `permissions` —
+ * a missing field returns an empty array, never throws.
+ */
+function readOnDiskDenyEntries(settings) {
+    const permissions = settings.permissions;
+    if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions))
+        return [];
+    const deny = permissions.deny;
+    if (!Array.isArray(deny))
+        return [];
+    return deny.filter((d) => typeof d === 'string');
+}
+function copyBridgeHookIfPresent(userHome) {
+    const source = resolve(__dirname, '..', '..', 'services', 'hooks', 'pre-tool-superpowers-bridge.sh');
+    const target = resolve(userHome, '.claude', 'skills', 'peaks-code', 'hooks', 'pre-tool-superpowers-bridge.sh');
+    if (!existsSync(source)) {
+        return { copied: false, source, target };
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    copyFileSync(source, target);
+    return { copied: true, source, target };
+}
 export function registerHooksCommands(program, io) {
     const hooks = program
         .command('hooks')
@@ -64,14 +118,31 @@ export function registerHooksCommands(program, io) {
             if (options.dryRun === true) {
                 const plan = planHookInstall(scope, projectRoot, { ide, skipProgress });
                 const dryRunEntries = listExpectedEntriesForIde(ide, skipProgress);
+                const bridgeCopy = scope === 'global'
+                    ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                    : { copied: false, source: '', target: '' };
                 printResult(io, ok('hooks.install', {
                     ...plan,
                     ide,
                     applied: false,
                     dryRun: true,
                     skipProgress,
-                    entries: dryRunEntries
-                }, [], [`would install ${dryRunEntries.length} peaks-managed hook entries`]), options.json);
+                    entries: dryRunEntries,
+                    bridgeHookCopy: bridgeCopy,
+                    // Slice 2026-07-29-worktree-layer3-deny: surface the
+                    // Layer 3 deny entries the install WOULD write. The
+                    // dry-run branch never actually invokes
+                    // `applyHookInstall`, so the on-disk snapshot is not
+                    // consulted here — the list is the desired-state
+                    // constant for clarity in the JSON envelope.
+                    permissionsDenyEntries: listSuperpowersDenyEntries()
+                }, [], [
+                    `would install ${dryRunEntries.length} peaks-managed hook entries`,
+                    `would write ${listSuperpowersDenyEntries().length} permissions.deny entries (Layer 3 worktree governance)`,
+                    bridgeCopy.copied
+                        ? `would copy bridge hook from ${bridgeCopy.source} to ${bridgeCopy.target}`
+                        : 'would not copy bridge hook (source missing or non-global scope)'
+                ]), options.json);
                 return;
             }
             const result = applyHookInstall(scope, projectRoot, { ide, skipProgress });
@@ -82,18 +153,44 @@ export function registerHooksCommands(program, io) {
             // entry; the summary mirrors the install shape, NOT a hardcoded
             // expected list.
             const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
+            // Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): when
+            // the install targets global scope, also copy the superpowers-bridge
+            // hook script from src/services/hooks/ to the user-global hooks
+            // directory. Project scope does not need this — project's
+            // .claude/skills/peaks-code is already a junction into the npm source.
+            const bridgeCopy = scope === 'global'
+                ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
+                : { copied: false, source: '', target: '' };
             const nextActions = result.applied
                 ? [
                     'Restart the IDE (or reload the workspace) so the hook entries take effect',
-                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`
+                    `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`,
+                    // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny
+                    // write alongside the hook install — single atomic write.
+                    `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
+                    bridgeCopy.copied
+                        ? `Copied bridge hook: ${bridgeCopy.target}`
+                        : 'Bridge hook not copied (source missing or non-global scope)'
                 ]
-                : [];
+                : (bridgeCopy.copied
+                    ? [`Bridge hook copied: ${bridgeCopy.target}`]
+                    : []);
+            // Slice 2026-07-29-worktree-layer3-deny: emit L3 deny bookkeeping
+            // in the JSON envelope so downstream automation (audit / sc) can
+            // confirm Layer 3 was applied without re-reading the file. When
+            // the install is a no-op (`applied: false`) the deny block was
+            // already on disk from a prior install; we still emit the
+            // current desired list for symmetry with the dry-run envelope.
+            const denyEntries = listSuperpowersDenyEntries();
             printResult(io, ok('hooks.install', {
                 ...result,
                 ide,
                 dryRun: false,
                 skipProgress,
-                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel }))
+                entries: installedEntries.map((e) => ({ matcher: e.matcher, sentinel: e.sentinel })),
+                bridgeHookCopy: bridgeCopy,
+                permissionsDenyApplied: result.applied,
+                permissionsDenyEntries: denyEntries
             }, [], nextActions), options.json);
         }
         catch (error) {
@@ -113,7 +210,16 @@ export function registerHooksCommands(program, io) {
         const ide = resolveIdeForCommand(options, projectRoot);
         try {
             const result = removeHookInstall(scope, projectRoot, { ide });
-            printResult(io, ok('hooks.uninstall', { ...result, ide }), options.json);
+            // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny removal
+            // bookkeeping. `permissionsDenyRemoved` mirrors `removed` (the
+            // service strips deny entries on the same atomic write that
+            // strips the hook entries; they share the same boolean).
+            printResult(io, ok('hooks.uninstall', {
+                ...result,
+                ide,
+                permissionsDenyRemoved: result.removed,
+                permissionsDenyEntries: listSuperpowersDenyEntries()
+            }), options.json);
         }
         catch (error) {
             const message = getErrorMessage(error);
@@ -141,10 +247,20 @@ export function registerHooksCommands(program, io) {
             // install left behind.
             const settingsPath = status.settingsPath;
             const settings = existsSync(settingsPath) ? readJsonObjectFile(settingsPath) : {};
+            // Slice 2026-07-29-worktree-layer3-deny: report the Layer 3 deny
+            // entries actually on disk. We read the existing settings.json
+            // (above) and surface its `permissions.deny` block. Any entry
+            // that matches the current `SUPERPOWERS_DENIED_SKILLS` set is
+            // considered "peaks-managed"; user-written entries are passed
+            // through verbatim so the envelope reflects reality. The desired
+            // list is also included for parity with install / uninstall.
+            const onDiskDeny = readOnDiskDenyEntries(settings);
             printResult(io, ok('hooks.status', {
                 ...status,
                 ide,
-                entries: readInstalledEntriesFromSettings(settings, ide)
+                entries: readInstalledEntriesFromSettings(settings, ide),
+                permissionsDenyEntries: listSuperpowersDenyEntries(),
+                permissionsDenyOnDisk: onDiskDeny
             }), options.json);
         }
         catch (error) {

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

@@ -1,6 +1,6 @@
 import { detectCurrentIdeModel } from '../../services/ide/current-model-detector.js';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { listAdapterIds } from '../../services/ide/ide-registry.js';
 export function registerIdeCommands(program, io) {
     const ide = program.command('ide').description('Read-only introspection helpers for the registered IDE adapter layer (slice 2026-07-09 add-zcode-adapter, Slice C)');

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

@@ -12,7 +12,7 @@
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { mustCheckFromReport, runImpactScan } from '../../services/impact/impact-scan-service.js';
-import { fail, ok } from '../../shared/result.js';
+import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerImpactCommands(program, io) {
     const impact = program

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

@@ -1,7 +1,7 @@
 // src/cli/commands/job-commands.ts
 import { join } from 'node:path';
 import { Command } from 'commander';
-import { fail, ok } from '../../shared/result.js';
+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';
@@ -11,6 +11,8 @@ 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();
@@ -285,5 +287,36 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         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;