peaks-loop 4.0.0-beta.9 → 4.0.3

package/skills/peaks-code/references/cron-scheduler-deployment.md

@@ -0,0 +1,313 @@
+# peaks-cron-scheduler deployment guide
+
+> **Slice 2026-07-29-worktree-l2-extended Part 20.** Companion to
+> the scheduler implementation in
+> `src/cli/commands/cron-scheduler-commands.ts`. This file
+> ships the install recipe operators actually run.
+
+## What the scheduler does
+
+`peaks cron-scheduler` is a long-running background process
+that wakes up once per minute and runs any task in
+`.peaks/cron/schedule.json` whose `intervalMs` has elapsed
+since the last run. Built-in tasks include `lease-gc-daily`
+(24h interval; sweeps orphan worktree leases). See
+`peaks cron init` to bootstrap the schedule.
+
+## Quick start (manual)
+
+```sh
+# 1. Initialize the schedule (idempotent)
+peaks cron init --project .
+
+# 2. Start the scheduler as a detached background process
+peaks cron-scheduler start --project .
+
+# 3. Confirm it is alive
+peaks cron-scheduler status --project .
+
+# 4. Trigger a one-shot run if you need it
+peaks cron-scheduler run-once --project .
+
+# 5. Stop the scheduler (SIGTERM)
+peaks cron-scheduler stop --project .
+```
+
+The pid is written to `.peaks/cron/scheduler.pid` so
+`stop` and `status` can find the process without operator
+guesswork. If the pid file is stale, `stop` removes it
+unconditionally (the `isPidAlive` check filters dead entries).
+
+## Windows service install (NSSM)
+
+The scheduler is a normal CLI process. NSSM (the Non-Sucking
+Service Manager) is the recommended wrapper for running it
+as a real Windows service that auto-restarts on crash.
+
+```sh
+# 1. Download NSSM (https://nssm.cc/) and put nssm.exe on PATH.
+
+# 2. Install the service. NSSM is happy with node + script
+#    args, so the same call works on Windows + POSIX.
+nssm install peaks-cron-scheduler "C:\\Program Files\\nodejs\\node.exe" \
+  "C:\\Users\\<you>\\.claude\\skills\\peaks-loop\\bin\\peaks.js" \
+  "cron-scheduler" "start" "--project" "C:\\path\\to\\peaks-project"
+
+# 3. Set the working directory (NSSM inherits the install
+#    caller's cwd by default; that may not be the project).
+nssm set peaks-cron-scheduler AppDirectory "C:\\path\\to\\peaks-project"
+
+# 4. Set environment variables (if needed for proxies / mirrors).
+nssm set peaks-cron-scheduler AppEnvironmentExtra "PEAKS_HOME=C:\\Users\\<you>\\.peaks"
+
+# 5. Configure auto-restart on crash.
+nssm set peaks-cron-scheduler AppExit Default Restart
+nssm set peaks-cron-scheduler AppRestartDelay 5000
+
+# 6. Start the service.
+nssm start peaks-cron-scheduler
+
+# 7. Verify.
+nssm status peaks-cron-scheduler
+peaks cron-scheduler status --project .
+```
+
+The same NSSM recipe works on POSIX (use `nssm` from your
+distro's package manager) — NSSM runs the same commands on
+both Windows and Linux. The pid-file pattern is the same.
+
+## Logs
+
+`peaks-cron-scheduler.js` writes to its own stdout/stderr;
+NSSM captures them to the Windows Event Log when the
+service is running. For a debug session, run the scheduler
+in the foreground:
+
+```sh
+node bin/peaks.js cron-scheduler start --project .  # will not detach; use a tmux/foreground
+```
+
+(This is not the production path — the production path is
+`peaks cron-scheduler start` which uses detached spawn and
+returns immediately. The detached flag means the parent can
+exit cleanly without the child.)
+
+## Troubleshooting
+
+- **"scheduler.pid stale"** — `stop` removes the pid file
+  unconditionally. Restart with `start`.
+- **"no lease lease lease-id"** — the schedule was created
+  with `peaks cron init` but the user's `.peaks/cron/` is
+  read-only. Check filesystem permissions.
+- **"docker not found"** — the scheduler runs shell commands
+  via `execSync`. If a task is `docker rm --force ...` and
+  docker is missing, the task fails (the scheduler does not
+  crash — it logs and continues to the next tick).
+
+## When NOT to use this scheduler
+
+- **Production with strict timing** — peaks-cron is a
+  best-effort CLI scheduler, not a real cron daemon. For
+  mission-critical periodic work, use the OS cron / systemd
+  timer / Windows Task Scheduler to invoke
+  `peaks cron-scheduler run-once --project .` on a precise
+  interval. The OS scheduler is reliable; the in-process
+  scheduler is portable.
+- **Multi-tenant** — peaks-cron runs all tasks in the
+  schedule.json in a single process. If two users have
+  conflicting lease-gc schedules, the in-process scheduler
+  will collide. The OS scheduler + per-tenant
+  `peaks cron-scheduler run-once` is the right shape.
+
+## Source pointer
+
+The CLI surface lives in
+`src/cli/commands/cron-scheduler-commands.ts`. The pure
+`runSchedulerLoop` function is the async loop; `start` /
+`stop` / `status` are thin shells around pid-file
+management.
+
+---
+
+# Appendix A — NSSM (Non-Sucking Service Manager) detailed install
+
+> **Slice 2026-07-29-rid-prose-only-sweep Part 39.** This
+> appendix is the operator-focused, step-by-step NSSM install
+> recipe for `peaks-cron-scheduler` on Windows. NSSM wraps any
+> long-running process as a real Windows service that starts at
+> boot, restarts on crash, and writes to the Windows Event Log.
+
+## Why NSSM (not Windows Task Scheduler)
+
+Windows Task Scheduler can run `peaks-cron-scheduler start`
+on a schedule, but it does not manage the long-running process:
+if `node` crashes, Task Scheduler will not restart it until
+the next trigger. NSSM (and node-windows, a Node-native
+alternative) treat the process as a service with auto-restart.
+
+## Install NSSM
+
+Download NSSM from <https://nssm.cc/> (the official site
+hosts the binary). NSSM is a single `nssm.exe` (~50 KB); put
+it on PATH (e.g. `C:\Windows\System32` or a custom dir).
+
+For a 64-bit Windows host, NSSM ships 32-bit and 64-bit
+binaries in the same zip — use `win64\nssm.exe`. The 32-bit
+binary works for 32-bit services; the 64-bit binary is the
+default for modern systems.
+
+```sh
+# Verify NSSM is on PATH and reports its version
+nssm version
+# NSSM 2.24, 64-bit
+```
+
+If `nssm` is not on PATH, the install will fail with
+`'nssm' is not recognized`. The peaks-cron-scheduler NSSM
+install does not put NSSM on PATH for the operator; it
+expects NSSM to be installed first.
+
+## Install the service
+
+```sh
+# 1. Install the service. NSSM is happy with `node` + script
+#    args, so the same call works on Windows + POSIX.
+nssm install peaks-cron-scheduler "C:\Program Files\nodejs\node.exe" \
+  "C:\Users\<you>\.claude\skills\peaks-loop\bin\peaks.js" \
+  "cron-scheduler" "start" "--project" "C:\path\to\peaks-project"
+
+# 2. Set the working directory (NSSM inherits the install
+#    caller's cwd by default; that may not be the project).
+nssm set peaks-cron-scheduler AppDirectory "C:\path\to\peaks-project"
+
+# 3. Set environment variables (if needed for proxies / mirrors).
+nssm set peaks-cron-scheduler AppEnvironmentExtra "PEAKS_HOME=C:\Users\<you>\.peaks"
+
+# 4. Configure auto-restart on crash.
+nssm set peaks-cron-scheduler AppExit Default Restart
+nssm set peaks-cron-scheduler AppRestartDelay 5000
+
+# 5. Set log file paths (NSSM redirects stdout/stderr).
+nssm set peaks-cron-scheduler AppStdoutCreationDisposition 4   # OPEN_ALWAYS
+nssm set peaks-cron-scheduler AppStderrCreationDisposition 4
+nssm set peaks-cron-scheduler AppStdout "C:\path\to\logs\peaks-cron-scheduler.out.log"
+nssm set peaks-cron-scheduler AppStderr "C:\path\to\logs\peaks-cron-scheduler.err.log"
+nssm set peaks-cron-scheduler AppRotateFiles 1                   # rotate on size
+nssm set peaks-cron-scheduler AppRotateBytes 10485760              # 10 MB per file
+
+# 6. Start the service.
+nssm start peaks-cron-scheduler
+```
+
+The same NSSM recipe works on POSIX (use `nssm` from your
+distro's package manager) — NSSM runs the same commands on
+both Windows and Linux. The pid-file pattern is the same.
+
+## Verify
+
+```sh
+# 1. NSSM-level status
+nssm status peaks-cron-scheduler
+# SERVICE_RUNNING
+
+# 2. peaks-level status (peaks-cli reads the pid file)
+peaks cron-scheduler status --project C:\path\to\peaks-project
+# {
+#   "data": {
+#     "alive": true,
+#     "pid": 12345,
+#     "scheduleEntries": 1,
+#     "dueTaskCount": 0
+#   }
+# }
+
+# 3. Force a one-shot to verify the schedule is reachable
+peaks cron-scheduler run-once --project C:\path\to\peaks-project
+# {
+#   "data": {
+#     "ran": 1,
+#     "records": [{ ... }]
+#   }
+# }
+```
+
+If `nssm status` reports `SERVICE_STOPPED`, the service
+crashed on startup. Check the log file at
+`<AppStderr>` (typically `C:\path\to\logs\peaks-cron-scheduler.err.log`).
+The most common cause is `nssm` not finding the node binary
+at `<AppStdout>` — verify with
+`nssm get peaks-cron-scheduler AppStdout` + `AppParameters`.
+
+## Uninstall
+
+```sh
+# 1. Stop the service
+nssm stop peaks-cron-scheduler
+
+# 2. Remove the service registration
+nssm remove peaks-cron-scheduler confirm
+
+# 3. (Optional) Remove the log files
+rm "C:\path\to\logs\peaks-cron-scheduler.out.log"
+rm "C:\path\to\logs\peaks-cron-scheduler.err.log"
+
+# 4. (Optional) Remove the cron-schedule state
+#    Note: the peaks-cli schedule lives under .peaks/cron/ and
+#    is NOT in NSSM. Removing NSSM does not affect the schedule.
+peaks cron list --project C:\path\to\peaks-project
+```
+
+If the service refuses to stop, escalate:
+`taskkill /F /IM node.exe /FI "WINDOWTITLE eq peaks-cron-scheduler*"`
+or `nssm set peaks-cron-scheduler AppStopMethodSkip 0` to
+force NSSM to honor `Ctrl+C` instead of `WM_CLOSE`.
+
+## Troubleshooting
+
+- **"nssm: command not found"** — NSSM is not on PATH.
+  Install it (see `Install NSSM` above) and re-run the
+  `nssm install` command.
+- **"SERVICE_PAUSED" on startup** — Windows Defender or
+  another AV is blocking the binary. Add the node binary
+  to the AV exclusion list or sign the peaks-cli install.
+- **Service runs but no log lines** — the AppStdout path is
+  wrong, or the directory is not writable. NSSM needs the
+  AppStderr file's parent directory to exist before
+  service start. `mkdir -p` the log dir before
+  `nssm start`.
+- **Auto-restart not firing** — `AppExit Default Restart`
+  is set, but Windows also has a per-process recovery
+  policy (`sc failure` for native services). For NSSM,
+  `AppRestartDelay` is in milliseconds; 5000 is the
+  default. 0 means "restart immediately", which can cause
+  a crash loop if the underlying issue is fatal.
+- **Schedule has tasks but they don't fire** — verify
+  the schedule file is reachable by the service user
+  (the user the service runs as, not your interactive
+  user). `peaks cron list` from the interactive shell
+  may show entries that the service user cannot see
+  (different HOME / different `PEAKS_HOME` env).
+
+## Production checklist
+
+- [ ] NSSM installed on PATH
+- [ ] Node.js installed at the path NSSM is configured for
+- [ ] peaks-loop installed at the path NSSM is configured for
+- [ ] Project root has a populated `.peaks/cron/schedule.json`
+      (run `peaks cron init` from the project dir first)
+- [ ] Log directory exists and is writable by the service user
+- [ ] `nssm status peaks-cron-scheduler` reports `SERVICE_RUNNING`
+- [ ] `peaks cron-scheduler status` reports `alive: true`
+- [ ] `peaks cron-scheduler run-once` runs the lease-gc-daily
+      task without error
+- [ ] Service survives a reboot (`shutdown /r` then
+      `nssm status peaks-cron-scheduler`)
+
+## Related memory
+
+- [[2026-07-29-worktree-l2-extended-part15]] — peaks-cron
+  init / list / run / peaks-cron-scheduler start (Part 15)
+- [[2026-07-29-worktree-l2-extended-part20]] — first pass
+  NSSM recipe (Part 20)
+- [[2026-07-29-worktree-l2-extended-part14]] — peaks-cron
+  schedule.json shape + built-in `lease-gc-daily` task

package/skills/peaks-code/references/external-skill-invocation.md

@@ -70,3 +70,30 @@ When a skill body adds a new external reference, it must include the equivalent
 3. add the capability discovery clause, the reference-only qualifier, the do-not-execute clause, and the Peaks-authoritative gate to that section;
 4. for MCP servers, point the LLM at the tool-list self-check (its own `mcp__<server>__*` namespace) instead of describing manual `~/.claude/settings.json` edits;
 5. rerun the audit.
+
+## Superpowers transition contract (effective 2026-07-24, slice 2026-07-24-peaks-code-bridge-002-rootcause)
+
+`peaks-code` cooperates with the **superpowers** skill family under the following contract. This contract sits alongside Stage 1–3 above and is binding on every peaks-code dispatch.
+
+### Trigger
+
+When the user (or the active IDE skill picker) suggests invoking `superpowers:brainstorming`, `superpowers:writing-plans`, `superpowers:executing-plans`, or any other superpowers skill during a peaks-code request, the LLM MUST apply the transition steps below before continuing the peaks-code 11-step sequence.
+
+### Transition steps (binding)
+
+1. **Discovery** — confirm the superpowers skill is present via the LLM's own tool list / `peaks capabilities --source access-repo --json`. If absent, surface the install command (`claude install skill superpowers:<skill>`) and stop until the user installs.
+2. **Reference-only invocation** — invoke the superpowers skill as **reference material**. The output (a brainstorming map, a plan, a TDD recipe, etc.) is read; it is not executed as the workflow body. Quote the methods/surfaces the peaks-rd plan borrows; never persist or "execute" the superpowers output verbatim.
+3. **Re-author through peaks-rd** — re-author the borrowed plan as a peaks-rd artefact at `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`. peaks-rd owns the slice contract, the rollback plan, and the test plan. The superpowers output may inform the prose; it does not replace the peaks-rd envelope.
+4. **Continue peaks-code** — from Step 3 (sub-agent fan-out) onward. Do NOT call `superpowers:executing-plans` or `superpowers:subagent-driven-development` to run the resulting plan; use `peaks sub-agent dispatch rd` / `peaks sub-agent dispatch qa` instead.
+5. **Do not edit upstream** — the `superpowers:writing-plans` and `superpowers:brainstorming` upstream SKILL.md files are owned by the superpowers npm/Claude-Code skill distribution. Any direct edit is silently overwritten on the next `claude install skill superpowers:<skill>` refresh. If a user-facing bridge is needed, place it in `peaks-code/SKILL.md` (BRIDGE chapter), `peaks-code/references/runbook.md` (Step 2.7), `peaks-code/references/boundaries.md` (superpowers red lines), and this file (transition contract).
+6. **Mandatory closure** — when the request is complete, run `peaks request transition` through `spec-locked → implemented → qa-handoff → handed-off` and `peaks memory extract`. A half-finished state file under `.peaks/_runtime/<sessionId>/` is treated as pollution.
+
+### What peaks-code MUST NOT do
+
+- Dispatch `superpowers:executing-plans` or `superpowers:subagent-driven-development` to replace peaks-rd or peaks-qa.
+- Adopt superpowers' bare worktree convention (`~/.claude/worktrees/<branch>/`) inside peaks-code requests; peaks-loop uses `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) and the active junction at `~/.claude/skills/peaks-*`.
+- Hand-author hook scripts at `~/.claude/skills/peaks-code/hooks/*`. Hook source MUST come from `src/services/hooks/*.sh` in the peaks-loop repo, distributed via `peaks hooks install` (which itself respects the existing `peaks gate enforce` entry and is append-only).
+
+### Phrase the audit looks for
+
+When a peaks-code skill body mentions a superpowers skill by name, the body MUST include all four: a "reference only" qualifier, a "do not auto-run" clause, a "re-author through peaks-rd" clause, and a "Peaks artefacts remain authoritative" clause. The `tests/unit/skills/peaks-code-superpowers-bridge.test.ts` guard test enforces this on every peaks-* SKILL.md.

package/skills/peaks-code/references/lease-dashboard.html

@@ -0,0 +1,224 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>peaks lease-stats dashboard</title>
+<style>
+  :root {
+    --bg: #0f1115;
+    --fg: #e6e6e6;
+    --muted: #9aa0a6;
+    --accent: #6cc4ff;
+    --ok: #6ee787;
+    --warn: #f0c674;
+    --err: #ff6b6b;
+    --card: #1a1d24;
+    --border: #2a2e36;
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.5;
+  }
+  header {
+    padding: 1.5rem 2rem;
+    border-bottom: 1px solid var(--border);
+    background: var(--card);
+  }
+  header h1 {
+    margin: 0 0 .25rem 0;
+    font-size: 1.1rem;
+    letter-spacing: .04em;
+  }
+  header .sub {
+    color: var(--muted);
+    font-size: .85rem;
+  }
+  main {
+    max-width: 960px;
+    margin: 0 auto;
+    padding: 2rem;
+    display: grid;
+    gap: 1.5rem;
+  }
+  .card {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    padding: 1.25rem 1.5rem;
+  }
+  .card h2 {
+    margin: 0 0 1rem 0;
+    font-size: 0.95rem;
+    color: var(--accent);
+    text-transform: uppercase;
+    letter-spacing: .08em;
+  }
+  .stat {
+    display: flex;
+    justify-content: space-between;
+    align-items: baseline;
+    padding: .35rem 0;
+    border-bottom: 1px dashed var(--border);
+  }
+  .stat:last-child { border-bottom: none; }
+  .stat .label { color: var(--muted); font-size: .9rem; }
+  .stat .value { font-size: 1.05rem; font-weight: 600; }
+  .stat .value.ok { color: var(--ok); }
+  .stat .value.warn { color: var(--warn); }
+  .stat .value.err { color: var(--err); }
+  .bar {
+    height: 6px;
+    background: var(--bg);
+    border-radius: 3px;
+    overflow: hidden;
+    margin-top: .75rem;
+  }
+  .bar .fill { height: 100%; background: var(--accent); }
+  .bar .fill.warn { background: var(--warn); }
+  .bar .fill.err { background: var(--err); }
+  table { width: 100%; border-collapse: collapse; font-size: .9rem; }
+  th, td { text-align: left; padding: .4rem .6rem; border-bottom: 1px solid var(--border); }
+  th { color: var(--muted); font-weight: 500; }
+  td.num { text-align: right; font-variant-numeric: tabular-nums; }
+  .empty { color: var(--muted); font-style: italic; }
+  code { background: var(--bg); padding: 1px 6px; border-radius: 3px; font-size: .85em; }
+  .footer { text-align: center; color: var(--muted); font-size: .8rem; margin-top: 2rem; }
+</style>
+</head>
+<body>
+<header>
+  <h1>peaks lease-stats dashboard</h1>
+  <div class="sub">auto-refreshes every 30s. Source: <code>peaks lease-stats --json</code></div>
+</header>
+<main>
+  <section class="card" id="rates">
+    <h2>lease lifecycle (project-wide)</h2>
+    <div class="stat"><span class="label">leases spawned</span><span class="value" id="stat-spawn">—</span></div>
+    <div class="stat"><span class="label">leases released (manual)</span><span class="value" id="stat-release">—</span></div>
+    <div class="stat"><span class="label">leases auto-released</span><span class="value" id="stat-auto">—</span></div>
+    <div class="stat"><span class="label">leases gc'd</span><span class="value" id="stat-gc">—</span></div>
+    <div class="stat"><span class="label">auto-release failures</span><span class="value" id="stat-fail">—</span></div>
+  </section>
+
+  <section class="card" id="rate">
+    <h2>leak rate</h2>
+    <div class="stat"><span class="label">estimated active</span><span class="value" id="stat-active">—</span></div>
+    <div class="stat"><span class="label">estimated leaked</span><span class="value" id="stat-leaked">—</span></div>
+    <div class="bar"><div class="fill" id="bar-leaked"></div></div>
+    <div class="stat" id="row-lifetimes" style="display:none"><span class="label">avg lease lifetime</span><span class="value" id="stat-avglife">—</span></div>
+    <div class="stat" id="row-p99" style="display:none"><span class="label">p99 lease lifetime</span><span class="value" id="stat-p99">—</span></div>
+  </section>
+
+  <section class="card" id="rid-table">
+    <h2>top rids (by event count)</h2>
+    <table>
+      <thead><tr><th>rid</th><th class="num">events</th></tr></thead>
+      <tbody id="rid-body"><tr><td colspan="2" class="empty">no events recorded</td></tr></tbody>
+    </table>
+  </section>
+
+  <section class="card" id="role-table">
+    <h2>by role</h2>
+    <table>
+      <thead><tr><th>role</th><th class="num">events</th></tr></thead>
+      <tbody id="role-body"><tr><td colspan="2" class="empty">no events recorded</td></tr></tbody>
+    </table>
+  </section>
+
+  <section class="card" id="iso-table">
+    <h2>by isolation mode</h2>
+    <table>
+      <thead><tr><th>isolation</th><th class="num">events</th></tr></thead>
+      <tbody id="iso-body"><tr><td colspan="2" class="empty">no events recorded</td></tr></tbody>
+    </table>
+  </section>
+</main>
+<div class="footer">part 26 — open <code>lease-dashboard.html</code> in a browser served by a static file server</div>
+<script>
+  // Part 26 dashboard. Fetches the live peaks lease-stats
+  // envelope every 30s and re-renders the cards. The endpoint
+  // is a sibling field to `node bin/peaks.js audit red-lines`
+  // — any project root that has a populated .peaks/observability
+  // stream will render correctly.
+  //
+  // Use: serve this file via `python3 -m http.server 8080` and
+  // configure the peaks CLI to expose a JSON endpoint on the
+  // same port. (The simplest local setup is a tiny shell script
+  // that wraps `peaks lease-stats --project . --json | jq .`.)
+  async function refresh() {
+    try {
+      const res = await fetch('./lease-stats.json', { cache: 'no-store' });
+      if (!res.ok) throw new Error('HTTP ' + res.status);
+      const env = await res.json();
+      render(env.data);
+    } catch (err) {
+      // Render a soft error: the page stays useful as a static
+      // reference even when the JSON endpoint is down.
+      document.getElementById('stat-spawn').textContent = 'err: ' + err.message;
+    }
+  }
+  function render(d) {
+    if (!d) return;
+    const c = d.counts || {};
+    document.getElementById('stat-spawn').textContent = c.spawn ?? '—';
+    document.getElementById('stat-release').textContent = c.release ?? '—';
+    document.getElementById('stat-auto').textContent = c.autoRelease ?? '—';
+    document.getElementById('stat-gc').textContent = c.gc ?? '—';
+    document.getElementById('stat-fail').textContent = c['autoRelease-failed'] ?? '—';
+    if (d.rate) {
+      const active = d.rate.estimatedActive ?? 0;
+      const leaked = d.rate.estimatedLeaked ?? 0;
+      const denom = Math.max(active, 1);
+      const pct = Math.round((leaked / denom) * 100);
+      const cls = leaked === 0 ? 'ok' : (pct < 10 ? 'warn' : 'err');
+      const aEl = document.getElementById('stat-active');
+      const lEl = document.getElementById('stat-leaked');
+      aEl.textContent = active;
+      aEl.className = 'value ' + cls;
+      lEl.textContent = leaked + ' (' + pct + '%)';
+      lEl.className = 'value ' + cls;
+      const bar = document.getElementById('bar-leaked');
+      bar.style.width = pct + '%';
+      bar.className = 'fill ' + cls;
+      if (d.rate.avgLifetimeMs !== null && d.rate.avgLifetimeMs !== undefined) {
+        document.getElementById('row-lifetimes').style.display = 'flex';
+        document.getElementById('stat-avglife').textContent = formatMs(d.rate.avgLifetimeMs);
+      }
+      if (d.rate.p99LifetimeMs !== null && d.rate.p99LifetimeMs !== undefined) {
+        document.getElementById('row-p99').style.display = 'flex';
+        document.getElementById('stat-p99').textContent = formatMs(d.rate.p99LifetimeMs);
+      }
+    }
+    fillTable('rid-body', d.perRid || [], (r) => [r.rid, r.count]);
+    fillTable('role-body', d.perRole || [], (r) => [r.role, r.count]);
+    fillTable('iso-body', d.perIsolation || [], (r) => [r.isolation, r.count]);
+  }
+  function fillTable(id, rows, mapper) {
+    const body = document.getElementById(id);
+    if (rows.length === 0) {
+      body.innerHTML = '<tr><td colspan="2" class="empty">no events recorded</td></tr>';
+      return;
+    }
+    body.innerHTML = rows.map((r) => {
+      const [a, b] = mapper(r);
+      return '<tr><td>' + escape(a) + '</td><td class="num">' + b + '</td></tr>';
+    }).join('');
+  }
+  function escape(s) {
+    return String(s).replace(/[&<>"]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c]));
+  }
+  function formatMs(ms) {
+    if (ms < 1000) return ms + 'ms';
+    if (ms < 60_000) return (ms / 1000).toFixed(1) + 's';
+    if (ms < 3_600_000) return (ms / 60_000).toFixed(1) + 'm';
+    return (ms / 3_600_000).toFixed(1) + 'h';
+  }
+  refresh();
+  setInterval(refresh, 30_000);
+</script>
+</body>
+</html>

package/skills/peaks-code/references/lease-stats.sample.json

@@ -0,0 +1,26 @@
+{
+  "ok": true,
+  "command": "lease.stats",
+  "data": {
+    "projectRoot": ".",
+    "sessionCount": 0,
+    "totalLeaseEvents": 0,
+    "rate": {
+      "totalSpawn": 0,
+      "totalTerminal": 0,
+      "estimatedActive": 0,
+      "estimatedLeaked": 0,
+      "completedLifetimes": 0,
+      "avgLifetimeMs": null,
+      "p99LifetimeMs": null
+    },
+    "perRid": [],
+    "perRole": [],
+    "perIsolation": []
+  },
+  "warnings": [],
+  "nextActions": [
+    "0 lease events across 0 session(s); 0 estimated active, 0 estimated leaked.",
+    "Pipe to `jq` or paste into a dashboard for visual rendering."
+  ]
+}