agent-usage-manager 0.2.5__tar.gz → 0.3.0__tar.gz

{agent_usage_manager-0.2.5 → agent_usage_manager-0.3.0}/.gitignore

@@ -4,6 +4,7 @@ __pycache__/
 venv/
 .DS_Store
 agents.local.yaml
+agent_usage_manager/agents.yaml
 dist/
 build/
 *.egg-info/

agent_usage_manager-0.3.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+Notable changes to `agent-usage-manager` are recorded here. GitHub Releases
+remain the source for release artifacts.
+
+## Unreleased
+
+## 0.3.0 - 2026-09-13
+
+### Added
+
+- Compact resource triage with CPU/memory sorting, runtime and warning filters,
+  process search, and an optional inspector on desktop and phone layouts.
+- Measured warning evidence and CPU/RSS history. Saved warning links preserve
+  the first observation after clearance, with at most 100 warnings retained
+  in memory for up to 48 hours; restart clears them.
+- Structured alert fields for a plain-language title, exact process identity,
+  and an optional inspection URL configured with `alerts.dashboard_url`.
+- Reviewed process-tree revisions and explicit captured, signaled, skipped,
+  stopped, and surviving process identities in stop results and the action log.
+
+### Changed
+
+- API v2 uses one shared three-second sampler, reports stale collection as
+  unavailable, and exposes runtime, instance, warning, and delivery metadata.
+- Actionable stop requests require the exact `create_time` from the displayed
+  row. The dashboard also checks the reviewed tree revision before signaling.
+- Stop review stays bound to the child details actually displayed, including
+  while text selection defers a refresh; changed or unavailable scope disables it.
+- Failed alert commands retry while the condition persists, with visible
+  delivery state and a bounded three-attempt limit.
+- Runtime-wide short-lived exits are separated from proven launchd service
+  restart evidence. Process labels and working directories remain navigation
+  hints rather than claims about task identity or progress.
+- Dashboard HTML requires cache revalidation after an upgrade. The standalone
+  home link stays within the local AUM installation.
+- Reworked the README into a concise front door and moved operator detail into
+  `docs/reference.md`.
+- Added a security policy, private-reporting path, contribution guide, and
+  privacy-aware bug report form.
+- Added current changelog, documentation, and security links to package metadata.
+- Improved the dashboard at mid-width and phone sizes; clipboard denial now
+  fails visibly and leaves the stop command selected for manual copy.
+
+### Security and privacy
+
+- Stopped tracking the maintainer's operational `agents.yaml`. The current
+  source tree keeps that file local and Git-ignored while future releases
+  continue to ship only the sanitized `agents.default.yaml`.
+- Removed identifying dashboard captures from the current source tree.
+
+### Upgrade notes
+
+- API clients that stop processes must send the exact `create_time` returned by
+  `/api/agents`; actionable requests without it return HTTP 428. Use the
+  `tree_revision` returned by `/api/tree/{pid}` to reject a changed reviewed
+  scope with HTTP 409 before any signal. Refresh an open dashboard after upgrade.
+- Warning history is temporary. A retention deadline is a maximum, and the
+  100-warning cap or a restart can remove an observation earlier.
+
+## 0.2.6 - 2026-08-22
+
+### Fixed
+
+- The wheel and sdist now exclude the maintainer's operational configuration
+  and ship `agents.default.yaml` as the clean fallback.
+- Removed a maintainer-specific trusted hostname from the DNS-rebinding guard.
+  Proxy hostnames are opt-in through `AUM_TRUSTED_HOSTS`.
+
+For earlier history, see
+[GitHub Releases](https://github.com/minglong51/agent-usage-manager/releases).
+
+[Unreleased]: https://github.com/minglong51/agent-usage-manager/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/minglong51/agent-usage-manager/releases/tag/v0.3.0
+[0.2.6]: https://github.com/minglong51/agent-usage-manager/releases/tag/v0.2.6

agent_usage_manager-0.3.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: agent-usage-manager
+Version: 0.3.0
+Summary: Local htop-style dashboard and guarded kill switch for headless AI-agent processes.
+Project-URL: Homepage, https://github.com/minglong51/agent-usage-manager
+Project-URL: Repository, https://github.com/minglong51/agent-usage-manager
+Project-URL: Issues, https://github.com/minglong51/agent-usage-manager/issues
+Project-URL: Documentation, https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md
+Project-URL: Changelog, https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/minglong51/agent-usage-manager/security/policy
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,gpu,llm,monitoring,observability,ollama,vllm
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.9
+Requires-Dist: fastapi>=0.110
+Requires-Dist: psutil>=5.9
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: uvicorn[standard]>=0.27
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-usage-manager
+
+[![CI](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/minglong51/agent-usage-manager/blob/main/LICENSE)
+
+A local `htop`-style dashboard for headless AI-agent processes. It groups each
+agent's process tree, tracks CPU/RAM/GPU and sustained hot/idle/churn/leak
+states, and provides an allowlisted, token-gated stop control.
+
+**Per-node only:** AUM is not a scheduler or multi-host control plane. It runs
+on macOS and Linux; per-process GPU memory is currently NVIDIA/Linux only.
+
+![agent-usage-manager dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
+
+*Sanitized capture from a real macOS run. Host, path, and command details are
+replaced; Apple Silicon does not expose per-process GPU memory.*
+
+## Quick start
+
+```bash
+uvx agent-usage-manager
+```
+
+The dashboard opens at `http://127.0.0.1:8765`. No database or hosted service is
+required. The bundled config recognizes common tools including Claude Code,
+Codex, OpenClaw, Hermes, Ollama, vLLM, llama.cpp, Kiro, Aider, and Cline.
+
+Other install options:
+
+```bash
+pipx install agent-usage-manager
+# or, inside a virtual environment:
+pip install agent-usage-manager
+```
+
+## What it does
+
+- **One row per agent.** Child inference processes, MCP servers, and helpers are
+  rolled into the owning agent's row. CPU, memory, and GPU values are tree totals.
+- **Shows change over time.** CPU sparklines and `hot`, `idle`, `churn`, and
+  `leak?` states surface sustained problems rather than one noisy sample.
+- **Supports alerts.** A state transition can call a local command with `$AUM_*`
+  environment variables. `agent-usage-manager test-alert` proves the path first.
+- **Stops the process tree.** `kill` sends SIGTERM and escalates after three
+  seconds; `force` sends SIGKILL. launchd-supervised jobs get the command that
+  actually stops the service.
+- **Exposes read-only telemetry.** Use `agent-usage-manager list --json`,
+  `GET /api/agents`, or Prometheus-compatible `GET /metrics`.
+- **Keeps the control local.** The default bind is `127.0.0.1`; there is no
+  account, remote collector, or central coordinator.
+
+AUM complements process and telemetry tools:
+
+- `htop` sees processes, but not ownership of a spawned agent tree or agent states.
+- Grafana and Prometheus are useful fleet telemetry; AUM can feed them without
+  requiring that stack for a single machine.
+- GenAI traces describe sessions, tokens, and cost. AUM covers the host-process
+  side: liveness, resource pressure, restart churn, and local stop control.
+
+## Configure agents
+
+Create `agents.yaml` in the directory where you launch AUM, or pass
+`--config /path/to/agents.yaml`:
+
+```yaml
+agents:
+  - label: claude-code
+    match: "claude(\\s|$|-code)"
+    regex: true
+  - label: ollama
+    match: ollama
+
+protect:
+  - uvicorn
+
+ignore:
+  - crashpad
+```
+
+Only matched processes are listed or stoppable. `protect:` keeps a matched
+process visible but disables stopping it; `ignore:` removes a false match
+entirely. Edits hot-reload while the server runs.
+
+Advanced matching, per-instance tmux/launchd labels, alerts, API details,
+service setup, and troubleshooting are in the
+[operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md).
+
+## Safety boundary
+
+A web page that can stop processes needs a narrow boundary:
+
+- The server re-checks the allowlist before every signal. PID 1, AUM itself, and
+  configured `protect:` matches are always refused.
+- Every stop request requires an `X-Kill-Token`. AUM creates the token in a
+  mode-`0600` state file and never serves it over HTTP.
+- Browser requests are checked for DNS-rebinding and cross-origin state changes.
+- Non-loopback binds fail closed unless `--unsafe-expose` is explicit.
+- Every stop attempt and refusal is appended to a local action log.
+- Common token and key shapes are redacted before command lines reach the UI.
+  Redaction is not a substitute for reviewing screenshots and issue attachments.
+- Read-only endpoints still expose process metadata. Keep AUM on a trusted
+  machine or put an authenticated boundary in front of any proxy.
+
+Report vulnerabilities privately through the
+[security policy](https://github.com/minglong51/agent-usage-manager/security/policy). Do not open a public issue for a kill-path,
+authorization, redaction, or package-privacy defect.
+
+## Limits
+
+| Area | Current boundary |
+|---|---|
+| Process matching | Heuristic; use `ignore:` for false positives |
+| GPU | Per-process values require `nvidia-smi`; unavailable on Apple Silicon |
+| Supervision | launchd user jobs detected; systemd supervision is not |
+| Permissions | AUM can only signal processes accessible to its OS user |
+| History | In memory and reset when the server restarts |
+| Windows | Untested; CI covers macOS and Linux |
+
+## Command-line and API entry points
+
+```bash
+agent-usage-manager                     # dashboard
+agent-usage-manager list                # one-shot table
+agent-usage-manager list --json         # scriptable snapshot
+agent-usage-manager test-alert          # verify configured alert delivery
+```
+
+The HTTP surface is documented in the
+[operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md). External controllers should consume
+the read-only endpoints and own their own scheduling or irreversible decisions.
+
+## Project documentation
+
+- [Operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md): configuration, alerts, API, services,
+  proxying, and troubleshooting
+- [Changelog](https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md): current release and unreleased changes
+- [Security policy](https://github.com/minglong51/agent-usage-manager/security/policy): supported versions and private reporting
+- [Contributing](https://github.com/minglong51/agent-usage-manager/blob/main/CONTRIBUTING.md): setup, scope, and privacy requirements
+- [Architecture](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/HLD.md) and [implementation design](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/LLD.md)
+
+If AUM misclassifies a process or behaves differently on macOS or Linux,
+[open a bug report](https://github.com/minglong51/agent-usage-manager/issues/new?template=bug_report.yml)
+with sanitized output. Never attach a live config, token file, or unreviewed
+process command line.
+
+AUM is a personal open-source project. Maintenance and support are best-effort.
+
+## License
+
+MIT

agent_usage_manager-0.3.0/README.md

@@ -0,0 +1,152 @@
+# agent-usage-manager
+
+[![CI](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml/badge.svg)](https://github.com/minglong51/agent-usage-manager/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-usage-manager.svg)](https://pypi.org/project/agent-usage-manager/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/minglong51/agent-usage-manager/blob/main/LICENSE)
+
+A local `htop`-style dashboard for headless AI-agent processes. It groups each
+agent's process tree, tracks CPU/RAM/GPU and sustained hot/idle/churn/leak
+states, and provides an allowlisted, token-gated stop control.
+
+**Per-node only:** AUM is not a scheduler or multi-host control plane. It runs
+on macOS and Linux; per-process GPU memory is currently NVIDIA/Linux only.
+
+![agent-usage-manager dashboard](https://raw.githubusercontent.com/minglong51/agent-usage-manager/main/docs/dashboard.png)
+
+*Sanitized capture from a real macOS run. Host, path, and command details are
+replaced; Apple Silicon does not expose per-process GPU memory.*
+
+## Quick start
+
+```bash
+uvx agent-usage-manager
+```
+
+The dashboard opens at `http://127.0.0.1:8765`. No database or hosted service is
+required. The bundled config recognizes common tools including Claude Code,
+Codex, OpenClaw, Hermes, Ollama, vLLM, llama.cpp, Kiro, Aider, and Cline.
+
+Other install options:
+
+```bash
+pipx install agent-usage-manager
+# or, inside a virtual environment:
+pip install agent-usage-manager
+```
+
+## What it does
+
+- **One row per agent.** Child inference processes, MCP servers, and helpers are
+  rolled into the owning agent's row. CPU, memory, and GPU values are tree totals.
+- **Shows change over time.** CPU sparklines and `hot`, `idle`, `churn`, and
+  `leak?` states surface sustained problems rather than one noisy sample.
+- **Supports alerts.** A state transition can call a local command with `$AUM_*`
+  environment variables. `agent-usage-manager test-alert` proves the path first.
+- **Stops the process tree.** `kill` sends SIGTERM and escalates after three
+  seconds; `force` sends SIGKILL. launchd-supervised jobs get the command that
+  actually stops the service.
+- **Exposes read-only telemetry.** Use `agent-usage-manager list --json`,
+  `GET /api/agents`, or Prometheus-compatible `GET /metrics`.
+- **Keeps the control local.** The default bind is `127.0.0.1`; there is no
+  account, remote collector, or central coordinator.
+
+AUM complements process and telemetry tools:
+
+- `htop` sees processes, but not ownership of a spawned agent tree or agent states.
+- Grafana and Prometheus are useful fleet telemetry; AUM can feed them without
+  requiring that stack for a single machine.
+- GenAI traces describe sessions, tokens, and cost. AUM covers the host-process
+  side: liveness, resource pressure, restart churn, and local stop control.
+
+## Configure agents
+
+Create `agents.yaml` in the directory where you launch AUM, or pass
+`--config /path/to/agents.yaml`:
+
+```yaml
+agents:
+  - label: claude-code
+    match: "claude(\\s|$|-code)"
+    regex: true
+  - label: ollama
+    match: ollama
+
+protect:
+  - uvicorn
+
+ignore:
+  - crashpad
+```
+
+Only matched processes are listed or stoppable. `protect:` keeps a matched
+process visible but disables stopping it; `ignore:` removes a false match
+entirely. Edits hot-reload while the server runs.
+
+Advanced matching, per-instance tmux/launchd labels, alerts, API details,
+service setup, and troubleshooting are in the
+[operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md).
+
+## Safety boundary
+
+A web page that can stop processes needs a narrow boundary:
+
+- The server re-checks the allowlist before every signal. PID 1, AUM itself, and
+  configured `protect:` matches are always refused.
+- Every stop request requires an `X-Kill-Token`. AUM creates the token in a
+  mode-`0600` state file and never serves it over HTTP.
+- Browser requests are checked for DNS-rebinding and cross-origin state changes.
+- Non-loopback binds fail closed unless `--unsafe-expose` is explicit.
+- Every stop attempt and refusal is appended to a local action log.
+- Common token and key shapes are redacted before command lines reach the UI.
+  Redaction is not a substitute for reviewing screenshots and issue attachments.
+- Read-only endpoints still expose process metadata. Keep AUM on a trusted
+  machine or put an authenticated boundary in front of any proxy.
+
+Report vulnerabilities privately through the
+[security policy](https://github.com/minglong51/agent-usage-manager/security/policy). Do not open a public issue for a kill-path,
+authorization, redaction, or package-privacy defect.
+
+## Limits
+
+| Area | Current boundary |
+|---|---|
+| Process matching | Heuristic; use `ignore:` for false positives |
+| GPU | Per-process values require `nvidia-smi`; unavailable on Apple Silicon |
+| Supervision | launchd user jobs detected; systemd supervision is not |
+| Permissions | AUM can only signal processes accessible to its OS user |
+| History | In memory and reset when the server restarts |
+| Windows | Untested; CI covers macOS and Linux |
+
+## Command-line and API entry points
+
+```bash
+agent-usage-manager                     # dashboard
+agent-usage-manager list                # one-shot table
+agent-usage-manager list --json         # scriptable snapshot
+agent-usage-manager test-alert          # verify configured alert delivery
+```
+
+The HTTP surface is documented in the
+[operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md). External controllers should consume
+the read-only endpoints and own their own scheduling or irreversible decisions.
+
+## Project documentation
+
+- [Operator reference](https://github.com/minglong51/agent-usage-manager/blob/main/docs/reference.md): configuration, alerts, API, services,
+  proxying, and troubleshooting
+- [Changelog](https://github.com/minglong51/agent-usage-manager/blob/main/CHANGELOG.md): current release and unreleased changes
+- [Security policy](https://github.com/minglong51/agent-usage-manager/security/policy): supported versions and private reporting
+- [Contributing](https://github.com/minglong51/agent-usage-manager/blob/main/CONTRIBUTING.md): setup, scope, and privacy requirements
+- [Architecture](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/HLD.md) and [implementation design](https://github.com/minglong51/agent-usage-manager/blob/main/docs/design/LLD.md)
+
+If AUM misclassifies a process or behaves differently on macOS or Linux,
+[open a bug report](https://github.com/minglong51/agent-usage-manager/issues/new?template=bug_report.yml)
+with sanitized output. Never attach a live config, token file, or unreviewed
+process command line.
+
+AUM is a personal open-source project. Maintenance and support are best-effort.
+
+## License
+
+MIT

agent_usage_manager-0.3.0/SECURITY.md

@@ -0,0 +1,46 @@
+# Security policy
+
+`agent-usage-manager` exposes local process metadata and a stop endpoint. Please
+report vulnerabilities privately.
+
+## Supported versions
+
+| Version | Supported |
+|---|---|
+| Latest PyPI release | Yes |
+| Older releases | No |
+
+Security fixes are made against the latest release. Upgrade before reporting a
+problem that may already be fixed.
+
+## Report privately
+
+Use
+[GitHub private vulnerability reporting](https://github.com/minglong51/agent-usage-manager/security/advisories/new).
+
+Do not open a public issue for:
+
+- bypasses of the process allowlist, protected-process checks, or kill token
+- cross-origin, DNS-rebinding, or non-loopback exposure problems
+- command-line redaction bypasses
+- package contents that expose maintainer or user configuration
+- action-log or token-file permission problems
+
+Include the AUM version, operating system, installation method, reproduction
+steps, expected impact, and the smallest safe evidence needed to reproduce the
+problem.
+
+Do not attach a live `agents.yaml`, kill token, full process command line,
+hostname, home-directory path, or unsanitized screenshot. Replace identifying
+values before submitting.
+
+## What to expect
+
+This is a personal open-source project maintained on a best-effort basis, with
+no response-time SLA. The maintainer will acknowledge a reproducible report,
+work toward a fix, and coordinate disclosure when the issue is resolved.
+
+A local user who already has permission to signal the same processes is outside
+the threat boundary. Unsafe deployment choices, such as exposing read endpoints
+without an authenticated proxy, are also outside the default boundary unless
+AUM fails to enforce a documented guard.

agent_usage_manager-0.2.5/agent_usage_manager/agents.yaml → agent_usage_manager-0.3.0/agent_usage_manager/agents.default.yaml

@@ -1,3 +1,8 @@
+# Default configuration shipped with the package. It is used only when you have
+# no agents.yaml of your own: `--config` wins, then ./agents.yaml in the current
+# directory, then this file. Copy it somewhere and edit rather than editing it
+# in place — a package upgrade replaces this file.
+#
 # Which processes count as "agents". A process matches if the pattern hits its
 # executable name + first few arguments (case-insensitive substring or regex) —
 # NOT the entire command line, so a process that merely mentions an agent name
@@ -68,38 +73,35 @@ ignore:
 
 # Optional: per-instance labels from launchd job labels — the supervised-fleet
 # counterpart of tmux_labels below. Several LaunchAgents running the same
-# binary (e.g. ai.hermes.gateway, ai.hermes.gateway-frontdoor, …) all hit one
-# agents: entry and land as indistinguishable rows, and tmux never sees them.
-# When a matched root's own launchd job label matches this regex, the first
-# capture group (the whole label if no group) becomes the row label — churn
-# tracking, alert transitions, and /metrics all get per-instance identity.
-# tmux_labels wins when both apply. Empty/absent = off.
-launchd_labels: "^ai\\.hermes\\.(?:gateway-)?(.+)$"   # → gateway, frontdoor, engineering_3
+# binary all hit one agents: entry and land as indistinguishable rows, and tmux
+# never sees them. When a matched root's own launchd job label matches this
+# regex, the first capture group (the whole label if no group) becomes the row
+# label — churn tracking, alert transitions, and /metrics all get per-instance
+# identity. tmux_labels wins when both apply. Empty/absent = off.
+#
+#   launchd_labels: "^com\\.example\\.worker-(.+)$"   # → worker-1, worker-2
 
 # Optional: per-instance labels from tmux session names. A fleet of identical
-# agents (e.g. several claude-code bots, one per tmux session bot-*) all hit
-# one agents: entry above and land as N indistinguishable rows — their
-# cmdlines can't tell them apart, because matching deliberately sees only the
-# executable + first args. The tmux session each one runs in IS its identity:
-# when a matched root (or an ancestor) is a tmux pane whose session name
-# matches this regex, the row is labeled with the first capture group (the
-# whole session name if there is no group). Sessions that don't match keep
-# their agents: label, so incidental tmux use never renames rows.
-tmux_labels: "^bot-(.+)$"      # session bot-coder_1 → row label coder_1
+# agents (e.g. several claude-code bots, one per tmux session) all hit one
+# agents: entry above and land as N indistinguishable rows — their cmdlines
+# can't tell them apart, because matching deliberately sees only the executable
+# + first args. The tmux session each one runs in IS its identity: when a
+# matched root (or an ancestor) is a tmux pane whose session name matches this
+# regex, the row is labeled with the first capture group (the whole session
+# name if there is no group). Sessions that don't match keep their agents:
+# label, so incidental tmux use never renames rows.
+#
+#   tmux_labels: "^bot-(.+)$"      # session bot-worker1 → row label worker1
 
-# Labels whose idle state is NORMAL — agents that wait for work (bots parked
-# on a Telegram poll, gateways waiting for requests). They get no "idle"
-# badge: badging the whole waiting fleet wallpapers the dashboard and trains
-# badge-blindness (12 of 22 rows wore "idle 10m+" before this existed). Same
-# reasoning as `idle` being opt-in for alerts below. Case-insensitive
+# Labels whose idle state is NORMAL — agents that wait for work (bots parked on
+# a chat poll, gateways waiting for requests). They get no "idle" badge: badging
+# the whole waiting fleet wallpapers the dashboard and trains badge-blindness.
+# Same reasoning as `idle` being opt-in for alerts below. Case-insensitive
 # substrings of the row label (incl. tmux-derived ones), like ignore:.
-idle_ok:
-  - admin
-  - coder        # covers coder_1…coder_4
-  - hermes       # covers the launchd_labels-renamed rows too (gateway,
-                 # frontdoor, engineering_*) — suppression matches the BASE
-                 # matcher label as well as the instance label
-  - codex
+#
+#   idle_ok:
+#     - gateway
+#     - worker
 
 # GPU sampling: nvidia-smi is used automatically when present (Linux/NVIDIA).
 # On Apple Silicon there is no per-process GPU API, so the GPU column is blank.
@@ -113,29 +115,15 @@ idle_ok:
 # fleet of agents that wait for work, idle is the NORMAL state, and alerting on
 # it floods the channel every time the server restarts and re-learns the fleet.
 #
-# Example (desktop notification):
+# Nothing is wired by default — uncomment and point it at your own channel, then
+# prove it with `agent-usage-manager test-alert` before a real badge depends on
+# it. Two things worth knowing before you turn `hot` on: for inference agents
+# pegged CPU IS the job, and spawn-heavy agents look like churn while working.
+#
 #   alerts:
 #     command: 'terminal-notifier -title agent-usage-manager -message "$AUM_MSG"'
 #     cooldown: 600              # seconds, default 600
 #     flags: [hot, churn, leak]  # default; add idle only if you really want it
-#
-# Live wiring on this host: record to the attention feed, never ring
-# (2026-07-06, Ming: "most of them are noise"). First live day pushed two false
-# positives — "codex churn" during legitimate spawn work and "claude-code hot"
-# during a working session; for inference agents, pegged-CPU IS the job.
-# Badges stay live on the dashboard + machinery panel; the feed line rides the
-# next digest. Genuine breakage has louder, independent signals (mcp-autoheal
-# GAVE UP, cron-health, sync-bot liveness). `hot` dropped from alerting
-# entirely.
-# Ref discipline (2026-07-30): one stable ref per (agent, flag) + --upsert-open,
-# so a repeat firing UPDATES the single open card in place instead of stacking
-# one per cooldown expiry (nine churn cards in five days); the refreshed card
-# carries the latest cpu/mem/pid snapshot. fyi level = feed-only, riding the
-# digest exactly like the retired notify.py --feed-only wiring did.
-alerts:
-  command: '"$HOME/workspace/founder-agent-os/bin/attention" add --level fyi --source usage-manager --title "$AUM_MSG" --body "$AUM_MSG" --ref "usage-manager:$AUM_LABEL:$AUM_FLAG" --upsert-open'
-  cooldown: 7200                 # 2 h per (agent, flag)
-  flags: [churn, leak]
-  leak_floor_mb: 1536            # bots legitimately ratchet RSS as session
-                                 # context grows; only push leak alerts once
-                                 # the absolute footprint is actually large
+#     leak_floor_mb: 1536        # only alert on leak once the absolute footprint
+#                                # is large — long-running agents legitimately
+#                                # ratchet RSS as their context grows