agentmon 0.1.0

data/lib/agentmon/commands/sessions.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+
+# `agentmon sessions`: the agent sessions running now (Claude Code, Codex, their desktop apps),
+# busiest first, with what each has cost over its life.
+#
+#   agentmon sessions          a table (boxed on a terminal, plain aligned columns in a pipe)
+#   agentmon sessions --all    also sessions that ended in the last 15 minutes
+#   agentmon sessions --json   one JSON object per line, raw units (bytes, seconds, epoch), for scripts
+#
+#   Session            Processes     CPU  Footprint  Peak  CPU time  Written      Age
+#   claude 200 · repo          4  150.0%       628M  628M     15.6s     5.0M  56m 42s
+#
+# CPU is percent of one core now; Footprint is real memory now and Peak the largest seen; CPU time
+# and Written are lifetime totals (Written is a lower bound: see docs/design.md). Sizes are binary
+# (1M = 1024²), as in the dashboard. Age runs from the session's start to now, or to its end.
+module Agentmon
+  module Commands
+    module SessionList
+      HEADERS = ["Session", "Processes", "CPU", "Footprint", "Peak", "CPU time", "Written", "Age"].freeze
+      RIGHT = (1..7).to_h { |i| [i, :right] }.freeze
+      EMPTY = "No agent sessions running."
+
+      module_function
+
+      # Alive sessions (and ended ones with `all`), alive first, then by CPU, then by root pid.
+      def select(ledger, all: false)
+        ledger ||= [] # session_ledger failed or isn't there this sample (the error goes to stderr)
+        ledger = ledger.select(&:alive?) unless all
+        ledger.sort_by { |s| [s.alive? ? 0 : 1, -(s.cpu || 0.0), s.root_pid] }
+      end
+
+      def cells(session, now)
+        f = R2UI::Format
+        human = R2UI::CLI::Ext::HumanFormat
+        label = session.alive? ? session.label : "#{session.label} · ended #{human.duration(now - session.ended_at)} ago"
+        [label, session.processes.to_s, f.call(:percent, session.cpu), f.call(:bytes, session.footprint),
+         f.call(:bytes, session.peak_footprint), session.cpu_seconds && human.duration(session.cpu_seconds),
+         f.call(:bytes, session.bytes_written), human.duration(session.duration)].map(&:to_s)
+      end
+
+      def json(session) = JSON.generate(session.to_record)
+
+      # Narrowest a label is cut to, however many other columns there are: on a very narrow
+      # terminal (or a pipe without COLUMNS, 80) the table overflows rather than lose the label.
+      MIN_LABEL = 20
+
+      # `rows` (Arrays of Strings) with column `column` cut at a word boundary ("·", " ", ...) so
+      # the table r2ui draws fits `width`: r2ui's plain table never cuts and its boxed one wraps
+      # cells, so a long session name would overflow a pipe or wrap mid-word on a terminal.
+      # `boxed` is the terminal table: each cell padded by one space each side plus n+1 borders;
+      # plain columns are joined by two spaces. A cell's part matching `keep` (at its end) is kept
+      # whole and the rest cut. Used by sessions, footprint and top.
+      def fit(rows, headers, width:, boxed:, column: 0, keep: nil)
+        return rows if rows.empty?
+
+        measure = ->(text) { R2UI::CLI::Ext::Tabulate.width(text.to_s) }
+        others = headers.each_index.sum do |i|
+          i == column ? 0 : [measure[headers[i]], *rows.map { |r| measure[r[i]] }].max
+        end
+        n = headers.size
+        overhead = boxed ? (3 * n) + 1 : 2 * (n - 1)
+        room = [width - others - overhead, MIN_LABEL, measure[headers[column]]].max
+        rows.map do |row|
+          text = row[column].to_s
+          tail = (keep && text[keep]).to_s
+          head = text.delete_suffix(tail)
+          row.dup.tap { |r| r[column] = Views::Widgets.cut(head, [room - measure[tail], MIN_LABEL].max) + tail }
+        end
+      end
+
+      # The " · ended 3m ago" an ended session's label ends in: never cut.
+      ENDED = / · ended [^·]* ago\z/
+    end
+  end
+
+  command :sessions do
+    summary "Agent sessions now, with CPU, real memory and lifetime totals"
+    flag :all, short: "a", desc: "Also sessions that ended in the last 15 minutes"
+    flag :json, desc: "One JSON object per session per line, in raw units"
+
+    run do
+      list = Commands::SessionList
+      reading = Agentmon.engine.current
+      sessions = list.select(reading[:session_ledger], all: options[:all])
+      if options[:json]
+        sessions.each { |s| shell.puts(list.json(s)) }
+      elsif sessions.empty?
+        shell.puts(list::EMPTY)
+      else
+        rows = list.fit(sessions.map { |s| list.cells(s, reading.at) }, list::HEADERS, width: shell.width,
+                                                                                      boxed: shell.live?, keep: list::ENDED)
+        table(rows, headers: list::HEADERS, align: list::RIGHT)
+      end
+    end
+  end
+end

data/lib/agentmon/commands/top.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# `agentmon top`: the processes of agent sessions, busiest first, with real memory and disk I/O.
+#
+#   agentmon top              on a terminal: redrawn in place every 2 s until ctrl+c
+#   agentmon top --once       one table and exit (plain aligned columns in a pipe, for scripts)
+#   agentmon top -a -n 5 --sort footprint
+#   agentmon top --session repo   only one session (its id, root pid or part of its label);
+#                                 no match, or several, exits 1 and lists the sessions
+#
+#   PID    Name    Session              CPU  Footprint  Resident   Read  Write
+#   4242   claude  claude 4242 · repo  12.5%       512M      600M  1.0K/s     0B/s
+#
+# Sizes are binary (1M = 1024²), the same units the dashboard shows. An empty cell is unknown:
+# footprint and disk rates of other users' processes can't be read without root.
+module Agentmon
+  module Commands
+    module Top
+      HEADERS = %w[PID Name Session CPU Footprint Resident Read Write].freeze
+      RIGHT = [0, 3, 4, 5, 6, 7].freeze
+      SESSION = 2 # the column cut to fit the width (a session label can be a long human name)
+      # Seconds between the live loop's own redraws (which surface a dead ticker's error).
+      CHECK_EVERY = 1
+      SORTS = { "cpu" => :cpu, "footprint" => :footprint, "resident" => :resident, "read" => :read_rate,
+                "write" => :write_rate }.freeze
+
+      module_function
+
+      def select(rows, sort: "cpu", limit: 20, all: false)
+        key = SORTS.fetch(sort)
+        rows ||= [] # process_rows failed this sample: an empty table (the error goes to stderr)
+        rows = rows.select(&:session) unless all
+        rows.sort_by { |r| [-(r.public_send(key) || -1).to_f, r.pid] }.first(limit)
+      end
+
+      def cells(row)
+        f = R2UI::Format
+        [row.pid.to_s, row.name, row.session.to_s, f.call(:percent, row.cpu), f.call(:bytes, row.footprint),
+         f.call(:bytes, row.resident), f.call(:bytes_per_sec, row.read_rate), f.call(:bytes_per_sec, row.write_rate)]
+      end
+
+      # Plain aligned lines (header first), cut to `width`: the live view.
+      def lines(rows, width)
+        body = SessionList.fit(rows.map { |r| cells(r) }, HEADERS, width:, boxed: false, column: SESSION)
+        table = [HEADERS, *body]
+        widths = table.transpose.map { |col| col.map(&:length).max }
+        table.map do |cells|
+          cells.each_with_index.map { |c, i| RIGHT.include?(i) ? c.rjust(widths[i]) : c.ljust(widths[i]) }
+               .join("  ").rstrip[0, width]
+        end
+      end
+    end
+  end
+
+  command :top do
+    summary "Agent processes by CPU, with footprint and disk I/O"
+    flag :once, desc: "Print one table and exit"
+    flag :all, short: "a", desc: "Every process, not only agent sessions"
+    option :limit, :integer, short: "n", default: 20, desc: "Rows to show"
+    option :sort, default: "cpu", in: Commands::Top::SORTS.keys, desc: "Sort by"
+    option :session, desc: "Only one session's processes: its id, root pid or part of its label"
+
+    run do
+      top = Commands::Top
+      pick = ->(reading) { top.select(reading[:process_rows], sort: options[:sort], limit: options[:limit], all: options[:all]) }
+      engine = Agentmon.engine
+      if (query = options[:session])
+        sessions = engine.current(focused: false)[:session_ledger]&.select(&:alive?) || []
+        found = Focus.find(sessions, query)
+        listing = ->(list) { list.map { |s| "  #{s.label}  (#{s.id})" }.join("\n") }
+        abort!("no session matches #{query.inspect}. Sessions:\n#{listing.call(sessions)}") if found.empty?
+        abort!("#{query.inspect} matches #{found.size} sessions:\n#{listing.call(found)}") if found.size > 1
+        engine.focus = found.first.id
+      end
+      if options[:once] || !shell.live?
+        cells = Commands::SessionList.fit(pick.call(engine.current).map { |r| top.cells(r) }, top::HEADERS,
+                                          width: shell.width, boxed: shell.live?, column: top::SESSION)
+        table(cells, headers: top::HEADERS, align: top::RIGHT.to_h { |i| [i, :right] })
+      else
+        live = R2UI::CLI::Live.new(shell, fps: 2) { top.lines(pick.call(engine.current), shell.width).join("\n") }
+        # `refresh` redraws on this thread: if the ticker died on a raising view, it raises that
+        # error here, Live restores the terminal, and the command fails instead of freezing.
+        live.run { loop { sleep top::CHECK_EVERY; live.refresh } }
+      end
+    end
+  end
+end

data/lib/agentmon/commands/tree.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# `agentmon tree [SESSION]`: each agent session's process tree, the session label as root, each
+# process as "pid name · footprint · CPU %".
+#
+#   agentmon tree             every live session
+#   agentmon tree repo        one session, by id, root pid or label substring (any case)
+#
+#   claude 200 · repo
+#   └── 200 claude · 512M · 100.0%
+#       ├── 201 node · 100M · 50.0%
+#       └── 202 zsh · 8.0M · 0.0%
+#           └── 203 git · 8.0M · 0.0%
+#
+# A SESSION that matches nothing, or more than one session, exits 1 and lists the candidates.
+# "n/a" is unknown: other users' processes have no readable footprint without root. Sizes are
+# binary (1M = 1024²). Plain lines in a pipe, so `agentmon tree | grep node` works.
+module Agentmon
+  module Commands
+    module SessionTree
+      NONE = "No agent sessions running."
+
+      module_function
+
+      # The live sessions from a reading, root pid order; [] while `sessions` is unavailable.
+      def sessions(reading)
+        map = reading[:sessions]
+        map ? map.sessions.sort_by(&:root_pid) : []
+      end
+
+      # Sessions a SESSION argument names: an exact id or root pid first, else label substrings.
+      def find(sessions, query)
+        exact = sessions.select { |s| s.id == query || s.root_pid.to_s == query }
+        return exact unless exact.empty?
+
+        sessions.select { |s| s.label.downcase.include?(query.downcase) }
+      end
+
+      # { "pid name · footprint · cpu" => children } for one session's processes, nested by ppid.
+      # Members whose parent isn't in the session (normally just the root) are the top level.
+      def branches(session, rows)
+        members = (rows || []).select { |r| r.session_id == session.id }
+        pids = members.to_h { |r| [r.pid, true] }
+        kids = members.group_by(&:ppid)
+        top = members.reject { |r| pids[r.ppid] }
+        nest(top, kids, {})
+      end
+
+      def nest(rows, kids, seen)
+        rows.sort_by(&:pid).each_with_object({}) do |row, tree|
+          next if seen[row.pid] # a ppid cycle (pid reuse between ps lines) would never end
+
+          seen[row.pid] = true
+          below = nest(kids.fetch(row.pid, []), kids, seen)
+          tree[label(row)] = below.empty? ? nil : below
+        end
+      end
+
+      def label(row)
+        f = R2UI::Format
+        footprint = f.call(:bytes, row.footprint)
+        cpu = f.call(:percent, row.cpu)
+        "#{row.pid} #{row.name} · #{footprint.empty? ? 'n/a' : footprint} · #{cpu.empty? ? 'n/a' : cpu}"
+      end
+
+      def listing(sessions) = sessions.map { |s| "  #{s.label}  (#{s.id})" }.join("\n")
+    end
+  end
+
+  command :tree do
+    summary "Process tree of each agent session, with footprint and CPU"
+    argument :session, required: false, desc: "Session id, root pid or label substring"
+
+    run do
+      st = Commands::SessionTree
+      reading = Agentmon.engine.current
+      sessions = st.sessions(reading)
+      query = args[:session]
+      if query
+        abort!("no session matches #{query.inspect}: #{st::NONE}") if sessions.empty?
+        found = st.find(sessions, query)
+        abort!("no session matches #{query.inspect}. Sessions:\n#{st.listing(sessions)}") if found.empty?
+        abort!("#{query.inspect} matches #{found.size} sessions:\n#{st.listing(found)}") if found.size > 1
+        sessions = found
+      end
+      if sessions.empty?
+        say st::NONE
+      else
+        sessions.each_with_index do |s, i|
+          say if i.positive?
+          tree(s.label, st.branches(s, reading[:process_rows]))
+        end
+      end
+    end
+  end
+end

data/lib/agentmon/darwin.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+require "fiddle"
+
+module Agentmon
+  # macOS kernel data through Fiddle, without subprocesses: per-process resource usage
+  # (proc_pid_rusage, RUSAGE_INFO_V4), process start time plus fault and scheduling counters
+  # (proc_pidinfo PROC_PIDTASKALLINFO; PROC_PIDTBSDINFO for the start time alone), open file paths
+  # (PROC_PIDLISTFDS + proc_pidfdinfo) and the Mach clock (mach_timebase_info).
+  #
+  # Units: CPU times come from the kernel in Mach absolute-time ticks. On Intel a tick is 1 ns; on
+  # Apple Silicon it is 125/3 ns (41.67 ns), so ticks are always converted with the timebase and
+  # everything this module returns is in seconds (Float) or bytes (Integer).
+  #
+  # Other users' processes (root daemons) can't be read without root: the kernel answers EPERM and
+  # the readers here return nil. Callers fall back to what ps reports.
+  module Darwin
+    RUSAGE_INFO_V4 = 4
+    # struct rusage_info_v4: a 16-byte uuid, then 35 uint64 fields (ri_user_time ..
+    # ri_runnable_time) = 296 bytes. v5 and v6 append fields; v4 is what we ask for.
+    RUSAGE_FIELDS = 35
+    RUSAGE_SIZE = 16 + (8 * RUSAGE_FIELDS)
+    PROC_PIDTASKALLINFO = 2
+    PROC_PIDTBSDINFO = 3
+    # struct proc_bsdinfo is 136 bytes; pbi_start_tvsec/usec are its last two uint64 fields.
+    BSDINFO_SIZE = 136
+    BSDINFO_START = 120
+    # struct proc_taskallinfo = proc_bsdinfo (136) + proc_taskinfo (96): six uint64s
+    # (pti_virtual_size .. pti_threads_system), then twelve int32s (pti_policy .. pti_priority).
+    TASKINFO_SIZE = 96
+    TASKALLINFO_SIZE = BSDINFO_SIZE + TASKINFO_SIZE
+    # Indexes of the int32 fields after the six uint64s (xnu bsd/sys/proc_info.h).
+    TASK_FIELDS = { faults: 1, pageins: 2, cow_faults: 3, csw: 8, threadnum: 9, numrunning: 10 }.freeze
+
+    # Indexes of the uint64 fields after the uuid (xnu bsd/sys/resource.h).
+    FIELDS = {
+      user_time: 0, system_time: 1, pageins: 4, wired_size: 5, resident_size: 6, phys_footprint: 7,
+      proc_start_abstime: 8, child_user_time: 10, child_system_time: 11, diskio_bytesread: 16,
+      diskio_byteswritten: 17, lifetime_max_phys_footprint: 28, runnable_time: 34
+    }.freeze
+
+    # Open files (bsd/sys/proc_info.h). proc_pidinfo(PROC_PIDLISTFDS) fills struct proc_fdinfo
+    # entries {int32 proc_fd; uint32 proc_fdtype}; proc_pidfdinfo(PROC_PIDFDVNODEPATHINFO) fills a
+    # struct vnode_fdinfowithpath: proc_fileinfo (24 bytes) + vnode_info (vinfo_stat 136 + vi_type,
+    # vi_pad, vi_fsid = 152 bytes), then vip_path[MAXPATHLEN = 1024], NUL-terminated, at 176.
+    PROC_PIDLISTFDS = 1
+    PROC_PIDFDVNODEPATHINFO = 2
+    PROX_FDTYPE_VNODE = 1
+    FDINFO_SIZE = 8
+    VNODE_PATH_OFFSET = 24 + 152
+    VNODE_PATH_SIZE = VNODE_PATH_OFFSET + 1024
+
+    EPERM = 1
+    ESRCH = 3
+
+    # One process's counters, converted: seconds and bytes. Cumulative since the process started.
+    Rusage = Data.define(
+      :cpu_time,        # user + system CPU seconds (Float)
+      :child_cpu_time,  # user + system CPU seconds of children it has reaped (Float)
+      :resident,        # resident set size, bytes
+      :footprint,       # physical footprint (Activity Monitor's "Memory"), bytes
+      :peak_footprint,  # lifetime maximum footprint, bytes
+      :disk_read,       # bytes read from disk
+      :disk_written,    # bytes written to disk
+      :start_ticks,     # start time in Mach ticks: with the pid, identifies the process across pid reuse
+      :wired,           # wired bytes
+      :pageins,         # count of faults that read from disk
+      :runnable_time    # seconds runnable (running or waiting for a CPU)
+    ) do
+      def initialize(wired: nil, pageins: nil, runnable_time: nil, **) = super
+    end
+
+    # proc_taskallinfo, decoded: start time plus the task's fault and scheduling counters.
+    # Counts are the kernel's 32-bit counters, read unsigned (they wrap at 2**32).
+    TaskInfo = Data.define(
+      :started_at,       # epoch seconds (Float)
+      :faults,           # page faults, any kind
+      :cow_faults,       # copy-on-write faults
+      :context_switches,
+      :threads,          # threads now
+      :running_threads   # threads running now
+    )
+
+    class << self
+      def available? = RUBY_PLATFORM.include?("darwin")
+
+      # Rusage for `pid`, or nil when it can't be read (EPERM for other users' processes, ESRCH
+      # when it has exited). `errno` after a nil says which.
+      def rusage(pid)
+        buffer = Fiddle::Pointer.malloc(RUSAGE_SIZE, Fiddle::RUBY_FREE)
+        return fail_with(Fiddle.last_error) unless functions[:rusage].call(pid, RUSAGE_INFO_V4, buffer).zero?
+
+        Thread.current[:agentmon_errno] = 0
+        decode_rusage_bytes(buffer[0, RUSAGE_SIZE])
+      end
+
+      # Decodes a whole rusage_info_v4 as the kernel wrote it (uuid included, native-endian
+      # uint64s; every Mac agentmon runs on is little-endian). Public for tests.
+      def decode_rusage_bytes(bytes) = decode_rusage(bytes.byteslice(16, RUSAGE_SIZE - 16).unpack("Q<*"))
+
+      # Decodes the uint64 fields of a rusage_info_v4 (after the uuid), by FIELDS index.
+      def decode_rusage(values)
+        f = ->(name) { values.fetch(FIELDS.fetch(name)) }
+        Rusage.new(
+          cpu_time: ticks_to_seconds(f[:user_time] + f[:system_time]),
+          child_cpu_time: ticks_to_seconds(f[:child_user_time] + f[:child_system_time]),
+          resident: f[:resident_size],
+          footprint: f[:phys_footprint],
+          peak_footprint: f[:lifetime_max_phys_footprint],
+          disk_read: f[:diskio_bytesread],
+          disk_written: f[:diskio_byteswritten],
+          start_ticks: f[:proc_start_abstime],
+          wired: f[:wired_size],
+          pageins: f[:pageins],
+          # Mach ticks, like the CPU times (checked: 30 busy processes on 10 cores for 2 s report
+          # ~2.0 s runnable as ticks, 0.05 s if they were ns; it counts time on a CPU too).
+          runnable_time: ticks_to_seconds(f[:runnable_time])
+        )
+      end
+
+      # Wall-clock start time of `pid` as epoch seconds (Float), or nil when unreadable.
+      def started_at(pid)
+        buffer = Fiddle::Pointer.malloc(BSDINFO_SIZE, Fiddle::RUBY_FREE)
+        return fail_with(Fiddle.last_error) unless functions[:pidinfo].call(pid, PROC_PIDTBSDINFO, 0, buffer, BSDINFO_SIZE) == BSDINFO_SIZE
+
+        decode_start(buffer[0, BSDINFO_SIZE])
+      end
+
+      # Start time plus fault and scheduling counters in one proc_pidinfo(PROC_PIDTASKALLINFO)
+      # call (the same cost as PROC_PIDTBSDINFO alone), or nil when unreadable.
+      def task_info(pid)
+        buffer = Fiddle::Pointer.malloc(TASKALLINFO_SIZE, Fiddle::RUBY_FREE)
+        unless functions[:pidinfo].call(pid, PROC_PIDTASKALLINFO, 0, buffer, TASKALLINFO_SIZE) == TASKALLINFO_SIZE
+          return fail_with(Fiddle.last_error)
+        end
+
+        Thread.current[:agentmon_errno] = 0
+        decode_task_info_bytes(buffer[0, TASKALLINFO_SIZE])
+      end
+
+      # Decodes a whole proc_taskallinfo as the kernel wrote it. Public for tests.
+      def decode_task_info_bytes(bytes)
+        counts = bytes.byteslice(BSDINFO_SIZE + 48, 48).unpack("L<12") # unsigned: wrapped counters stay positive
+        c = ->(name) { counts.fetch(TASK_FIELDS.fetch(name)) }
+        TaskInfo.new(started_at: decode_start(bytes), faults: c[:faults], cow_faults: c[:cow_faults],
+                     context_switches: c[:csw], threads: c[:threadnum], running_threads: c[:numrunning])
+      end
+
+      # Paths (Strings) of `pid`'s open vnode files (regular files, directories, devices), or nil
+      # when its descriptors can't be listed (another user's process, exited). One
+      # proc_pidinfo(PROC_PIDLISTFDS) call plus one proc_pidfdinfo per vnode descriptor; a
+      # descriptor closed in between is skipped.
+      def open_paths(pid)
+        size = functions[:pidinfo].call(pid, PROC_PIDLISTFDS, 0, nil, 0)
+        return fail_with(Fiddle.last_error) unless size.positive?
+
+        size += 32 * FDINFO_SIZE # room for descriptors opened between the two calls
+        list = Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+        filled = functions[:pidinfo].call(pid, PROC_PIDLISTFDS, 0, list, size)
+        return fail_with(Fiddle.last_error) unless filled.positive?
+
+        Thread.current[:agentmon_errno] = 0
+        buffer = Fiddle::Pointer.malloc(VNODE_PATH_SIZE, Fiddle::RUBY_FREE)
+        decode_fdinfo_list(list[0, filled]).filter_map do |fd, type|
+          next unless type == PROX_FDTYPE_VNODE
+          next unless functions[:pidfdinfo].call(pid, fd, PROC_PIDFDVNODEPATHINFO, buffer, VNODE_PATH_SIZE) == VNODE_PATH_SIZE
+
+          path = decode_vnode_path(buffer[0, VNODE_PATH_SIZE])
+          path unless path.empty?
+        end
+      end
+
+      # [[fd, fdtype], ...] from the struct proc_fdinfo array PROC_PIDLISTFDS wrote. Public for tests.
+      def decode_fdinfo_list(bytes)
+        bytes.byteslice(0, bytes.bytesize - (bytes.bytesize % FDINFO_SIZE)).unpack("l<L<" * (bytes.bytesize / FDINFO_SIZE))
+             .each_slice(2).to_a
+      end
+
+      # vip_path of a struct vnode_fdinfowithpath, as a UTF-8 String ("" when empty). Public for tests.
+      def decode_vnode_path(bytes)
+        bytes.byteslice(VNODE_PATH_OFFSET, 1024).to_s.unpack1("Z*").force_encoding(Encoding::UTF_8).scrub
+      end
+
+      # errno of the last failed read on this thread (EPERM, ESRCH, ...), 0 after a success.
+      def errno = Thread.current[:agentmon_errno] || 0
+
+      # Nanoseconds per Mach tick (Rational): 1 on Intel, 125/3 on Apple Silicon.
+      def ns_per_tick
+        @ns_per_tick ||= begin
+          buffer = Fiddle::Pointer.malloc(8, Fiddle::RUBY_FREE)
+          functions[:timebase].call(buffer)
+          numer, denom = buffer[0, 8].unpack("LL")
+          Rational(numer, denom)
+        end
+      end
+
+      # Overrides the timebase (tests decode fixtures recorded on another machine). nil resets.
+      attr_writer :ns_per_tick
+
+      def ticks_to_seconds(ticks) = (ticks * ns_per_tick).fdiv(1_000_000_000)
+
+      private
+
+      # pbi_start_tvsec/usec from the head of a proc_bsdinfo (or proc_taskallinfo).
+      def decode_start(bytes)
+        sec, usec = bytes.byteslice(BSDINFO_START, 16).unpack("Q<Q<")
+        sec + (usec / 1_000_000.0)
+      end
+
+      def fail_with(errno)
+        Thread.current[:agentmon_errno] = errno
+        nil
+      end
+
+      def functions
+        @functions ||= begin
+          lib = Fiddle.dlopen(nil) # libSystem: libproc and the Mach clock are in the default namespace
+          uint64 = -Fiddle::TYPE_LONG_LONG
+          {
+            rusage: Fiddle::Function.new(lib["proc_pid_rusage"], [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP],
+                                         Fiddle::TYPE_INT),
+            pidinfo: Fiddle::Function.new(lib["proc_pidinfo"],
+                                          [Fiddle::TYPE_INT, Fiddle::TYPE_INT, uint64, Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT],
+                                          Fiddle::TYPE_INT),
+            pidfdinfo: Fiddle::Function.new(lib["proc_pidfdinfo"],
+                                            [Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_INT, Fiddle::TYPE_VOIDP,
+                                             Fiddle::TYPE_INT],
+                                            Fiddle::TYPE_INT),
+            timebase: Fiddle::Function.new(lib["mach_timebase_info"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT)
+          }
+        end
+      end
+    end
+  end
+end

data/lib/agentmon/engine.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Agentmon
+  # Sampler -> Reading (metrics) -> Store (recorders), one tick at a time, shared by everything
+  # that shows data: the dashboard's resources (each r2ui feed thread calls `current`), and the CLI
+  # commands. `current` samples at most once per `max_age`, so three panels refreshing every two
+  # seconds cost one sample, not three.
+  #
+  # The first call takes two samples PRIME_GAP apart: CPU % and disk rates are deltas, so the very
+  # first frame or `agentmon top --once` already has them.
+  #
+  # Metrics and recorders get a state Hash kept for this engine's life (one per metric, one per
+  # recorder), so nothing needs module-level state and two engines (tests) never share it.
+  class Engine
+    PRIME_GAP = 0.5
+
+    attr_reader :interval, :store, :run_id
+    attr_accessor :recording
+
+    def initialize(sampler: Sampler.new, registry: Agentmon.registry, store: nil, recording: false, interval: 2.0,
+                   prime_gap: PRIME_GAP, clock: Clock)
+      @sampler = sampler
+      @registry = registry
+      @store = store
+      @recording = recording
+      @interval = interval
+      @prime_gap = prime_gap
+      @clock = clock
+      @lock = Mutex.new
+      @states = Hash.new { |h, k| h[k] = {} } # metric name => state; [:recorder, name] => state
+      @recorded_at = {}
+      @recorder_errors = {}
+      @run_id = "#{Process.pid}-#{clock.now.to_i}"
+    end
+
+    # The latest Reading, sampling first if it's older than `max_age` seconds. While a session is
+    # focused it is a FocusedReading narrowed to it (lib/agentmon/focus.rb); `focused: false`
+    # returns the whole machine regardless.
+    def current(max_age: interval * 0.75, focused: true)
+      @lock.synchronize do
+        if @reading.nil?
+          tick!
+          sleep(@prime_gap) if @prime_gap.positive?
+          tick!
+        elsif @clock.mono - @ticked_at >= max_age
+          tick!
+        end
+        focused ? focused_reading : @reading
+      end
+    end
+
+    # The focused session's id (Session#id / ProcessRow#session_id), nil when unfocused.
+    def focus = @focus
+
+    # Focuses every reader of `current` on one session; nil clears. Takes effect on each panel's
+    # next feed refresh. Recorders and `errors` always see the whole machine.
+    def focus=(session_id)
+      @lock.synchronize { @focus = session_id }
+    end
+
+    # The focused Session from the ledger (alive or recently ended), or nil when nothing is
+    # focused or the session has left the ledger.
+    def focused_session
+      id = focus or return nil
+      current(focused: false)[:session_ledger]&.find { |s| s.id == id }
+    end
+
+    # Samples now (callers hold no lock: use `current` from threads).
+    def tick!
+      sample = @sampler.sample
+      reading = Reading.new(sample, previous: @reading&.sample, metrics: @registry.metrics, states: @states)
+      reading.evaluate_all
+      @ticked_at = @clock.mono
+      record(reading) if @recording && @store
+      @reading = reading
+    end
+
+    # What's broken right now: { "probe cwd" => "Errno::ENOENT: ...", "metric memory" => ...,
+    # "recorder sessions" => ... } from the latest sample's probes, the latest reading's metrics and
+    # the recorders' last runs. The dashboard's status bar and the CLI's stderr show it.
+    def errors
+      reading = @reading
+      found = {}
+      reading&.sample&.errors&.each { |name, message| found["probe #{name}"] = message }
+      reading&.errors&.each { |name, message| found["metric #{name}"] = message }
+      @recorder_errors.each { |name, message| found["recorder #{name}"] = message }
+      found
+    end
+
+    private
+
+    # The latest reading narrowed to the focus, built once per (reading, focus) under the lock.
+    def focused_reading
+      return @reading unless @focus
+
+      @focused = nil unless @focused&.unfocused.equal?(@reading) && @focused.focus == @focus
+      @focused ||= Focus.apply(@reading, @focus)
+    end
+
+    def record(reading)
+      @registry.recorders.each do |recorder|
+        last = @recorded_at[recorder.name]
+        next if last && @ticked_at - last < recorder.every
+
+        @recorded_at[recorder.name] = @ticked_at
+        rows = recorder.block.call(reading, @states[[:recorder, recorder.name]])
+        rows = [rows] if rows.is_a?(Hash) # Array(hash) would split it into pairs
+        Array(rows).each { |row| @store.append(recorder.name, row.merge(run: run_id)) }
+        @recorder_errors.delete(recorder.name)
+      rescue StandardError => e
+        @recorder_errors[recorder.name] = "#{e.class}: #{e.message}"
+      end
+    end
+  end
+end