[tdody]

Summary

With ~10 agents running, periscope gets laggy. This adds the measurements needed to see where memory and CPU go before optimizing anything (THI-448).

• New periscope/resources.py, stdlib-only (ctypes on libproc/libSystem). Once per /api/state tick it reads every process's phys_footprint and CPU time and puts each process in exactly one group: each pane's process tree, the periscope server, the webview, and elsewhere.
  • Memory is footprint, not RSS. Under swap, RSS undercounted the webview at 276 MB against 2.8 GB of real footprint.
  • The webview is periscope-app plus every process macOS holds it responsible for: the live WebContent, any WebContent the recycle left parked, GPU and Networking. The app is matched by the kernel's process name, because ps cuts comm to 16 characters.
  • CPU is the change in each process's CPU time since the previous sample, summed per group. Reaped children count too, so short git/gh/tsc runs and Bash-tool commands show up. A process that ended has its last total charged back to its nearest surviving ancestor (the one whose children time just grew), so nothing is counted twice, including a zsh -c wrapper and its command ending together. It's shown as a share of the whole machine (100% = every core busy), not per core like top, so groups listed side by side read as parts of one total. Samples are keyed by (pid, start time), taken under a lock, at most every 0.5 s. CPU is null until a previous sample exists, and when a reading exceeds every core for the interval.
  • Cost: no extra subprocess. build_state takes the tick's process snapshot once and passes it in. About 4–6 ms per pass on ~750–790 processes.
• /api/state: each row gets res: {mem_mb, cpu_pct} and the blob gets resources: {server, webview, panes, elsewhere, machine}. Both are null when the tick's ps snapshot fails.
• UI:
  • A ▣ 12.6G header pill shows what periscope and its panes hold.
  • Its popover lists the server, the webview, all panes together, each pane heaviest first (a line selects its pane; the list scrolls), elsewhere, and a machine line: 16.0G RAM · swap 8.6G/10.0G · 39% free · load 9.7. RAM leads because footprints include compressed and swapped pages, so the owners can add up past physical RAM, and that overcommitment is what the line shows.
  • The detail header shows · 630M mem · 0.4% cpu, in a fixed-width box so the header can't re-wrap between ticks.
• ↻ cycle hint: it reads claude's footprint instead of RSS (same 2 / 4 GB thresholds) and says which limit tripped.

Design: docs/superpowers/specs/2026-10-30-resource-monitor-design.md. Plan: docs/superpowers/plans/2026-10-30-resource-monitor.md. Related tickets: THI-449 (the webview recycle never fires while you're active) and THI-450 (subprocesses per tick).

Test plan

• uv run pytest -q: 2080 passed. tests/test_resources.py covers:

  • group assignment, including overlapping subtrees;
  • CPU accounting: reaped children, a Bash-tool zsh -c chain ending, a closed pane's shell, orphans launchd reaped, pid reuse, slow and stale ticks, an impossible delta;
  • the throttle, two callers forced to overlap, and a failed pass.

  Each new test was checked to fail when its fix is undone. An autouse conftest stub keeps every other test off the real machine.

• npm test: 1313 passed. Covers formatting, the pill and popover render, the detail-header part, and memHint.

• bin/check is clean, and static/dist is rebuilt.

• On the dev server (:17375) with live panes:

  • The webview showed at 4.7 GB, and every row carried res.
  • One pane's 794 MB covered its claude's 567 MB in top.
  • In the browser, the pill sits next to the usage meters, the popover lists every group, clicking a line selects the pane, and Escape closes it and returns focus to the pill.
  • A 5 s one-core burn run through a zsh -c wrapper reads ~10% while it runs, with no spike on the tick it ends.

• Thorough multi-agent review: 17 findings, none blocking merge, all fixed and re-verified.

Assumptions to challenge

• macOS only. resources.py loads libproc/libSystem at import, and session_status now imports it, so the planned Linux port needs a seam here.
• Private API. responsibility_get_pid_responsible_for_pid is private libSystem API, verified on macOS 27.
• Possible double count. Summing phys_footprint across the WebKit helpers is assumed not to double count. That's unproven for the GPU process.
• Measurement adds no ps. It uses the snapshot build_state takes before the fan-out. On a fan-out slower than the snapshot's 1 s cache, Codex detection still re-forks ps. That predates this PR and belongs to THI-450.
• Rare one-tick under-counts. A process reparented to launchd that dies in the same interval as its parent loses its last stretch of CPU. A child reaped in the few milliseconds between its parent's reading and its own, within one pass, is under-counted for that tick. That race predates this PR.
• Panes are active panes only. Non-active panes of split windows, the tmux server and the periscope-input pane count as elsewhere.
• The ↻ label during a deploy. A webview running JS older than the server shows a malformed ↻ label until it reloads.
• Claude's age. It still comes from ps etime. Moving liveness and age off ps is THI-450.

🤖 Generated with Claude Code