agent-dispatch 0.14.0__tar.gz → 0.15.1__tar.gz

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/AGENTS.md

@@ -12,6 +12,8 @@ MCP server + CLI that lets Claude Code agents delegate tasks to agents in other
 |------|------|
 | `src/agent_dispatch/runner.py` | Sync subprocess wrapper around `claude -p` — the actual work |
 | `src/agent_dispatch/server.py` | Async FastMCP interface (21 MCP tools), wraps runner in `asyncio.to_thread` + semaphore |
+| `src/agent_dispatch/usage.py` | Append-only dispatch journal (cost/duration/outcome) + aggregation for `stats` and the `typical` block |
+| `src/agent_dispatch/servers.py` | Registry of live `serve` processes and the version each one runs (`doctor` reads it) |
 | `src/agent_dispatch/cli.py` | Click CLI: `init`, `add`, `update`, `remove`, `list`, `describe`, `test`, `doctor`, `jobs`, `job`, `cancel`, `gc`, `group` (add/list/inspect/update/remove), `serve` |
 | `src/agent_dispatch/models.py` | Pydantic v2 models (`AgentConfig`, `DispatchGroup`/`GroupMember`, `Settings`, `DispatchResult`) |
 | `src/agent_dispatch/config.py` | YAML config load/save + project auto-description |
@@ -28,7 +30,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 637 tests, ~15s
+python3 -m pytest tests/ -v   # 714 tests, ~17s
 ```
 
 Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. The one exception is `TestStreamPipeHandling`, which spawns a short-lived *python* subprocess: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
@@ -61,6 +63,13 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 - Every state file (`agents.yaml`, job files) is written **temp file + `os.replace`**, never in place, and every load/mutate/save is wrapped in `config.ProcessLock` — the CLI and the MCP server are separate processes writing the same files, so a thread lock alone loses updates.
 - Anything that changes an agent's config must call `_invalidate_agent_cache` — the cache key holds the agent *name*, not its directory or permissions.
 - Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, `budget_exceeded` results, and results whose `outcome` is `partial`/`blocked`, so the documented "grant access / fix the cause, then re-dispatch" recovery is never short-circuited.
+- **Coerce every number read off disk through `usage.as_float`.** `float("abc")` raises **ValueError** — not `JSONDecodeError`, not `OSError` — so it escaped the per-line handler in `usage.load` and the sort key in `servers.live_servers`, turning `agent-dispatch stats --days 7` and `doctor` into tracebacks over one hand-edited character. Same escape route as the `UnicodeDecodeError`-is-a-`ValueError` round. A journal or registry field is untrusted input: skip the record or sort it last, never raise from the command someone ran *because* something is already wrong.
+- **`--json` output must be valid JSON on the empty path too.** `stats --json` printed prose when the journal had no records — i.e. on a fresh install, which is exactly when a script first pipes it somewhere.
+- **The usage journal is written by a decorator, not at each return.** `runner._journaled` wraps `dispatch`/`dispatch_stream` because each has a dozen early returns; instrumenting them one by one guarantees the next new return path goes unrecorded. It records the outermost call only (`_use_session_flag` is False on the stream's old-CLI retry, which would otherwise double-count one dispatch). It also swallows exceptions itself even though `usage.record` already does: the result in hand is billed, and the guarantee has to hold at the boundary that owns the damage rather than on another module's promise (`test_a_broken_journal_never_breaks_a_paid_dispatch` removes record()'s guard to prove it).
+- **A journal record is one `O_APPEND` write under `PIPE_BUF`**, never a locked read-modify-write: the CLI and every running server share one file, and this user has 14+ servers alive. Every field is capped so the line cannot approach 4096 bytes. Rotation is an atomic rename at ~2 MB, two generations kept.
+- **Profiles are memoized on the journal's (path, size, mtime) and read a NARROWER tail than `stats`.** `list_agents`/`inspect_agent` run on the event-loop thread: a full 2 MB journal cost **24.8 ms** per discovery call at the 512 KB report window — 33x the config parse that 0.13.0 exists to have fixed. Now 3.3 ms cold, ~0 warm. Every profile consumer goes through `usage.profiles()`; never add a caller that re-parses per agent.
+- **`usage_limit` is its own error type** (observed live: `You've hit your session limit · resets 6pm`). It is checked *before* the permission patterns and its hint says the limit is account-wide, so "try another agent" is not a workaround. Text-classified errors attach their advisory through the single `_classification_hint`, not per site.
+- **Server liveness is an advisory lock, not a PID.** `servers.register` holds an exclusive `flock` on `<config dir>/servers/<pid>.json` for the process lifetime; a reader that *takes* that lock owns a dead entry and deletes it. `os.kill(pid, 0)` would believe a recycled PID and would never notice a SIGKILLed server. Never close that fd (re-registering closes the old one first).
 - **The dispatch protocol goes in the system prompt, not the task.** `_build_system_prompt` (runner.py) renders the protocol (non-interactive, time/spend budget, lead with the outcome, trailing `STATUS:` line) plus the agent's `instructions`, and `_build_command` passes it as `--append-system-prompt` — on `--resume` too, since the CLI re-applies an appended prompt on every launch. `_build_prompt` (the `-p` text) is unchanged, so the cache key is unchanged. The text always starts with a `##` header line so it can never be read as a flag. `settings.dispatch_protocol: false` turns the protocol off (for CLIs that predate the flag; `doctor` probes `claude --help` for it); per-agent `instructions` still go through when set.
 - **`outcome` is lifted from the LAST line of the result** (`_split_outcome`), before JSON parsing, by the shared `_build_success_result` (the success-side twin of `_build_error_result` — both `dispatch` and `dispatch_stream` go through it) and by the plain-text fallback tier. A bare marker line is removed from `result`; a marker with a trailing reason stays. `outcome` never flips `success`; `partial`/`blocked` add a `hint` with the `dispatch_session(...)` continuation, after the denial hint. In JSON mode the protocol omits the STATUS instruction (the JSON footer governs), but a STATUS line that arrives anyway is still stripped so `parsed_result` survives.
 - Remediation text is a contract: a hint that names a flag must name one that exists (`test_printed_budget_hint_is_a_runnable_command` feeds the printed flags back into the CLI). Run the command you print.
@@ -87,4 +96,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## More detail
 
-[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 637 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).
+[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 714 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/CHANGELOG.md

@@ -7,6 +7,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.1] - 2026-09-09
+
+Three defects in 0.15.0's own new code, found by re-auditing it the way this
+project audits everything else — the fix is the most likely place for the next
+bug, and a new file is a new place for an old one.
+
+### Fixed
+- **A corrupt number in the journal or the server registry crashed the command
+  you run to diagnose it.** `float("abc")` raises **ValueError**, which is
+  neither a `json.JSONDecodeError` nor an `OSError`, so one hand-edited or
+  torn-written character made `agent-dispatch stats --days 7` and
+  `agent-dispatch doctor` end in a traceback instead of skipping the record.
+  This is the same escape route as the `UnicodeDecodeError`-is-a-`ValueError`
+  round in 0.12.1. All three sites now coerce through one shared
+  `usage.as_float`: an undatable record falls outside the window, a registry
+  entry with a mangled timestamp sorts last.
+- **`stats --json` printed prose instead of JSON when the journal was empty** —
+  which is precisely the state of a fresh install, and therefore the first
+  thing a script piping it would hit. It now always emits the report object.
+- Doc drift: `AGENTS.md` carried a stale test count.
+
+
+## [0.15.0] - 2026-09-09
+
+The measurement round. 0.14.0 told a dispatched agent how to behave; this one
+records what actually happened. Four live dispatches through the new protocol
+came back **5/5 with a STATUS line and 0/5 ending in a clarifying question**,
+covering every branch of the protocol. The case it was built for: an ambiguous
+task ("how many users signed up in 30 days?", no project named) where the agent
+stated its assumption, counted across every database, and returned `done`
+rather than asking. A tool-less agent returned `blocked`. And under a
+deliberately tight 45s budget an agent scoped the work down, delivered what it
+had, listed three specific gaps ("31 mirrors, not 32 — I did not check which";
+"HEAD only"; "mirrors may be stale") and returned `partial` with a resume hint —
+a result the cache then refuses to store, so the retry runs fresh.
+
+### Added
+- **Usage journal + `agent-dispatch stats`.** Every dispatch appends one line to
+  `usage.jsonl` — agent, ok, cost, duration, turns, outcome, error type, caller;
+  cache hits too, flagged `cached`. `stats [--days N --agent X --json]` turns it
+  into spend, median/p90 durations, outcome and failure counts per agent. Until
+  now `cost_usd` and `duration_ms` were returned once and discarded, so "which
+  agent burns money" had no answer and the only timing knowledge in the system
+  was hand-written prose in agent descriptions. Recording is one `O_APPEND`
+  write capped under `PIPE_BUF`, so the CLI and all running servers share one
+  file with no lock; it rotates at ~2 MB keeping two generations; a failure to
+  write it can never fail a dispatch. Off with `settings.usage_log: false`.
+- **`typical` in `list_agents` and `inspect_agent`** — measured median/p90
+  seconds and median cost from that agent's own recent runs, so a caller can
+  size `timeout_seconds` from data instead of from a description. Absent below
+  three recorded dispatches: no data beats a "typical" derived from two runs.
+  Costs ~115 bytes per agent (3.6% of a discovery payload).
+- **`error_type: "usage_limit"`** for the Claude *account's* rate/session limit,
+  observed live during this round's evaluation (`You've hit your session limit ·
+  resets 6pm`) — it used to land in the generic `cli_error` bucket. The hint
+  names the reset time and says the limit is account-wide, so dispatching a
+  different agent is not a workaround, and nothing was billed.
+- **`doctor` now names the sessions running stale code.** Each server registers
+  `<config dir>/servers/<pid>.json` and holds an advisory lock on it for life;
+  `doctor` reports live servers by version and prints the pid and age of every
+  one still on an older release. A Python process holds its modules for life, so
+  an upgrade reaches an open Claude Code session only when it restarts — on this
+  machine 18 servers were running previous code with no way to tell which.
+  Liveness is the lock, not the PID: a recycled PID cannot fake a live server
+  and a SIGKILLed one cannot linger.
+
+### Changed
+- **A timeout error now suggests a number, not a doubling.** With enough history
+  the message names the value that would have covered this agent's real p90
+  (padded 50%). Doubling the current timeout was wrong in both directions.
+
+### Fixed
+- Discovery no longer pays for the journal on the event loop: profiles are
+  memoized on the journal's (path, size, mtime) and read a narrower tail than
+  the report. Measured on a full 2 MB journal, `list_agents` went from
+  **24.8 ms to 3.3 ms cold and ~0.01 ms warm** — the 512 KB version would have
+  been 33x the config parse that 0.13.0 exists to have eliminated.
+
+
 ## [0.14.0] - 2026-09-08
 
 The delegation round: what a dispatched agent is *told*, and what it tells

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-dispatch
-Version: 0.14.0
+Version: 0.15.1
 Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
 Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
 Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -134,13 +134,16 @@ Lists all configured agents. **Call this first** to see what's available.
     "capabilities": ["docker_logs", "deploy_debug"],
     "risky_capabilities": ["restart_services"],
     "permission_mode": "bypassPermissions",
-    "allowed_tools": ["Bash", "Read", "Grep"]
+    "allowed_tools": ["Bash", "Read", "Grep"],
+    "typical": {"median_seconds": 143.3, "p90_seconds": 178.3, "median_cost_usd": 0.2666}
   }
 ]
 ```
 
 `mcp_servers`, `stacks`, and `dbs` are detected from the agent's project files (`.mcp.json`, `Dockerfile`, `pyproject.toml`, `Cargo.toml`, `prisma/`, `alembic.ini`, etc.) so callers can pick the right agent without dispatching a probe.
 
+`typical` is **measured**, not declared: it comes from this agent's own recent dispatches in the [usage journal](#usage-journal--what-your-fleet-actually-costs) and appears only after a few runs. Use it to size `timeout_seconds` and to know what a call will cost before you make it. It is absent when the journal is off or the agent has too little history — no data is better than a typical duration derived from two runs.
+
 ### `inspect_agent`
 
 Cheap detailed lookup — reads the agent's files without spawning a `claude` session. Returns the full config (timeout, model, budget, permission mode, allowed/disallowed tools), detected MCP/stacks/DBs, plus short previews of `CLAUDE.md` and `README.md` when present.
@@ -152,6 +155,15 @@ Cheap detailed lookup — reads the agent's files without spawning a `claude` se
 
 Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
 
+It also carries the agent's `instructions` (its standing orders) and the full `typical` block — the trimmed one in `list_agents` plus `dispatches`, `failed` and the `outcomes` breakdown:
+
+```json
+"typical": {
+  "dispatches": 24, "median_seconds": 143.3, "p90_seconds": 178.3,
+  "median_cost_usd": 0.2666, "failed": 1, "outcomes": {"done": 21, "partial": 2}
+}
+```
+
 ### Groups
 
 A **group** bundles related agents into a cross-project working set — typically a few code repos plus capability gateways (an `infra` agent with a Portainer MCP, an `analytics` agent with a browser + Yandex Metrica). It lets one orchestrating session coordinate work that spans code, deploy, and verification.
@@ -234,7 +246,7 @@ dispatch(
 }
 ```
 
-**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (the Claude *account* hit its rate/session limit), `cli_error` (other failures). Permission, budget, usage-limit and timeout errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -533,10 +545,11 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `error_type` | Meaning | Recovery |
 |--------------|---------|----------|
 | `permission` | A tool call was denied | `update_agent(name, allowed_tools="Bash,Read")` (least privilege) or `update_agent(name, permission_mode="bypassPermissions")`, then re-dispatch. The `error` text includes a hint with the exact fix. |
-| `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
+| `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
 | `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
+| `usage_limit` | The Claude **account** hit its usage/rate limit — not this agent, and nothing was billed | Wait for the reset named in the `error` text. Dispatching a *different* agent is not a workaround: every agent runs on the same account. If it recurs under load, lower `settings.max_concurrency`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
@@ -607,6 +620,9 @@ settings:
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
   # dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
   #                         # time budget, STATUS line → `outcome`). false = raw claude -p.
+  # usage_log: true         # record every dispatch in usage.jsonl (cost, duration, outcome).
+  #                         # Powers `agent-dispatch stats`, the `typical` block and the
+  #                         # measured timeout suggestion. false = record nothing.
   # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
@@ -616,6 +632,42 @@ settings:
 
 Config is reloaded on every tool call — add agents without restarting.
 
+### Usage journal — what your fleet actually costs
+
+Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
+(override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
+turns, `outcome`, error type, caller. Cache hits are recorded too, flagged
+`cached`, so the report can show what the cache saves.
+
+```console
+$ agent-dispatch stats --days 7
+Usage (last 7 day(s))
+  dispatches: 33, 1 served from cache
+  spend:      $13.0390
+  duration:   median 87s, p90 2m40s, max 10m00s
+  outcomes:   blocked 1, done 27, partial 3
+  failures:   timeout 1, usage_limit 1
+
+Per agent
+  analytic           18 runs  $  8.9441  median  2m04s  p90  2m51s
+      done 15, partial 3
+  gitlab             12 runs  $  3.7949  median    60s  p90    86s
+      done 12  |  1 cached
+```
+
+`--agent NAME` narrows it, `--json` emits the same report as JSON.
+
+The journal is what makes three other things work: the `typical` block in
+`list_agents` / `inspect_agent`, the timeout error naming a value derived from
+the agent's real p90 instead of a doubling guess, and any answer at all to
+"which agent is expensive". Turn it off with `usage_log: false` in settings.
+
+Properties worth knowing: the file is owner-only (`0o600`); each record is a
+single `O_APPEND` write capped well under `PIPE_BUF`, so the CLI and every
+running server can share it with no lock and no torn lines; it rotates to
+`usage.jsonl.1` at ~2 MB and keeps two generations, so it is bounded at ~4 MB
+forever. A failure to write it can never fail a dispatch.
+
 ### Job retention
 
 Every `dispatch_async` **and** every `dispatch(..., return_ref=True)` writes a
@@ -682,6 +734,8 @@ agent-dispatch MCP server
        ├─ System prompt += dispatch protocol + the agent's standing `instructions`
        ├─ Receives structured prompt with goal/caller/context/task
        └─ Returns result (+ its own STATUS → `outcome`) → cached when complete
+                    │
+                    └─ one line appended to usage.jsonl (cost, duration, outcome)
 ```
 
 ## Safety
@@ -689,7 +743,7 @@ agent-dispatch MCP server
 - **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3. Best-effort across the subprocess boundary (see [SECURITY.md](SECURITY.md)).
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
-- **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
+- **Owner-only state** — job files, `agents.yaml`, the usage journal and the server registry are all written `0o600`; their directories are `0o700`.
 - **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
@@ -710,7 +764,8 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
 | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
-| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), MCP registration, agent health, and group membership |
+| `agent-dispatch stats [--days N --agent X --json]` | What dispatches cost: spend, durations, outcomes and failures per agent |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), running servers on stale code, MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/README.md

@@ -104,13 +104,16 @@ Lists all configured agents. **Call this first** to see what's available.
     "capabilities": ["docker_logs", "deploy_debug"],
     "risky_capabilities": ["restart_services"],
     "permission_mode": "bypassPermissions",
-    "allowed_tools": ["Bash", "Read", "Grep"]
+    "allowed_tools": ["Bash", "Read", "Grep"],
+    "typical": {"median_seconds": 143.3, "p90_seconds": 178.3, "median_cost_usd": 0.2666}
   }
 ]
 ```
 
 `mcp_servers`, `stacks`, and `dbs` are detected from the agent's project files (`.mcp.json`, `Dockerfile`, `pyproject.toml`, `Cargo.toml`, `prisma/`, `alembic.ini`, etc.) so callers can pick the right agent without dispatching a probe.
 
+`typical` is **measured**, not declared: it comes from this agent's own recent dispatches in the [usage journal](#usage-journal--what-your-fleet-actually-costs) and appears only after a few runs. Use it to size `timeout_seconds` and to know what a call will cost before you make it. It is absent when the journal is off or the agent has too little history — no data is better than a typical duration derived from two runs.
+
 ### `inspect_agent`
 
 Cheap detailed lookup — reads the agent's files without spawning a `claude` session. Returns the full config (timeout, model, budget, permission mode, allowed/disallowed tools), detected MCP/stacks/DBs, plus short previews of `CLAUDE.md` and `README.md` when present.
@@ -122,6 +125,15 @@ Cheap detailed lookup — reads the agent's files without spawning a `claude` se
 
 Use this **before** `dispatch_async`/`dispatch` to confirm an agent has the tools and context for your task — much cheaper than a probe dispatch.
 
+It also carries the agent's `instructions` (its standing orders) and the full `typical` block — the trimmed one in `list_agents` plus `dispatches`, `failed` and the `outcomes` breakdown:
+
+```json
+"typical": {
+  "dispatches": 24, "median_seconds": 143.3, "p90_seconds": 178.3,
+  "median_cost_usd": 0.2666, "failed": 1, "outcomes": {"done": 21, "partial": 2}
+}
+```
+
 ### Groups
 
 A **group** bundles related agents into a cross-project working set — typically a few code repos plus capability gateways (an `infra` agent with a Portainer MCP, an `analytics` agent with a browser + Yandex Metrica). It lets one orchestrating session coordinate work that spans code, deploy, and verification.
@@ -204,7 +216,7 @@ dispatch(
 }
 ```
 
-**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `cli_error` (other failures). Permission and budget errors include an actionable hint.
+**`error_type` values:** `permission` (tool/action denied), `timeout`, `recursion` (dispatch depth exceeded), `not_found` (missing directory or CLI), `budget` (the `claude` CLI stopped the session at `max_budget_usd`), `usage_limit` (the Claude *account* hit its rate/session limit), `cli_error` (other failures). Permission, budget, usage-limit and timeout errors include an actionable hint.
 
 **Resumable timeouts:** every fresh dispatch pre-assigns a session UUID (`--session-id`), so a timed-out dispatch still returns a `session_id` — the partial transcript survives the kill. The timeout error spells out the recovery: resume with `dispatch_session(agent, "Continue where you left off", session_id=...)`, retry with a bigger `timeout_seconds`, or use `dispatch_async`.
 
@@ -503,10 +515,11 @@ Failures are deterministic: check `success`, then branch on `error_type`.
 | `error_type` | Meaning | Recovery |
 |--------------|---------|----------|
 | `permission` | A tool call was denied | `update_agent(name, allowed_tools="Bash,Read")` (least privilege) or `update_agent(name, permission_mode="bypassPermissions")`, then re-dispatch. The `error` text includes a hint with the exact fix. |
-| `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=`, or use `dispatch_async`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
+| `timeout` | Process killed at the timeout | Resume the partial work: `dispatch_session(agent, "Continue where you left off", session_id=<from the error text>)`. Or retry with a bigger `timeout_seconds=` — once the journal has history the error names the value that would have covered this agent's p90 — or use `dispatch_async`. A *streaming* dispatch that produced its answer before the deadline returns that answer with a `hint` instead of failing. |
 | `not_found` | Agent directory or `claude` CLI missing | `list_agents()` → check `healthy`. Re-add the agent with an existing path, or run `agent-dispatch doctor` to find what's missing. |
 | `recursion` | Dispatch nesting exceeded `max_dispatch_depth` (default 3) | Don't dispatch from dispatched agents; if the nesting is intentional, raise `max_dispatch_depth` in settings. |
 | `budget` | The `claude` CLI ended the session at the `max_budget_usd` spend cap — the answer is incomplete | Raise the cap (`update_agent(name, max_budget_usd=2.0)`), switch to a cheaper `model`, or split the task. The partial session is resumable: `dispatch_session(agent, "Continue where you left off", session_id=<from the result>)`. |
+| `usage_limit` | The Claude **account** hit its usage/rate limit — not this agent, and nothing was billed | Wait for the reset named in the `error` text. Dispatching a *different* agent is not a workaround: every agent runs on the same account. If it recurs under load, lower `settings.max_concurrency`. |
 | `cli_error` | Anything else from the `claude` subprocess | Read the `error` text; run `agent-dispatch doctor` for environment issues; retry once if transient. |
 
 Three soft signals that arrive with `success: true`:
@@ -577,6 +590,9 @@ settings:
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
   # dispatch_protocol: true # send every agent the dispatch protocol (non-interactive,
   #                         # time budget, STATUS line → `outcome`). false = raw claude -p.
+  # usage_log: true         # record every dispatch in usage.jsonl (cost, duration, outcome).
+  #                         # Powers `agent-dispatch stats`, the `typical` block and the
+  #                         # measured timeout suggestion. false = record nothing.
   # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
@@ -586,6 +602,42 @@ settings:
 
 Config is reloaded on every tool call — add agents without restarting.
 
+### Usage journal — what your fleet actually costs
+
+Every dispatch appends one line to `~/.config/agent-dispatch/usage.jsonl`
+(override with `AGENT_DISPATCH_USAGE_LOG`): agent, success, cost, duration,
+turns, `outcome`, error type, caller. Cache hits are recorded too, flagged
+`cached`, so the report can show what the cache saves.
+
+```console
+$ agent-dispatch stats --days 7
+Usage (last 7 day(s))
+  dispatches: 33, 1 served from cache
+  spend:      $13.0390
+  duration:   median 87s, p90 2m40s, max 10m00s
+  outcomes:   blocked 1, done 27, partial 3
+  failures:   timeout 1, usage_limit 1
+
+Per agent
+  analytic           18 runs  $  8.9441  median  2m04s  p90  2m51s
+      done 15, partial 3
+  gitlab             12 runs  $  3.7949  median    60s  p90    86s
+      done 12  |  1 cached
+```
+
+`--agent NAME` narrows it, `--json` emits the same report as JSON.
+
+The journal is what makes three other things work: the `typical` block in
+`list_agents` / `inspect_agent`, the timeout error naming a value derived from
+the agent's real p90 instead of a doubling guess, and any answer at all to
+"which agent is expensive". Turn it off with `usage_log: false` in settings.
+
+Properties worth knowing: the file is owner-only (`0o600`); each record is a
+single `O_APPEND` write capped well under `PIPE_BUF`, so the CLI and every
+running server can share it with no lock and no torn lines; it rotates to
+`usage.jsonl.1` at ~2 MB and keeps two generations, so it is bounded at ~4 MB
+forever. A failure to write it can never fail a dispatch.
+
 ### Job retention
 
 Every `dispatch_async` **and** every `dispatch(..., return_ref=True)` writes a
@@ -652,6 +704,8 @@ agent-dispatch MCP server
        ├─ System prompt += dispatch protocol + the agent's standing `instructions`
        ├─ Receives structured prompt with goal/caller/context/task
        └─ Returns result (+ its own STATUS → `outcome`) → cached when complete
+                    │
+                    └─ one line appended to usage.jsonl (cost, duration, outcome)
 ```
 
 ## Safety
@@ -659,7 +713,7 @@ agent-dispatch MCP server
 - **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3. Best-effort across the subprocess boundary (see [SECURITY.md](SECURITY.md)).
 - **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
 - **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
-- **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
+- **Owner-only state** — job files, `agents.yaml`, the usage journal and the server registry are all written `0o600`; their directories are `0o700`.
 - **Cost control** — `max_budget_usd` per agent or globally is passed to the `claude` CLI as `--max-budget-usd`, so a runaway dispatch is stopped at the cap and comes back as `error_type: "budget"` with a resumable `session_id`. An overshoot that lands over budget without stopping is flagged post-hoc with `budget_exceeded: true` + a hint.
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
@@ -680,7 +734,8 @@ See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassP
 | `agent-dispatch group <add\|list\|inspect\|update\|remove>` | Manage [groups](#groups) — cross-project working sets of agents |
 | `agent-dispatch describe <name>` | Show full configuration for one agent (tri-state tools, project files) |
 | `agent-dispatch test <name> [task] [--stream]` | Test an agent with a dispatch (`--stream` for live progress) |
-| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), MCP registration, agent health, and group membership |
+| `agent-dispatch stats [--days N --agent X --json]` | What dispatches cost: spend, durations, outcomes and failures per agent |
+| `agent-dispatch doctor` | Diagnose installation: Claude CLI (incl. `--append-system-prompt` support), running servers on stale code, MCP registration, agent health, and group membership |
 | `agent-dispatch jobs [--status --limit]` | List async dispatch jobs (most recent first) |
 | `agent-dispatch job <id>` | Show one job: status, progress tail, result preview |
 | `agent-dispatch cancel <id>` | Cancel a pending job (running jobs: use the `dispatch_cancel` MCP tool) |

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/agents.example.yaml

@@ -100,6 +100,12 @@ settings:
   default_timeout: 300
   max_dispatch_depth: 3           # recursion protection: A -> B -> A
   max_concurrency: 5              # max parallel claude -p processes
+  # usage_log: true                # Append one line per dispatch to usage.jsonl: agent,
+                                   # cost, duration, turns, outcome, error type, caller.
+                                   # Powers `agent-dispatch stats`, the measured `typical`
+                                   # block in list_agents/inspect_agent, and the timeout
+                                   # error's suggested value. Owner-only, rotates at ~2 MB.
+                                   # false = record nothing.
   # dispatch_protocol: true        # Append the dispatch protocol to every agent's system
                                    # prompt: it is non-interactive (never end with a
                                    # question), its time/spend budget, lead with the

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.14.0"
+version = "0.15.1"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/src/agent_dispatch/__init__.py

@@ -1,3 +1,3 @@
 """agent-dispatch: Delegate tasks between Claude Code agents across projects."""
 
-__version__ = "0.14.0"
+__version__ = "0.15.1"

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/src/agent_dispatch/cli.py

@@ -891,6 +891,37 @@ def doctor() -> None:
     else:
         warn("agent-dispatch not on PATH (MCP server still works via absolute path)")
 
+    section("Running servers")
+    from . import __version__, servers
+    from . import usage as usage_mod
+
+    live = servers.live_servers()
+    if not live:
+        ok("No agent-dispatch server is registered as running")
+    else:
+        drift = servers.version_drift(__version__)
+        stale_count = sum(drift.values())
+        ok(f"{len(live)} server process(es) registered, {len(live) - stale_count} on {__version__}")
+    # Printed in BOTH branches on purpose. A server only registers if it was
+    # started on a version that has this registry, so the count is a lower
+    # bound — on the machine this was written, 19 servers were running and
+    # exactly 1 of them appeared here. Reporting "1 server running" without
+    # this line would be a diagnostic that quietly under-counts.
+    click.echo("    Lower bound: only servers started on this version or later register here.")
+    if live:
+        if drift:
+            versions = ", ".join(f"{n}x {v}" for v, n in drift.items())
+            warn(f"{stale_count} server(s) still executing older code: {versions}")
+            click.echo("    A server keeps its modules in memory for life, so an upgrade")
+            click.echo("    reaches an open Claude Code session only when that session")
+            click.echo("    restarts. Restart them to pick up the installed version.")
+            for entry in live:
+                version = str(entry.get("version") or "unknown")
+                if version != __version__:
+                    started = entry.get("started_at")
+                    age = f", up {_age(usage_mod.as_float(started))}" if started else ""
+                    click.echo(f"      pid {entry.get('pid')}: {version}{age}")
+
     section("Config")
     cp = config_path()
     config: DispatchConfig | None = None
@@ -1180,6 +1211,91 @@ def jobs_gc(days: int, purge_all: bool) -> None:
     click.echo(f"Deleted {deleted} job(s) older than {days} day(s).")
 
 
+def _fmt_seconds(ms: float) -> str:
+    """Human duration from milliseconds: 850ms, 42s, 3m20s."""
+    seconds = ms / 1000
+    if seconds < 1:
+        return f"{int(ms)}ms"
+    if seconds < 90:
+        return f"{seconds:.0f}s"
+    return f"{int(seconds) // 60}m{int(seconds) % 60:02d}s"
+
+
+def _fmt_counts(counts: dict[str, int]) -> str:
+    return ", ".join(f"{k} {v}" for k, v in counts.items())
+
+
+@cli.command("stats")
+@click.option("--days", default=0, type=int, help="Only count the last N days (default: all).")
+@click.option("--agent", default=None, help="Only this agent.")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable output.")
+def usage_stats(days: int, agent: str | None, as_json: bool) -> None:
+    """Show what dispatches actually cost: spend, durations, outcomes per agent."""
+    from . import usage
+
+    if days < 0:
+        click.echo(click.style(f"Error: --days must be >= 0 (got {days}).", fg="red"))
+        raise SystemExit(1)
+
+    entries = usage.load(days=days, agent=agent)
+    report = usage.summarize(entries)
+    if as_json:
+        # Always valid JSON, including the empty case — a caller piping this
+        # into a parser must not get prose on a fresh install, which is
+        # exactly when the journal is empty.
+        click.echo(json.dumps(report, indent=2, ensure_ascii=False))
+        return
+    if not entries:
+        window = f" in the last {days} day(s)" if days else ""
+        who = f" for agent '{agent}'" if agent else ""
+        click.echo(f"No dispatches recorded{who}{window}.")
+        click.echo(f"    Journal: {usage.journal_path()}")
+        click.echo("    (Recording is off if settings.usage_log is false in agents.yaml.)")
+        return
+
+    total = report["total"]
+    window = f"last {days} day(s)" if days else "all recorded"
+    click.echo(click.style(f"Usage ({window})", bold=True))
+    cached = f", {total['cached_hits']} served from cache" if total["cached_hits"] else ""
+    click.echo(f"  dispatches: {total['dispatches']}{cached}")
+    click.echo(f"  spend:      ${total['cost_usd']:.4f}")
+    if "median_ms" in total:
+        click.echo(
+            f"  duration:   median {_fmt_seconds(total['median_ms'])}, "
+            f"p90 {_fmt_seconds(total['p90_ms'])}, max {_fmt_seconds(total['max_ms'])}"
+        )
+    if total.get("outcomes"):
+        click.echo(f"  outcomes:   {_fmt_counts(total['outcomes'])}")
+    if total.get("errors"):
+        click.echo(click.style(f"  failures:   {_fmt_counts(total['errors'])}", fg="yellow"))
+
+    click.echo()
+    click.echo(click.style("Per agent", bold=True))
+    for name, st in report["agents"].items():
+        head = (
+            f"  {click.style(name, bold=True):<24} {st['dispatches']:>4} "
+            f"{'run ' if st['dispatches'] == 1 else 'runs'}  "
+            f"${st['cost_usd']:>8.4f}"
+        )
+        if "median_ms" in st:
+            head += (
+                f"  median {_fmt_seconds(st['median_ms']):>6}  p90 {_fmt_seconds(st['p90_ms']):>6}"
+            )
+        click.echo(head)
+        detail = []
+        if st.get("outcomes"):
+            detail.append(_fmt_counts(st["outcomes"]))
+        if st.get("errors"):
+            detail.append(click.style(_fmt_counts(st["errors"]), fg="yellow"))
+        if st["cached_hits"]:
+            detail.append(f"{st['cached_hits']} cached")
+        if detail:
+            click.echo(f"      {'  |  '.join(detail)}")
+
+    click.echo()
+    click.echo(f"Journal: {usage.journal_path()}")
+
+
 @cli.command()
 def serve() -> None:
     """Start the MCP server (stdio transport)."""

{agent_dispatch-0.14.0 → agent_dispatch-0.15.1}/src/agent_dispatch/models.py

@@ -119,6 +119,13 @@ class Settings(BaseModel):
     # (parsed into DispatchResult.outcome). Off = raw `claude -p` behaviour,
     # for CLIs that predate --append-system-prompt or for A/B comparison.
     dispatch_protocol: bool = True
+    # Append one line per dispatch to <config dir>/usage.jsonl: agent, ok,
+    # cost, duration, turns, outcome, error type, caller. It is what makes
+    # "which agent burns money / how long does this one actually take"
+    # answerable (CLI `stats`, the timing block in inspect_agent, the
+    # timeout hint's suggested value). Owner-only, rotated at ~2 MB, and
+    # written with a single atomic append so concurrent servers can share it.
+    usage_log: bool = True
 
 
 def validate_agent_name(name: str) -> str: