agentmon 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf488d280dd14af8cfdf2a7c576f0894b6c64749ac1249ece9282df402ff8a17
+  data.tar.gz: fe30f9f22652a83a2412922082bff73a832fe8c4ad73e09d5345f3d0f968531a
+SHA512:
+  metadata.gz: 4e4f558fa84438c7c956d7e2b903b03d25de57b3fd6f3602dd7f21c4be7e34017cda1df1023309a9e01ba0d89ba29b14af53ed00fb3abcd43f8bfe1ae0e9490e
+  data.tar.gz: 767da3880bb80429d9c0d960adff29ed252d368e9ee5581f4dbee8ddac36899946b87bde5473b54b22da7c172302018df15b8b0b48fa19a3a8dfa5ebba29cee9

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0
+
+First release.
+
+- `agentmon`: a live dashboard of AI coding agent sessions (Claude, Codex and their desktop apps) on macOS, opening on the dense layout; `--layout classic` and `--layout visual` for the others. Enter drills into a session, Escape comes back.
+- Per session and per process: CPU, real memory (footprint), resident size, disk read/write rates, network in/out and connections (from `nettop`), memory growth and page-ins.
+- Memory: Activity Monitor's breakdown, memory pressure and the sessions driving it.
+- Processes: scopes (Agents, All, Busy, Heavy, Writing, Waiting), grouping, search, a detail drawer, and terminate/kill with confirmation.
+- Commands: `top`, `sessions`, `tree`, `memory`, `footprint`, `record`, `report`, plus `completion` and `--version`. Off a terminal every view prints plain text.
+- History of sessions and memory as JSON lines under `~/.local/state/agentmon`, summarised by `agentmon report`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Gavin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,105 @@
+# agentmon
+
+What AI coding agents (Claude, Codex) cost your Mac: per-session CPU, real memory, disk and network I/O, memory pressure, and a history of runs, in your terminal.
+
+## Install
+
+With Homebrew (brings its own Ruby):
+
+```
+brew install satoramoto/tap/agentmon
+```
+
+Or as a gem:
+
+```
+gem install agentmon
+```
+
+Requirements: macOS; the gem needs Ruby 3.3 or newer. No root needed (other users' processes show only what `ps` gives). The network columns come from `nettop`, which ships with macOS; without it they show as unknown and the rest works.
+
+## Usage
+
+```
+agentmon                    # live dashboard, dense layout
+agentmon --layout visual    # gauges, areas and heat
+agentmon --layout classic   # the original dashboard: sessions, memory, processes, detail
+agentmon --no-motion        # no animation (also AGENTMON_MOTION=0)
+agentmon | cat              # one plain frame, no terminal needed
+agentmon top --once         # agent processes by CPU, one plain table
+agentmon --help             # every command and option
+```
+
+Commands:
+
+| Command | Shows |
+|---|---|
+| `top` | Agent processes by CPU, with footprint and disk I/O (`--once`, `--all`, `--sort`, `--session`, `-n`) |
+| `sessions` | Agent sessions now, with CPU, real memory and lifetime totals (`--all` adds recently ended, `--json`) |
+| `tree [SESSION]` | Process tree of each agent session, with footprint and CPU |
+| `memory` | RAM breakdown, pressure and the sessions driving it (`--json`) |
+| `footprint` | Real memory by session: footprint, share, growth, paging (`--json`) |
+| `record` | Record sessions to the history until ctrl+c (`--interval`, `--prune DAYS`) |
+| `report` | Sessions recorded over a period: peak memory, CPU, disk writes (`--since 2h`, `--json`) |
+| `completion zsh\|bash\|fish` | A shell completion script |
+
+Every command takes `--version`, `--color`/`--no-color` and `--trace`. Off a terminal, output is plain text for scripts.
+
+## Layouts
+
+- **dense** (default): an htop-like strip of machine CPU, memory and I/O, the Sessions table, and all agents together. Enter on a session drills into it: its CPU, memory and network, its processes, connections and a detail drawer.
+- **visual**: the same content as meters, braille area charts and heat colours.
+- **classic**: the first dashboard: Sessions, Memory, Processes and the Detail panel side by side.
+
+## Keys
+
+| Key | Does |
+|---|---|
+| `enter` | Open the selected session (dense, visual) |
+| `F` | Open the selected process's session |
+| `esc` | Back to all sessions; clears a search |
+| `tab` / `shift-tab` | Next / previous panel |
+| `↑` `↓` `j` `k` | Move the selection |
+| `[` `]` | Previous / next scope: Agents, All, Busy, Heavy, Writing, Waiting |
+| `g` | Group by session, directory, name, or as a tree |
+| `s` / `S` | Next sort column / reverse |
+| `/` | Search: free text, or `footprint>500M`, `cpu>5`, `session~repo` |
+| `z` | Zoom the focused panel |
+| `K` / `X` | Terminate (TERM) / kill (KILL) the selected process or group, after a y/n |
+| `?` | Help: every key and what each panel shows |
+| `q` | Quit |
+
+The mouse works too: click focuses a panel and selects a row, the wheel moves the selection.
+
+## What the numbers mean
+
+- **Session**: a `claude` or `codex` CLI and everything under it (its outermost one), or a desktop app (Claude, ChatGPT/Codex) and its children. Labelled `claude 4242 · repo`.
+- **CPU**: percent of one core, so 250% is two and a half cores. A session's CPU is the sum of its processes.
+- **Footprint** (real memory): the kernel's `phys_footprint`, what Activity Monitor calls Memory. It counts compressed pages, unlike resident size, which is also shown.
+- **Disk read/write**: bytes per second from each process's own I/O counters. Session totals add each process's growth, so very short-lived tools may be missed.
+- **Network in/out**: bytes per second per process and connection, from one `nettop` stream; hosts and connections are counted per session. A session with a sudden spike or many remote hosts is marked `⚑`.
+- **Memory pressure**: `100 − kern.memorystatus_level`, in percent; the Memory panel lists which sessions push it (footprint share and growth per second).
+- **Wait** and **page-ins**: time runnable but waiting for a CPU, and page-ins per second (each one waited for the disk).
+- **Lifetime totals** (CPU seconds, written, peak footprint): counted from when agentmon sees the session; nothing in a process tree is counted twice.
+
+Unknown values (an unreadable process, the first sample's rates) are blank, never 0. Sizes are binary (`1.5G` = 1.5 × 1024³ bytes).
+
+## History
+
+While the dashboard is open, or under `agentmon record`, agentmon writes one JSON line per session (and the memory breakdown) every 10 seconds to `~/.local/state/agentmon/<kind>/YYYY-MM-DD.jsonl` (or `$XDG_STATE_HOME/agentmon`, or `$AGENTMON_STATE_DIR`). `agentmon report` reads it; `agentmon record --prune 30` deletes days older than 30.
+
+## Development
+
+agentmon is built on [r2ui](https://github.com/satoramoto/r2ui). With an r2ui checkout beside this one (`../r2ui`), the Gemfile uses it; otherwise it uses r2ui's `main` on GitHub.
+
+```
+bundle install
+bundle exec rake test
+bundle exec exe/agentmon
+```
+
+See [AGENTS.md](AGENTS.md) for targeted tests, [docs/design.md](docs/design.md) for the architecture and [docs/releasing.md](docs/releasing.md) for releases.
+
+## License
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/exe/agentmon

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# agentmon                  the dense layout (one plain frame when piped: `agentmon | cat`)
+# agentmon --layout NAME    another layout: classic (the panel dashboard) or a view in docs/views.md
+# agentmon top --once       processes of agent sessions, plain table
+# agentmon --help           every command
+#
+# macOS only: the library reads processes through libproc (Fiddle) and nettop, so off macOS it
+# stops here with a message instead of failing to load.
+unless RUBY_PLATFORM.include?("darwin")
+  warn "agentmon: macOS only (it reads process data from the macOS kernel and nettop); this is #{RUBY_PLATFORM}"
+  exit 1
+end
+
+require_relative "../lib/agentmon"
+
+Agentmon::Program.start(ARGV)

data/lib/agentmon/commands/cli_options.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Root-level options every `agentmon` command takes, from r2ui's CLI extensions.
+#
+#   agentmon --version                  agentmon 0.1.0 (also -V, and `agentmon top --version`)
+#   agentmon completion zsh             a completion script; also bash and fish:
+#     eval "$(agentmon completion zsh)"           in ~/.zshrc, after compinit
+#     eval "$(agentmon completion bash)"          in ~/.bashrc
+#     agentmon completion fish | source           in ~/.config/fish/config.fish
+#   agentmon report --trace             an unexpected error prints its backtrace (and causes)
+#   agentmon top --no-color             no colour on a terminal; --color colours a pipe (| less -R)
+#
+# Without --color/--no-color, colour follows the terminal and NO_COLOR/FORCE_COLOR as usual.
+module Agentmon
+  cli do
+    version Agentmon::VERSION
+    completion
+    trace_option
+    color_option
+  end
+end

data/lib/agentmon/commands/footprint.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "json"
+
+# `agentmon footprint`: real memory by agent session now, largest first, with what is growing and
+# what is paging.
+#
+#   agentmon footprint          a table (boxed on a terminal, plain aligned columns in a pipe)
+#   agentmon footprint --json   one JSON object per session per line, raw units, for scripts
+#
+#   Session            Processes  Footprint  Share  Resident  Wired  Peak    Growth  Pageins/s
+#   claude 200 · repo          4       628M   5.1%      630M   1.0M  628M  +1.0M/s       10.0
+#   Claude 300                 3       501M   4.1%      530M     0B  501M    +0B/s        0.0
+#
+#   compressed 2.0G · swap 512M (per-process compressed/swap needs root)
+#
+# Footprint is what Activity Monitor calls Memory, summed over the session's processes (each
+# once); Share is its percent of the machine's used memory; Peak the largest footprint seen over
+# the session's life; Growth the footprint change per second over the last minute (a single run
+# sees only the half second between its two samples); Pageins/s counts page-ins (each waited for
+# the disk). Sizes are binary (1M = 1024²), as in the dashboard. The last line is the machine's
+# compressed memory and swap used: macOS splits those out per process only for root. `--json`
+# prints SessionMemory fields (bytes, bytes/s, percent, events/s; null when unknown).
+module Agentmon
+  module Commands
+    module FootprintList
+      HEADERS = ["Session", "Processes", "Footprint", "Share", "Resident", "Wired", "Peak", "Growth",
+                 "Pageins/s"].freeze
+      RIGHT = (1..8).to_h { |i| [i, :right] }.freeze
+      EMPTY = "No agent sessions running."
+
+      module_function
+
+      def cells(m)
+        f = R2UI::Format
+        [m.label, m.processes.to_s, f.call(:bytes, m.footprint), f.call(:percent, m.share), f.call(:bytes, m.resident),
+         f.call(:bytes, m.wired), f.call(:bytes, m.peak_footprint), growth(m.growth_rate),
+         f.call(:number, m.pagein_rate)].map(&:to_s)
+      end
+
+      # "+1.5M/s", "-12K/s"; "" when unknown.
+      def growth(rate)
+        return "" if rate.nil?
+
+        "#{rate.negative? ? "-" : "+"}#{R2UI::Format.bytes(rate.abs)}/s"
+      end
+
+      # The machine's compressed and swap, or nil without a MemoryView.
+      def machine(memory)
+        memory && "compressed #{R2UI::Format.bytes(memory.compressed.to_i)} · swap #{R2UI::Format.bytes(memory.swap_used.to_i)} " \
+                  "(per-process compressed/swap needs root)"
+      end
+
+      def json(m) = JSON.generate(m.to_h)
+    end
+  end
+
+  command :footprint do
+    summary "Real memory by agent session now: footprint, share, growth, paging"
+    flag :json, desc: "One JSON object per session per line, in raw units"
+
+    run do
+      list = Commands::FootprintList
+      reading = Agentmon.engine.current
+      rows = reading[:session_memory] || [] # nil when the metric failed this sample (the error goes to stderr)
+      if options[:json]
+        rows.each { |m| shell.puts(list.json(m)) }
+      elsif rows.empty?
+        shell.puts(list::EMPTY)
+      else
+        cells = Commands::SessionList.fit(rows.map { |m| list.cells(m) }, list::HEADERS, width: shell.width,
+                                                                                         boxed: shell.live?)
+        table(cells, headers: list::HEADERS, align: list::RIGHT)
+        if (line = list.machine(reading[:memory]))
+          shell.puts
+          shell.puts(line)
+        end
+      end
+    end
+  end
+end

data/lib/agentmon/commands/memory.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+
+# `agentmon memory`: this Mac's RAM right now, the way Activity Monitor breaks it down, then the
+# agent sessions pushing memory pressure hardest.
+#
+#   agentmon memory
+#
+#   Memory
+#     Total          16G
+#     Used           12G
+#     App            8.0G
+#     Wired          2.0G
+#     Compressed     2.0G (3.1x)
+#     Cached         3.0G
+#     Swap           1.0G / 2.0G
+#     Swap in        1.0K/s
+#     Swap out       0B/s
+#     Compression    2.0M/s
+#     Decompression  512K/s
+#     Pressure       35.0%
+#
+#   Pressure drivers
+#   Session            Footprint  Share   Growth
+#   claude 200 · repo       512M   4.2%  +1.0M/s
+#
+#   agentmon memory --json    one JSON object: {"memory": {...}, "pressure_drivers": [...]} in raw
+#                             units (bytes, bytes/s, percent) for scripts
+#
+# Used = App + Wired + Compressed; Compressed is the RAM the compressor occupies and (3.1x) how much
+# it holds per byte. Rates are since the previous sample. Pressure is 100 - kern.memorystatus_level.
+# Share is a session's footprint as a percent of used memory; Growth its footprint change per
+# second over the last minute. Sizes are binary (1G = 1024³), as in the dashboard. "—" is unknown.
+module Agentmon
+  module Commands
+    module MemoryReport
+      DRIVERS = 5
+      HEADERS = %w[Session Footprint Share Growth].freeze
+      RIGHT = { 1 => :right, 2 => :right, 3 => :right }.freeze
+
+      module_function
+
+      # [[key, value]] for r2ui `pairs`; nil values print as "—".
+      def pairs(view)
+        size = ->(v) { v && R2UI::Format.bytes(v) }
+        rate = ->(v) { v && R2UI::Format.call(:bytes_per_sec, v) }
+        compressed = size.(view.compressed)
+        compressed = "#{compressed} (#{R2UI::Format.call(:ratio, view.compression_ratio)})" if compressed && view.compression_ratio
+        swap = [view.swap_used, view.swap_total].all?(&:nil?) ? nil : "#{size.(view.swap_used) || "—"} / #{size.(view.swap_total) || "—"}"
+        [
+          ["Total", size.(view.total)], ["Used", size.(view.used)], ["App", size.(view.app)],
+          ["Wired", size.(view.wired)], ["Compressed", compressed], ["Cached", size.(view.cached)], ["Swap", swap],
+          ["Swap in", rate.(view.swapin_rate)], ["Swap out", rate.(view.swapout_rate)],
+          ["Compression", rate.(view.compression_rate)], ["Decompression", rate.(view.decompression_rate)],
+          ["Pressure", view.pressure && R2UI::Format.call(:percent, view.pressure)]
+        ]
+      end
+
+      def cells(driver)
+        f = R2UI::Format
+        [driver.label, f.call(:bytes, driver.footprint), f.call(:percent, driver.share), growth(driver.growth_rate)]
+      end
+
+      # "+1.0M/s", "-2.0K/s", "0B/s" (Format.bytes doesn't take negatives).
+      def growth(rate)
+        return "" if rate.nil?
+
+        sign = if rate.positive? then "+" elsif rate.negative? then "-" else "" end
+        "#{sign}#{R2UI::Format.call(:bytes_per_sec, rate.abs)}"
+      end
+
+      def json(view, drivers)
+        JSON.generate(memory: view.to_h, pressure_drivers: drivers&.map(&:to_h))
+      end
+    end
+  end
+
+  command :memory do
+    summary "RAM breakdown, pressure and the sessions driving it"
+    flag :json, desc: "Print raw values as one JSON object"
+
+    run do
+      report = Commands::MemoryReport
+      reading = Agentmon.engine.current
+      view = reading[:memory]
+      drivers = reading[:pressure_drivers]
+      unless view
+        # abort! skips after_run hooks, so say what broke here.
+        Agentmon.engine_errors.each { |name, message| shell.err_puts("#{shell.symbol(:warn)} #{name}: #{message}") }
+        abort!("Memory isn't available (no memory metric, or it failed this sample)")
+      end
+
+      if options[:json]
+        shell.puts(report.json(view, drivers))
+      else
+        pairs report.pairs(view), title: "Memory"
+        if drivers
+          say
+          say "Pressure drivers", :heading
+          if drivers.empty?
+            say "No agent sessions are using memory.", :muted
+          else
+            table(drivers.first(report::DRIVERS).map { |d| report.cells(d) }, headers: report::HEADERS, align: report::RIGHT)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agentmon/commands/record.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# `agentmon record`: keeps a history of agent sessions without the dashboard open. Samples every
+# `--interval` seconds with recording on, so every recorder (sessions, memory, ...) appends to the
+# store (`$AGENTMON_STATE_DIR`, else `~/.local/state/agentmon`), until ctrl+c or TERM.
+#
+#   agentmon record                     on a terminal: one live status line, redrawn in place
+#   agentmon record --interval 5        sample every 5 s instead of 2
+#   agentmon record --prune 14          first delete day files older than 14 days
+#   agentmon record > record.log        off a terminal: one status line a minute
+#
+#   recording 3 sessions to /Users/me/.local/state/agentmon
+#
+# TERM (launchd, `kill`) exits 0 and ctrl+c exits 130, both after the current sample: every store
+# line is complete and on disk (each append closes its file). `agentmon report` reads the history.
+module Agentmon
+  module Commands
+    module Record
+      # Seconds between status lines off a terminal.
+      STATUS_EVERY = 60
+      # Exit code per signal that stops recording.
+      SIGNALS = { "TERM" => 0, "INT" => 130 }.freeze
+
+      # The stop flag the signal handlers raise. `request` only writes to a pipe, which is safe in a
+      # trap handler; `wait` sleeps until the timeout or a request, whichever comes first.
+      class Stop
+        attr_reader :signal
+
+        def initialize
+          @reader, @writer = IO.pipe
+        end
+
+        def request(signal)
+          @signal ||= signal
+          @writer.write_nonblock(".", exception: false)
+        end
+
+        def requested? = !@signal.nil?
+
+        def wait(seconds)
+          @reader.wait_readable(seconds) if seconds.positive? && !requested?
+          requested?
+        end
+
+        def close = [@reader, @writer].each(&:close)
+      end
+
+      module_function
+
+      # "recording 3 sessions to <dir>"; without the session ledger (nil), just "recording to <dir>".
+      def status(reading, store)
+        sessions = reading[:session_ledger]
+        count = sessions && " #{R2UI::CLI::Ext::HumanFormat.plural(sessions.count(&:alive?), "session")}"
+        "recording#{count} to #{store.dir}"
+      end
+
+      # Samples every `interval` seconds with recording on until `stop` is requested: a live status
+      # line on a terminal, a plain one every STATUS_EVERY seconds off it. Returns the signal.
+      def run(engine, shell:, interval:, stop:, clock: Clock, status_every: STATUS_EVERY)
+        was = engine.recording
+        engine.recording = true
+        line = "recording to #{engine.store.dir}"
+        live = R2UI::CLI::Live.new(shell, fps: 2) { |frame| "#{R2UI::CLI::Live.spinner(frame)} #{line}" }
+        next_status = nil
+        live.run do
+          until stop.requested?
+            started = clock.mono
+            line = status(engine.current(max_age: 0), engine.store)
+            if live.live?
+              live.refresh
+            elsif next_status.nil? || started >= next_status
+              shell.puts(line)
+              next_status = started + status_every
+            end
+            stop.wait(interval - (clock.mono - started))
+          end
+        end
+        stop.signal
+      ensure
+        engine.recording = was
+      end
+    end
+  end
+
+  command :record do
+    summary "Record agent sessions to the history until ctrl+c or TERM"
+    option :interval, :float, default: 2.0, desc: "Seconds between samples"
+    option :prune, :integer, desc: "First delete day files older than this many days"
+
+    run do
+      record = Commands::Record
+      usage_error!("--interval must be more than 0") unless options[:interval].positive?
+      usage_error!("--prune must be at least 1 day") if options[:prune] && options[:prune] < 1
+      engine = Agentmon.engine
+      abort!("no store to record to") unless engine.store
+      if options[:prune]
+        removed = engine.store.prune(days: options[:prune])
+        plural = R2UI::CLI::Ext::HumanFormat.method(:plural)
+        shell.puts("pruned #{plural.call(removed.size, "day file")} older than #{plural.call(options[:prune], "day")}")
+      end
+
+      stop = record::Stop.new
+      previous = record::SIGNALS.keys.to_h { |sig| [sig, Signal.trap(sig) { stop.request(sig) }] }
+      begin
+        signal = record.run(engine, shell:, interval: options[:interval], stop:)
+      ensure
+        previous.each { |sig, handler| Signal.trap(sig, handler || "DEFAULT") }
+        stop.close
+      end
+      code = record::SIGNALS.fetch(signal, 0)
+      next if code.zero?
+
+      # halt skips the after_run hooks, so report what's broken here, as they would.
+      engine.errors.each { |name, message| shell.err_puts("#{shell.symbol(:warn)} #{name}: #{message}") }
+      halt(code)
+    end
+  end
+end

data/lib/agentmon/commands/report.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+# `agentmon report`: what agent sessions cost this Mac over a period, from the recorded history
+# (the `sessions` store lines that the dashboard and `agentmon record` write).
+#
+#   agentmon report               the last 24 hours
+#   agentmon report --since 90m   or 2h, 3d
+#   agentmon report --json        one merged record per line, raw units (bytes, seconds)
+#
+#   Agent sessions · last 24h
+#
+#   Session             Started  Duration  Peak    CPU  Written  Status
+#   claude 4242 · repo    09:14    2h 0m   900M  10m 0s    2.0G  ended 11:14
+#   claude 4300 · web     13:40    1h 0m   2.0G  1h 0m    100M  ended (not seen after 14:02)
+#   claude 4410 · repo    15:02   20m 5s   100M  1m 0s      0B  running
+#
+#   3 sessions · 1h 11m CPU · 2.1G written
+#
+# Lines of one session (several agentmon runs record it) are merged taking each lifetime total's
+# maximum: every run recounts from the kernel's counters, so a sum would double count. A session
+# with no end whose last line is over a minute old is shown ended when it was last seen, never
+# running: agentmon wasn't running when it ended. Sizes are binary (1G = 1024³), as in the
+# dashboard; written bytes are a lower bound (see docs/design.md, "Lifetime totals").
+module Agentmon
+  module Commands
+    module Report
+      PERIOD = /\A([1-9]\d*)([mhd])\z/
+      UNIT = { "m" => 60, "h" => 3600, "d" => 86_400 }.freeze
+      # A session with no ended_at is running only if it was seen this recently (6 recorder lines).
+      RUNNING_WITHIN = 60
+      TOTALS = %i[cpu_seconds bytes_read bytes_written peak_footprint].freeze
+      HEADERS = %w[Session Started Duration Peak CPU Written Status].freeze
+      RIGHT = { 1 => :right, 2 => :right, 3 => :right, 4 => :right, 5 => :right }.freeze
+
+      # The --since value type: the text back when it's a period ("90m", "2h", "3d").
+      SINCE = lambda do |text|
+        raise ArgumentError, "expects a period like 90m, 2h or 3d" unless PERIOD.match?(text)
+
+        text
+      end
+
+      module_function
+
+      def seconds(period)
+        number, unit = PERIOD.match(period).captures
+        Integer(number) * UNIT.fetch(unit)
+      end
+
+      # Store lines → one Hash per session id, oldest start first, with `status` ("running",
+      # "ended", "not_seen") and `duration` (seconds) added, and the per-line `t` and `run` gone.
+      def merge(lines, now:)
+        lines.group_by { |l| l[:id] }.map do |_id, group|
+          group = group.sort_by { |l| l[:t].to_f }
+          merged = group.last.except(:t, :run)
+          TOTALS.each { |k| merged[k] = group.filter_map { |l| l[k] }.max }
+          merged[:started_at] = group.filter_map { |l| l[:started_at] }.min
+          merged[:first_seen_at] = group.filter_map { |l| l[:first_seen_at] }.min
+          merged[:last_seen_at] = group.filter_map { |l| l[:last_seen_at] }.max
+          merged[:ended_at] = group.filter_map { |l| l[:ended_at] }.max
+          finish(merged, now)
+        end.sort_by { |s| [(s[:started_at] || s[:first_seen_at]).to_f, s[:id].to_s] }
+      end
+
+      def finish(session, now)
+        last = session[:last_seen_at]
+        session[:status] = if session[:ended_at] then "ended"
+                           elsif last && now - last <= RUNNING_WITHIN then "running"
+                           else "not_seen"
+                           end
+        start = session[:started_at] || session[:first_seen_at]
+        stop = session[:ended_at] || last
+        session[:duration] = start && stop ? [stop - start, 0.0].max : nil
+        session
+      end
+
+      # "14:02" today, "Sep 30 14:02" on another day.
+      def clock(t, now)
+        return "" unless t
+
+        time = Time.at(t)
+        time.strftime("%F") == Time.at(now).strftime("%F") ?time.strftime("%H:%M") : time.strftime("%b %-d %H:%M")
+      end
+
+      def status(session, now)
+        case session[:status]
+        when "running" then "running"
+        when "ended" then "ended #{clock(session[:ended_at], now)}"
+        else "ended (not seen after #{clock(session[:last_seen_at], now)})"
+        end
+      end
+    end
+  end
+
+  command :report do
+    summary "Agent sessions recorded over a period, with their peak memory, CPU and disk writes"
+    option :since, Commands::Report::SINCE, default: "24h", placeholder: "period", desc: "How far back: 90m, 2h, 3d"
+    flag :json, desc: "One merged session record per line, raw units"
+
+    run do
+      report = Commands::Report
+      now = Clock.now
+      store = Agentmon.engine.store || Store.new
+      sessions = report.merge(store.each(:sessions, since: now - report.seconds(options[:since])).to_a, now:)
+
+      if options[:json]
+        sessions.each { |s| shell.puts(JSON.generate(s)) }
+      elsif sessions.empty?
+        say "No agent sessions recorded in the last #{options[:since]}."
+      else
+        bytes = ->(n) { R2UI::Format.call(:bytes, n) }
+        time = ->(s) { s ? duration(s) : "" }
+        heading "Agent sessions · last #{options[:since]}"
+        rows = sessions.map do |s|
+          [s[:label].to_s, report.clock(s[:started_at] || s[:first_seen_at], now), time.call(s[:duration]),
+           bytes.call(s[:peak_footprint]), time.call(s[:cpu_seconds]), bytes.call(s[:bytes_written]), report.status(s, now)]
+        end
+        table rows, headers: report::HEADERS, align: report::RIGHT
+        say
+        cpu = sessions.sum { |s| s[:cpu_seconds].to_f }
+        written = sessions.sum { |s| s[:bytes_written].to_i }
+        say "#{plural(sessions.size, "session")} · #{duration(cpu)} CPU · #{bytes.call(written)} written"
+      end
+    end
+  end
+end