resources

harn resources status gives agents the latest measurements from the optional local supervisor. It reads cached measurements without scanning processes or starting a service. Writer liveness is checked separately.

harn supervisor start --keep-alive
harn resources status
harn resources status --json
harn resources status --processes
harn supervisor stop

Dashboard and managed-workflow startup also ensure the supervisor is running. Use --keep-alive for command-only monitoring that should remain available without a dashboard. Every resource command accepts --root <path>.

Cached status

The supervisor samples every two seconds and atomically replaces .harnery/resources/snapshot.json. Readers share that snapshot. The supervisor also keeps a 15-minute history of machine and process-group totals.

The default status leads with the pressure assessment, then reports CPU usage, available RAM, available disk space, sample age, and measurement scope. JSON includes the assessment in full plus the underlying measurements and their support states. --processes adds up to 20 processes ordered by resident memory, with proven ownership where available. Command lines are excluded from status output.

Agent status includes the same compact summary. Prompt context reports a material change in the assessment, keyed on scope, state, and recommended action, so a change in numbers alone does not repeat a notice. The assessment is advisory and cannot reserve capacity, block work, kill processes, or change coordination state.

A snapshot older than 15 seconds is stale. Missing, malformed, oversized, or unsupported snapshots produce an explicit unavailable result. Unknown data is not zero. The assessment stays unknown when the observer’s published record or the writer cannot be verified, even when recent measurements can still be displayed. Windows-host readings have their own timestamps and expire after 30 seconds.

What sets the pressure state

State comes only from evidence that a shared resource is actually contended:

Dimension	Source	Raises state
Memory and I/O full stalls	Linux PSI memory_full and io_full	Yes
New out-of-memory kill	An increase in the kernel oom_kill counter	Yes
Swap-out rate	/proc/vmstat pswpout as bytes per second	Yes
Direct reclaim	/proc/vmstat pgscan_direct as pages per second	Yes, with another memory signal
Memory available with swap exhausted	Machine totals	Yes
Disk space	Workspace and temporary filesystem capacity	Yes
CPU stalls	Linux PSI cpu some-average	To elevated only
A large process, group, or hook receipt	Attribution findings	No

The last row is the important one. A process holding a gibibyte, an unattributed group holding two, or a heavy hook receipt tells you who is using memory, not that anything is waiting for it. Those findings are carried as contributors so you can see the likely owner, and they can never raise or lower the state. The kernel already reports whether anything is waiting.

Entry needs a streak of hot samples and exit needs a dwell of clear samples, so a state does not flip on one sample and does not clear the instant a reading dips. A sample is clear when no dimension sits at or above its entry threshold; there is no lower exit threshold, so a reading the policy calls normal can never hold a state open. While only the dwell holds a state, the summary says the evidence reads clear and counts down the samples left, rather than reporting contention that the kernel no longer shows. Full I/O stalls need a higher bar and a longer streak than memory stalls, because a virtual disk holds io_full in the twenties through an ordinary checkout. A counter reset or an observer restart starts a new baseline instead of reporting a spurious event. Every change of state is written to the supervisor log as a supervisor.pressure_transition record carrying the reasons that set it, so a past episode can be explained after it clears. A dimension the platform does not expose is reported as unavailable and never read as spare capacity, so a partial platform cannot produce a falsely healthy answer. In WSL the Windows host is assessed separately and can only raise the combined state, never mask the guest.

Guidance is given per kind of work, because the answer differs: reads and small edits, CPU-heavy builds and tests, memory-heavy browser and QA captures, and storage-heavy writes. It never states a safe number of agents, and it names an owner only when that finding’s attribution is exact.

Every threshold lives in one policy object that is included in a diagnostic bundle’s threshold digest, so tuning any value invalidates a frozen replay rather than silently changing its expected result.

Measurements and platforms

The Resources dashboard includes live charts beside CPU, memory, one-minute load average, and process count. Choose a shared 1-, 5-, or 15-minute lookback; the browser remembers the selection. Hover over a chart or focus it and use the arrow keys to inspect readings. Charts use actual sample times, leave gaps where readings are missing, and include the latest measurement shown on the card. Load history begins when a supervisor with load-history support starts.

Measurement	Linux / WSL	macOS	Windows
CPU utilization	Consecutive kernel counters	Consecutive OS counters	Consecutive OS counters
RAM	Available memory from procfs	Available memory estimated from free, inactive, and speculative pages	OS free physical memory
Swap	Kernel totals	Native swap totals	Pagefile totals when available
Workspace and temporary disk space	Filesystem capacity	Filesystem capacity	Filesystem capacity
CPU, memory, I/O stall averages	Linux PSI when exposed	Explicitly unsupported	Explicitly unsupported
Recent out-of-memory kills	Kernel counter changes	Explicitly unsupported	Explicitly unsupported
Swap-out, swap-in, direct reclaim, major-fault rates	/proc/vmstat counter deltas	Explicitly unsupported	Explicitly unsupported
Disk read/write rates	Whole-device counter deltas	Explicitly unsupported	Explicitly unsupported
Process ownership	Validated PID ancestry or exact bridge identity	Explicitly unavailable	Explicitly unavailable

Linux PSI reports time during which tasks stalled on a resource, averaged over 10, 60, and 300 seconds. The cpu, memory, and io fields contain some averages: at least one task was waiting. The separate memory_full and io_full fields measure when all non-idle tasks were waiting simultaneously. System-wide CPU full is undefined and is not collected. Status prints full-stall windows and whether the 10-second average is rising or falling relative to the minute.

The oom section reads the kernel’s oom_kill counter. The first sample reports the historical total and leaves recent kills unknown. Later samples expose the increase and age of the last observed kill. A new kill holds a critical state for one minute; the finding history retains the incident afterward. Counter resets or failed reads restart the baseline. This does not identify victims or grant permission to stop work. High memory occupancy and swap occupancy on their own are capacity readings, not proof that tasks are stalled, and they do not set the state. Swap becomes a state-bearing signal only through its measured out rate, or when available memory is exhausted at the same time as swap.

Disk I/O rates exclude partitions and stacked devices that would double-count the underlying disks. Initial or reset counters produce unknown rates until a second usable sample arrives. Disk capacity probes inspect only the workspace and temporary filesystems; they never walk directory contents.

A WSL snapshot describes the Linux environment. It includes a separate Windows host section when Windows interop and CIM providers are available. That section reports CPU, memory, pagefiles, and fixed-volume capacity. The Windows probe is cached for 15 seconds, including failures. Supervisor probes run in the background and coalesce while one query is in flight, so WSL sampling does not wait for Windows. Pending host measurements are explicit. It does not allocate shared Windows processes to individual WSL tasks. A failed host query leaves WSL measurements usable and marks the host section unavailable.

Native macOS and Windows snapshots are partial because process attribution and Linux PSI are unavailable. Their CPU, memory, and disk measurements remain usable. Native command probes are read-only, bounded, and hidden on Windows. The supervisor starts through its Node or Bun runtime on all supported platforms. Cgroup limits and GPU usage are not collected.

One-time snapshot

harn resources snapshot

This command collects one fresh snapshot without starting the supervisor. Memory, load, and disk capacity are available immediately. Current CPU utilization and I/O rates need consecutive samples, so the first sample reports them as null. Linux process records include bounded, redacted command excerpts; prefer cached status for routine agent decisions.