show what pi agents cost today, this week and this month, counting forked replies once

1 files changed, 18 insertions, 4 deletions

diff --git a/README.md b/README.md
index 9f3a9af..4b1eeb2 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,19 @@ than a poll is still a completion.
   `/unread`, and `! dingger unread` does not work in it: Claude (2.1.311)
   answers a `!` command with a model turn, so the agent is working and the
   mark is refused. Use the panel or search for Claude agents.
+- **What agents cost** (pi): the menu's top line totals what pi agents
+  spent today, this week, and this month (`$8.86 today · $457 this week ·
+  $8.86 this month`); each agent's line adds what its session spent today
+  (menu, panel, search), and `dingger status` shows both. Periods start at
+  00:00 UTC (a week on Monday, a month on its 1st). The daemon reads pi's
+  session files (`~/.pi/agent/sessions`, and those of running agents
+  elsewhere) in a thread of its own every 15 seconds, only what was
+  appended since. Each reply counts once, for the session it first appeared
+  in: a fork (`/fork`, `pi --fork`) copies its parent's replies into its
+  own file, and summing every file would count them again (in one month
+  here, $1,024 of $2,991). The totals include agents since closed or
+  started over. Amounts are what pi prices each reply at (its model
+  configuration); Claude Code records no prices, so it is not counted.
 - **Forgotten drafts** (pi): an agent with text left in its input box shows
   `✎` before its name wherever you are not looking at it (where you look,
   you may be typing it). Idle agents with one come first among idle agents;
@@ -148,8 +161,8 @@ than a poll is still a completion.
 
 All per-pane state lives in tmux pane options (`@agent_state`,
 `@dingger_since`, `@dingger_hook`, `@dingger_importance`,
-`@dingger_extension`, `@dingger_control`, `@dingger_draft`), so
-restarting dingger loses nothing.
+`@dingger_extension`, `@dingger_control`, `@dingger_draft`,
+`@dingger_cost`), so restarting dingger loses nothing.
 
 ### Keeping pi agents on the current extension
 
@@ -184,7 +197,7 @@ session as a custom entry of type `dingger-importance`.
 
 ```bash
 dingger watch                 # the daemon (run by launchd, see below)
-dingger status                # agents in priority order
+dingger status                # agents in priority order, with what they spent
 dingger focus [--pane ID]     # jump to an agent (default: the top waiter)
 dingger importance [LEVEL]    # an agent's importance: high, normal, low
 dingger unread [--pane ID]    # mark an idle agent unread (done again)
@@ -257,7 +270,8 @@ covers identification, the extension's state and session reports, a turn,
 `/reload`, an extension's blocked event, screen detection without the
 extension, restore, reloading an agent on an old extension (and refusing
 while busy or with a draft), drafts (reported, cleared, kept across a
-crash and put back by restore), and exit. To try a release without installing it:
+crash and put back by restore), cost (priced replies, counted once across
+a real `pi --fork`), and exit. To try a release without installing it:
 `npm install --prefix /tmp/pi-next @earendil-works/pi-coding-agent@<version>`
 (through `sfw`), then `tests/pi-live.sh /tmp/pi-next/node_modules/.bin/pi`.