agentmon 0.1.0

data/lib/agentmon/probes/network.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require "pty"
+
+module Agentmon
+  # sample[:network]: every process's sockets and byte counters, as a NetSnapshot (model.rb), from
+  # ONE long-lived `nettop` child. Nil until its first block arrives, when the latest block is older
+  # than STALE seconds (nettop stalled), and off macOS.
+  #
+  # nettop in connection mode (`-x -L 0 -s 1 -J interface,state,bytes_in,bytes_out`, no -P) prints
+  # one block a second: a header line `,interface,state,bytes_in,bytes_out,`, then per process a
+  # line `Name With Spaces.PID,,,BYTES_IN,BYTES_OUT,` followed by its flows:
+  #
+  #   tcp4 192.0.2.5:55584<->198.51.100.11:5223,en0,Established,3177530,7189392,
+  #   udp4 *:5353<->*:*,en0,,4823549,2970949,
+  #   tcp6 fe80::1%lo0.53<->*.*,lo0,Listen,,,
+  #
+  # IPv6 endpoints put `.` before the port, IPv4 (and host names) `:`; `*` is a wildcard; empty byte
+  # fields are unknown (nil). Byte counts are cumulative. A one-shot `nettop -L 1` takes ~5 s, so it
+  # is never run per sample or per process.
+  #
+  # Piped, nettop block-buffers its output (nothing for many seconds), so the child runs under a pty
+  # (PTY.spawn), where each block arrives at once. A reader thread parses lines and publishes each
+  # complete block, frozen, as soon as the next header arrives or the pty has been idle for IDLE
+  # seconds. `at_mono` is when the block's header arrived, so rates come from the snapshots' own
+  # clock whatever the engine's interval. The child starts on the first probe call, restarts at most
+  # once every RESTART_EVERY seconds when it dies (MISSING_RETRY when nettop is missing), and is
+  # stopped (TERM, KILL after KILL_AFTER, then reaped) by an at_exit hook or Stream#stop.
+  module Probes
+    module Network
+      COMMAND = %w[/usr/bin/nettop -x -L 0 -s 1 -J interface,state,bytes_in,bytes_out].freeze
+
+      module_function
+
+      # Every block in captured nettop text, as NetSnapshots (the last one even when its block is
+      # cut short). Block i gets at_mono `at_mono + i * every`. Pure; tests feed it fixtures.
+      def parse(text, at_mono: 0.0, every: 1.0)
+        parser = Parser.new
+        blocks = -1
+        snapshots = text.each_line.filter_map do |line|
+          blocks += 1 if Parser.header?(line)
+          parser.feed(line, at_mono + (blocks * every))
+        end
+        last = parser.flush
+        last ? snapshots << last : snapshots
+      end
+
+      # The process's one stream.
+      def stream = @stream ||= Stream.new
+
+      # The probe: the latest snapshot, starting nettop when needed. Never raises into the sampler.
+      def read
+        Darwin.available? ? stream.snapshot : nil
+      rescue StandardError
+        nil
+      end
+
+      # Turns nettop lines into NetSnapshots, one block at a time. Not thread-safe: one feeder.
+      class Parser
+        HEADER = /\A,interface,/
+
+        def self.header?(line) = HEADER.match?(line)
+
+        def initialize
+          @block = nil   # { at_mono:, processes: { pid => builder Hash } }
+          @current = nil # the process the next flow lines belong to
+          @dirty = false # changed since the last snapshot handed out
+        end
+
+        # Feeds one line; returns the previous block's snapshot when this line is the header that
+        # closes it (and it changed since it was last handed out), else nil. Lines before the first
+        # header (a block we joined midway) are dropped.
+        def feed(line, at_mono)
+          line = line.delete("\r\n")
+          return nil if line.empty?
+
+          if self.class.header?(line)
+            done = flush
+            @block = { at_mono:, processes: {} }
+            @current = nil
+            @dirty = true
+            return done
+          end
+          return nil unless @block
+
+          add(line)
+          nil
+        end
+
+        # The block so far as a snapshot, if it changed since the last one handed out; else nil.
+        def flush
+          return nil unless @block && @dirty
+
+          @dirty = false
+          snapshot
+        end
+
+        private
+
+        def add(line)
+          head, interface, state, bytes_in, bytes_out = fields(line)
+          return unless head
+
+          if head.include?("<->")
+            return unless @current
+
+            @current[:flows] << flow(head, interface, state, bytes_in, bytes_out)
+          else
+            name, dot, pid = head.rpartition(".")
+            pid = Integer(pid, 10, exception: false)
+            return if dot.empty? || pid.nil?
+
+            @current = @block[:processes][pid] = { pid:, name:, bytes_in: count(bytes_in),
+                                                   bytes_out: count(bytes_out), flows: [] }
+          end
+          @dirty = true
+        end
+
+        # [first field, interface, state, bytes_in, bytes_out]; the first field may hold commas.
+        def fields(line)
+          parts = line.split(",", -1)
+          parts.pop if line.end_with?(",")
+          return nil if parts.size < 5
+
+          [parts[0...-4].join(","), *parts[-4..]]
+        end
+
+        def flow(head, interface, state, bytes_in, bytes_out)
+          protocol, endpoints = head.split(" ", 2)
+          local, remote = endpoints.to_s.split("<->", 2)
+          host, port = Network.endpoint(remote, protocol)
+          NetFlow.new(protocol:, local:, remote:, remote_host: host, remote_port: port,
+                      interface: blank(interface), state: blank(state), bytes_in: count(bytes_in),
+                      bytes_out: count(bytes_out))
+        end
+
+        def snapshot
+          processes = @block[:processes].transform_values do |p|
+            NetProcess.new(**p.except(:flows), flows: p[:flows].dup.freeze)
+          end
+          NetSnapshot.new(at_mono: @block[:at_mono], processes: processes.freeze)
+        end
+
+        def count(text) = text.nil? || text.empty? ? nil : Integer(text, 10, exception: false)
+
+        def blank(text) = text.nil? || text.empty? ? nil : text
+      end
+
+      # [host, port] of an endpoint as nettop prints it: IPv6 (`protocol` ending in 6) separates the
+      # port with the last `.`, IPv4 and names with `:`. `*` (either part) is nil.
+      def endpoint(text, protocol)
+        return [nil, nil] if text.nil? || text.empty?
+
+        separators = protocol.to_s.end_with?("6") ? [".", ":"] : [":", "."]
+        host, port = nil
+        separators.each do |sep|
+          h, s, p = text.rpartition(sep)
+          next if s.empty?
+
+          host = h
+          port = p
+          break
+        end
+        host ||= text
+        host = nil if host == "*"
+        port = port.nil? || port == "*" ? nil : Integer(port, 10, exception: false)
+        [host, port]
+      end
+
+      # The nettop child and its reader thread. `feed`/`idle` are the reader's entry points, public
+      # so tests drive publishing without spawning.
+      class Stream
+        IDLE = 0.05           # seconds of pty silence that end a block
+        STALE = 5.0           # a snapshot older than this is not returned
+        RESTART_EVERY = 10.0  # seconds between starts when the child keeps dying
+        MISSING_RETRY = 60.0  # seconds between tries when nettop is missing
+        KILL_AFTER = 1.0      # seconds between TERM and KILL on stop
+
+        attr_reader :pid
+
+        def initialize(command: COMMAND, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          @command = command
+          @clock = clock
+          @parser = Parser.new
+          @latest = nil
+          @next_start = nil
+          @lock = Mutex.new
+        end
+
+        # The probe's call: starts (or restarts) nettop when due, returns the latest fresh snapshot.
+        def snapshot
+          @lock.synchronize { ensure_running }
+          latest
+        end
+
+        # The latest published snapshot, or nil when none yet or it is older than STALE.
+        def latest
+          snap = @latest
+          snap if snap && @clock.call - snap.at_mono <= STALE
+        end
+
+        # One line from nettop (the reader thread, or a test).
+        def feed(line) = publish(@parser.feed(line, @clock.call))
+
+        # The pty went quiet: the block so far is complete.
+        def idle = publish(@parser.flush)
+
+        def running? = !@pid.nil? && !reaped?(@pid)
+
+        def start
+          now = @clock.call
+          unless File.executable?(@command.first)
+            @next_start = now + MISSING_RETRY
+            return false
+          end
+
+          @next_start = now + RESTART_EVERY
+          @parser = Parser.new
+          reader, writer, @pid = PTY.spawn(*@command)
+          writer.close
+          @reader = reader
+          @thread = Thread.new { read_loop(reader) }
+          @thread.report_on_exception = false
+          register_exit_hook
+          true
+        rescue SystemCallError
+          @next_start = now + MISSING_RETRY
+          false
+        end
+
+        # Stops the child (TERM, then KILL after KILL_AFTER) and reaps it; safe to call twice.
+        def stop
+          @lock.synchronize do
+            pid = @pid
+            @pid = nil
+            terminate(pid) if pid
+            begin
+              @reader&.close
+            rescue IOError
+              nil
+            end
+            @thread&.join(1)
+            @thread = nil
+            @reader = nil
+            @next_start = nil
+          end
+        end
+
+        private
+
+        def ensure_running
+          return if running?
+          return if @next_start && @clock.call < @next_start
+
+          start
+        end
+
+        def publish(snap)
+          @latest = snap if snap
+          snap
+        end
+
+        def read_loop(io)
+          buffer = String.new(encoding: Encoding::BINARY)
+          loop do
+            unless io.wait_readable(IDLE)
+              idle
+              next
+            end
+            chunk = io.read_nonblock(65_536, exception: false)
+            next if chunk == :wait_readable
+            break if chunk.nil?
+
+            buffer << chunk
+            while (i = buffer.index("\n"))
+              feed(buffer.slice!(0..i).force_encoding(Encoding::UTF_8).scrub)
+            end
+          end
+        rescue IOError, SystemCallError # Errno::EIO when the child exits; IOError when stop closes it
+          nil
+        ensure
+          idle
+        end
+
+        # True when `pid` has exited (and is now reaped).
+        def reaped?(pid)
+          !Process.waitpid(pid, Process::WNOHANG).nil?
+        rescue Errno::ECHILD
+          true
+        end
+
+        def terminate(pid)
+          signal(:TERM, pid)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + KILL_AFTER
+          until reaped?(pid)
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+              signal(:KILL, pid)
+              begin
+                Process.waitpid(pid)
+              rescue Errno::ECHILD
+                nil
+              end
+              break
+            end
+            sleep 0.01
+          end
+        end
+
+        def signal(name, pid)
+          Process.kill(name, pid)
+        rescue Errno::ESRCH, Errno::EPERM
+          nil
+        end
+
+        def register_exit_hook
+          return if @exit_hook
+
+          @exit_hook = true
+          at_exit { stop }
+        end
+      end
+    end
+  end
+
+  probe(:network) { Probes::Network.read }
+end

data/lib/agentmon/probes/processes.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+# sample[:processes]: every process, as ProcessStat (lib/agentmon/model.rb).
+#
+# One `ps` for the whole table (pid, ppid, rss, %cpu, executable path: what rusage lacks), then
+# proc_pid_rusage and proc_pidinfo(PROC_PIDTASKALLINFO) through Fiddle for each pid: no
+# subprocess per process. ~800 processes take ~50 ms on an M-series Mac: ~12 ms of Fiddle calls
+# and decoding, the rest ps.
+#
+# Processes the kernel won't describe (other users', EPERM) and ones that exit between ps and
+# rusage (ESRCH) keep their ps values: `readable: false`, resident from ps rss, ps %cpu, and nil
+# footprint, CPU time, disk I/O, faults and scheduling counters.
+module Agentmon
+  module Probes
+    module Processes
+      PS = %w[ps -axo pid=,ppid=,rss=,pcpu=,comm=].freeze
+
+      module_function
+
+      # `ps_text` and `reader` (anything with Darwin's `rusage(pid)`, `task_info(pid)` and
+      # `started_at(pid)`) are injectable for tests.
+      #
+      # Two calls per readable process: rusage, then task_info (start time plus fault and
+      # scheduling counters, one proc_pidinfo). Only if task_info fails where rusage worked (not
+      # seen on macOS 26) does a third call fetch the start time alone.
+      def read(ps_text: IO.popen(PS, err: File::NULL, &:read), reader: Darwin)
+        parse_ps(ps_text).map do |row|
+          usage = reader.rusage(row[:pid])
+          task = usage && reader.task_info(row[:pid])
+          build(row, usage, task ? task.started_at : (usage && reader.started_at(row[:pid])), task)
+        end
+      end
+
+      # ps lines -> Hashes. comm is last and may contain spaces.
+      def parse_ps(text)
+        text.each_line.filter_map do |line|
+          pid, ppid, rss, pcpu, path = line.strip.split(nil, 5)
+          next unless path
+
+          { pid: pid.to_i, ppid: ppid.to_i, rss: rss.to_i * 1024, pcpu: pcpu.to_f, path: }
+        end
+      end
+
+      def build(row, usage, started_at, task = nil)
+        ProcessStat.new(
+          pid: row[:pid], ppid: row[:ppid], name: File.basename(row[:path]), path: row[:path],
+          readable: !usage.nil?,
+          start_ticks: usage&.start_ticks,
+          started_at:,
+          cpu_time: usage&.cpu_time,
+          child_cpu_time: usage&.child_cpu_time,
+          resident: usage ? usage.resident : row[:rss],
+          footprint: usage&.footprint,
+          peak_footprint: usage&.peak_footprint,
+          disk_read: usage&.disk_read,
+          disk_written: usage&.disk_written,
+          ps_cpu: row[:pcpu],
+          wired: usage&.wired,
+          pageins: usage&.pageins,
+          runnable_time: usage&.runnable_time,
+          faults: task&.faults,
+          cow_faults: task&.cow_faults,
+          context_switches: task&.context_switches,
+          threads: task&.threads,
+          running_threads: task&.running_threads
+        )
+      end
+    end
+  end
+
+  probe(:processes) { Probes::Processes.read }
+end

data/lib/agentmon/probes/system.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Agentmon
+  # sample[:system]: machine-wide CPU, load and network counters, read once per sample.
+  #
+  #   cpu_ticks  [user, system, idle, nice]: cumulative ticks over all CPUs since boot
+  #              (host_statistics(HOST_CPU_LOAD_INFO), Integers; only deltas mean anything)
+  #   ncpu       logical CPUs (hw.logicalcpu, else hw.ncpu)
+  #   load       [1, 5, 15]-minute load averages (getloadavg, Floats)
+  #   net_in     cumulative bytes received over every interface except lo0 (netstat -ibn)
+  #   net_out    cumulative bytes sent, likewise
+  #   at_mono    monotonic clock when read (seconds), for rates
+  #
+  # One `netstat -ibn` per sample (no per-interface work). It prints one `<Link#N>` row per
+  # interface plus one row per address with the same counters; only the Link rows are summed, so an
+  # interface with three addresses counts once. CPU, load and ncpu come through Fiddle.
+  #
+  # Each part is read on its own: one that fails (netstat missing, a sysctl refused) leaves its
+  # fields nil and the others still arrive. Off macOS the probe is nil.
+  SystemStat = Data.define(:cpu_ticks, :ncpu, :load, :net_in, :net_out, :at_mono)
+
+  module Probes
+    module System
+      HOST_CPU_LOAD_INFO = 3
+      CPU_STATES = 4 # CPU_STATE_USER, CPU_STATE_SYSTEM, CPU_STATE_IDLE, CPU_STATE_NICE
+      NETSTAT = %w[netstat -ibn].freeze
+
+      module_function
+
+      # Reads the live machine.
+      def read
+        net_in, net_out = attempt { parse_netstat(netstat) }
+        SystemStat.new(cpu_ticks: attempt { Native.cpu_ticks }, ncpu: attempt { Native.ncpu },
+                       load: attempt { Native.load_average }, net_in:, net_out:,
+                       at_mono: Process.clock_gettime(Process::CLOCK_MONOTONIC))
+      end
+
+      # [bytes in, bytes out] summed over the `<Link#N>` rows of `netstat -ibn` output, lo0 left
+      # out; nil when there is no Link row (not netstat's table). Pure; tests feed it captured text.
+      #
+      # Columns: Name Mtu Network Address Ipkts Ierrs Ibytes Opkts Oerrs Obytes Coll. Address is
+      # empty for some interfaces (utun, gif), so the counters are taken from the right.
+      def parse_netstat(text)
+        found = false
+        totals = text.each_line.each_with_object([0, 0]) do |line, sums|
+          fields = line.split
+          next unless fields.size >= 10 && fields[2]&.start_with?("<Link#")
+          next if fields[0].delete_suffix("*") == "lo0"
+
+          ibytes = Integer(fields[-5], exception: false)
+          obytes = Integer(fields[-2], exception: false)
+          next unless ibytes && obytes
+
+          found = true
+          sums[0] += ibytes
+          sums[1] += obytes
+        end
+        found ? totals : nil
+      end
+
+      def netstat = IO.popen(NETSTAT, err: File::NULL, &:read)
+
+      # The block's value, or nil when it raises (a part that can't be read stays unknown).
+      def attempt
+        yield
+      rescue StandardError # Fiddle::DLError, Errno::ENOENT (no netstat), Agentmon::Error
+        nil
+      end
+
+      # The Fiddle calls. Buffers are per call, so reads from several threads don't share memory.
+      module Native
+        module_function
+
+        # host_cpu_load_info: natural_t cpu_ticks[CPU_STATE_MAX], in user/system/idle/nice order.
+        def cpu_ticks
+          buffer = Fiddle::Pointer.malloc(4 * CPU_STATES, Fiddle::RUBY_FREE)
+          count = Fiddle::Pointer.malloc(4, Fiddle::RUBY_FREE)
+          count[0, 4] = [CPU_STATES].pack("L")
+          result = functions[:host_statistics].call(host, HOST_CPU_LOAD_INFO, buffer, count)
+          raise Error, "host_statistics failed (kern_return_t #{result})" unless result.zero?
+
+          buffer[0, 4 * CPU_STATES].unpack("L<#{CPU_STATES}")
+        end
+
+        def load_average
+          buffer = Fiddle::Pointer.malloc(8 * 3, Fiddle::RUBY_FREE)
+          n = functions[:getloadavg].call(buffer, 3)
+          raise Error, "getloadavg failed" unless n == 3
+
+          buffer[0, 24].unpack("d3")
+        end
+
+        # Logical CPUs: constant for the process's life, so read once.
+        def ncpu = @ncpu ||= sysctl_int("hw.logicalcpu") || sysctl_int("hw.ncpu")
+
+        # An integer sysctl of 4 or 8 bytes, or nil.
+        def sysctl_int(name)
+          buffer = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+          length = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+          length[0, 8] = [8].pack("Q")
+          return nil unless functions[:sysctlbyname].call(name, buffer, length, nil, 0).zero?
+
+          case length[0, 8].unpack1("Q")
+          when 4 then buffer[0, 4].unpack1("l<")
+          when 8 then buffer[0, 8].unpack1("q<")
+          end
+        end
+
+        # mach_host_self() returns a send right each call; take it once.
+        def host = @host ||= functions[:mach_host_self].call
+
+        def lib = @lib ||= Fiddle.dlopen(nil)
+
+        def functions
+          @functions ||= {
+            mach_host_self: Fiddle::Function.new(lib["mach_host_self"], [], -Fiddle::TYPE_INT),
+            host_statistics: Fiddle::Function.new(lib["host_statistics"],
+                                                  [-Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP,
+                                                   Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT),
+            getloadavg: Fiddle::Function.new(lib["getloadavg"], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT],
+                                             Fiddle::TYPE_INT),
+            sysctlbyname: Fiddle::Function.new(lib["sysctlbyname"],
+                                               [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP,
+                                                Fiddle::TYPE_VOIDP, Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT)
+          }
+        end
+      end
+    end
+  end
+
+  probe(:system) { Darwin.available? ? Probes::System.read : nil }
+end

data/lib/agentmon/program.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Agentmon
+  # The `agentmon` command line, an r2ui CLI program: the root (no command) opens the dashboard
+  # in a layout (`--layout`, default dense), and every registered command is a subcommand.
+  module Program
+    # The panel dashboard (rows and panels from Agentmon.row/panel), i.e. UI.install(view: nil).
+    CLASSIC = "classic"
+    DEFAULT_LAYOUT = "dense"
+
+    module_function
+
+    # The --layout choices: classic plus the registered views.
+    def layouts(registry = Agentmon.registry) = [CLASSIC, *UI.layouts(registry).map(&:to_s)]
+
+    # The view UI.install takes for a --layout choice (nil: the classic dashboard).
+    def view(layout) = layout == CLASSIC ? nil : layout&.to_sym
+
+    def build(registry: Agentmon.registry)
+      layouts = Program.layouts(registry)
+      default = layouts.include?(DEFAULT_LAYOUT) ? DEFAULT_LAYOUT : CLASSIC
+      R2UI.cli("agentmon") do
+        summary "What AI coding agents (Claude, Codex) cost this Mac"
+        description <<~TEXT.chomp
+          With no command, opens the dashboard in the #{default} layout: agent sessions with their
+          CPU, real memory (footprint), disk and network, and memory pressure. --layout #{CLASSIC} is
+          the panel dashboard. Off a terminal it prints one frame.
+        TEXT
+        registry.cli_blocks.each { |b| instance_exec(&b) }
+        registry.commands.each { |c| command(c.name, &c.block) }
+
+        option :layout, in: layouts, default:, desc: "Dashboard layout: #{CLASSIC} or a view (docs/views.md)"
+        flag :motion, default: true, desc: "Animate meters, changed values and moved rows (AGENTMON_MOTION=0: off)"
+
+        run do
+          engine = Agentmon.engine
+          engine.recording = shell.interactive? # history is written while the dashboard is open
+          Views.motion = options[:motion] && ENV["AGENTMON_MOTION"] != "0"
+          UI.install(engine:, view: Program.view(options[:layout]))
+          dashboard UI::DASHBOARD
+        end
+      end
+    end
+
+    def start(argv = ARGV) = build.start(argv)
+  end
+
+  # After any command, a broken probe, metric or recorder is reported on stderr ("⚠ metric
+  # memory: ..."), so a table with missing columns says why. stdout stays clean for scripts.
+  R2UI::CLI.extension :agentmon_errors do
+    after_run do
+      Agentmon.engine_errors.each { |name, message| shell.err_puts("#{shell.symbol(:warn)} #{name}: #{message}") }
+    end
+  end
+end

data/lib/agentmon/reading.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Agentmon
+  # One sample plus everything derived from it: `reading[:process_rows]`, `reading[:sessions]`.
+  # A metric's value is computed once, the first time it is asked for (metrics may ask for each
+  # other); the Engine asks for all of them before it publishes the reading, so readers on other
+  # threads only look values up.
+  #
+  # Stories land in any order, so a missing or broken metric never stops the others:
+  # `reading[:name]` is nil for a metric nobody registered (its story hasn't merged yet), and a
+  # metric that raises is nil too, with its error in `reading.errors[:name]` (the dashboard's
+  # status bar and the CLI's stderr show them). Consumers treat nil as "not available".
+  #
+  # Tests build one directly, with fixture samples and preset `values:` for metrics a story
+  # consumes but doesn't own:
+  #
+  #   Reading.new(sample, previous: earlier, values: { memory: MemoryView.new(...) })
+  class Reading
+    attr_reader :sample, :previous, :errors
+
+    def initialize(sample, previous: nil, metrics: Agentmon.registry.metrics, states: nil, values: {})
+      @sample = sample
+      @previous = previous
+      @metrics = metrics.to_h { |m| [m.name, m] }
+      @states = states || Hash.new { |h, k| h[k] = {} }
+      @values = values.transform_keys(&:to_sym)
+      @errors = {}
+      @computing = []
+    end
+
+    # Wall time of the sample (epoch seconds).
+    def at = sample.at
+
+    # Seconds between the previous sample and this one (monotonic), nil for the first.
+    def interval = previous && (sample.mono - previous.mono)
+
+    def [](name)
+      name = name.to_sym
+      return @values[name] if @values.key?(name)
+
+      metric = @metrics[name] or return nil
+      raise Error, "metric cycle: #{[*@computing, name].join(" -> ")}" if @computing.include?(name)
+
+      @values[name] = compute(metric)
+    end
+
+    # The focused session id: always nil here; a FocusedReading (lib/agentmon/focus.rb) answers
+    # its session. Code that may get either calls these instead of checking the class.
+    def focus = nil
+
+    # The whole machine's reading (a FocusedReading returns the one it narrows).
+    def unfocused = self
+
+    # True when a metric of that name is registered (or preset).
+    def key?(name) = @values.key?(name.to_sym) || @metrics.key?(name.to_sym)
+
+    # Computes every metric (the Engine calls this once per sample).
+    def evaluate_all
+      @metrics.each_key { |name| self[name] }
+      self
+    end
+
+    private
+
+    def compute(metric)
+      @computing.push(metric.name)
+      metric.block.call(self, @states[metric.name])
+    rescue Error => e
+      raise if e.message.start_with?("metric cycle") # a design bug: fail loudly
+
+      fail_metric(metric, e)
+    rescue StandardError => e
+      fail_metric(metric, e)
+    ensure
+      @computing.pop
+    end
+
+    def fail_metric(metric, error)
+      @errors[metric.name] = "#{error.class}: #{error.message}"
+      nil
+    end
+  end
+end

data/lib/agentmon/recorders/memory.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Memory history: while agentmon records (the interactive dashboard, `agentmon record`), one line
+# every 10 s in the store's `memory` kind, e.g. ~/.local/state/agentmon/memory/2026-10-01.jsonl:
+#
+#   {"t":1790000010.0,"total":17179869184,"used":11811160064,"app":7516192768,"wired":2147483648,
+#    "compressed":2147483648,"cached":3221225472,"free":536870912,"swap_used":1073741824,
+#    "swap_total":2147483648,"compression_ratio":3.1,"swapin_rate":0.0,"swapout_rate":4096.0,
+#    "compression_rate":1572864.0,"decompression_rate":262144.0,"pressure":38.0,"run":"4242-1790000000"}
+#
+# The line is `reading[:memory]` (a MemoryView: sizes in bytes, rates in bytes/s, pressure in
+# percent) without `pressure_trend` (the line's own history is the trend), stamped with the
+# sample's time `t` and the engine's `run`. Nothing is written while memory is unavailable.
+module Agentmon
+  recorder(:memory, every: 10) do |reading, _state|
+    view = reading[:memory]
+    view && { t: reading.at, **view.to_h.except(:pressure_trend) }
+  end
+end