@monster-orange/den 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -4,6 +4,180 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.9] - 2026-11-07
+
+A session ends when its pull request merges, or after 3 compactions. The
+role then relaunches from a handoff, in a fresh conversation (den#4, the
+session-rotation issue). Sessions that never end re-read huge contexts on
+every call. This keeps each session to one objective.
+
+### Added
+
+- **Den counts compactions.** A `SessionStart` hook (source `compact`),
+  alongside Den's other hooks for default-pack Claude Code agents, counts
+  each compaction of the agent's conversation once it happened. A
+  `/compact` that does nothing is not counted. The count is in
+  `<state dir>/agent-files/<id>/rotation.json`, and starts at 0 for each
+  new conversation.
+- **Two triggers.** A rotation is due after `agents.rotate.after_compactions`
+  compactions (default 3), or once the agent's pull request merged (the
+  `prMerged` outcome from `usage agents`). A merge counts only when the
+  agent ran `gh pr merge` itself, it exited 0, and `gh pr view` then says
+  MERGED. `echo gh pr merge 1` or `gh pr merge --help` never counts.
+- **The agent is told.** The compaction summary keeps the instruction, a
+  `SessionStart` hook adds it after the compaction, and the `Stop` hook
+  blocks once until the handoff is written. The shared instructions say
+  what to do: write `handoff.md` in the agent's files folder, then end the
+  turn.
+- **The handoff check.** A handoff has five parts: Objective, State, Open
+  items, How to QA, Next step. Each must be there and filled in, and every
+  ID explained. `<cli> agents handoff-check <id|file|->` runs the check (on an
+  agent's own handoff.md, by its id) and names what is missing.
+- **Relaunch from handoff.** A fresh conversation (a new conversation id),
+  with the same persona, workspace, folder and grants. Its first prompt is
+  the handoff. The handoff is then kept in `handoffs/`, and the record
+  notes the rotation. `<cli> agents relaunch <id>`, and
+  `POST /api/workspaces/<ws>/agents/<id>/relaunch`.
+- **The Agents page.** A rotated agent reads "Ready to relaunch (3
+  compactions)" or "Ready to relaunch (PR merged)". Its buttons are
+  Relaunch from handoff (the primary one), Start fresh and Remove. With no
+  handoff, or one that fails the check, the row says so and keeps Resume
+  and Start fresh. A running agent shows "Handoff due" or "Ready to
+  relaunch" as a tag.
+- **`agents.rotate` in the org config**: `after_compactions` (1 to 100,
+  default 3) and `standing` (default true). With `standing: false`,
+  standing personas such as the planner never rotate.
+- **Usage shows rotation.** `usage agents` adds each agent's compactions
+  and rotations. `usage report` adds `long_session_context_k`,
+  `never_ending_reread_pct` and `rotations`.
+
+### Changed
+
+- **Resume refuses a rotated conversation.** Once a rotation is due and the
+  handoff passes, `agents resume <id>` exits 1 with
+  `Relaunch from handoff: <cli> agents relaunch <id>`. The resume route
+  answers 409 with code `rotated`. Resume all lists it as not resumed.
+- **A standing persona that rotated relaunches on its own** after a
+  restart, as it resumed on its own before.
+- **The `Stop` hook and the new hooks take the agent's files folder** on
+  their command line (`--files <dir> --after <n>`).
+
+### Metrics (before → after)
+
+- Peak tokens per call in a long session: 365–510k → <150k.
+- Share of context re-reads from never-ending sessions: 59% → <15%.
+- How it is measured: `usage report` on this machine.
+  `long_session_context_k` is the highest average tokens per call of any
+  session. `never_ending_reread_pct` is the share of cache re-reads from
+  sessions that compacted more than `agents.rotate.after_compactions`
+  times. Compare a week's report before and after.
+- On the test fixture (15 sessions with 16 compactions each, and 127 that
+  end within 3): 399k → 139k per call, and 59% → 0% of re-reads. The same
+  calls re-read fewer tokens.
+
+### Migrations
+
+- None needed. Rotation is on for Den's default pack, with 3 compactions.
+  To change the number, set `agents.rotate.after_compactions`. To keep
+  standing personas from rotating, set `agents.rotate.standing: false`.
+  `rotate` is now a reserved key under `agents:`, so no agent can have the
+  id `rotate`. Agents started before 0.4.9 start counting at their next
+  start or resume.
+
+## [0.4.8] - 2026-11-07
+
+Stopped agents stay in the list, and come back where they were (AG-14, the
+stopped-agents slice). Den also counts what each agent used and what it
+got done, read on this machine only (den#6, the agent-usage issue).
+
+### Added
+
+- **Stopped agents stay listed.** They sit below the running ones, each
+  with why it stopped: stopped by you, exited (with its code), or
+  interrupted by a restart. Each row has Resume, Start fresh and Remove.
+- **Resume is the same conversation.** Den runs the runtime's own resume
+  with the conversation id it saved (Claude Code: `--resume <id>`). The
+  agent comes back in its own folder, with its workspace and grants. A
+  runtime that can't resume (codex, gemini, grok), or an agent with no
+  saved id, offers Start fresh only and says why.
+- **Remove in one click, with Undo.** The toast offers Undo for 10 seconds.
+  **Clear stopped** removes every stopped agent in view. A running agent
+  is never removed.
+- **After a restart, one line.** "2 agents were interrupted when Acme
+  restarted · Resume all · Review". Standing personas, and personas with
+  `resume_on_restart: true`, resume on their own.
+- **The CLI:** `agents list --stopped`, `agents resume --all-interrupted`,
+  `agents rm <id>` and `agents rm --stopped`.
+- **`agent_resume`, an MCP action for orchestrators.** Off unless
+  `mcp.actions` names it. It resumes agents of its own workspace or a
+  granted one, never itself. The web server checks the same rule.
+- **`usage agents` and `usage report`.** Each agent's tokens and outcome
+  (pull request opened or merged, tests green, wall-clock time) are read
+  from its transcripts and saved in its record, matched by the
+  conversation id. `usage report` writes a weekly summary, compared with
+  the last. Transcripts stay on the machine, and only counts are kept.
+- **The `usage` plugin kind** (server tier) adds a transcript reader for
+  another runtime. Den ships one for Claude Code.
+
+### Changed
+
+- **The audit trail survives a restart.** The last 200 actions are kept in
+  `<state dir>/audit.jsonl` (0600) and read back at start.
+- **An agent after a restart says Interrupted**, not Exited. An agent that
+  exited says Exited (code n), even after the session host forgets it.
+- **An agent record notes its grants**, its end and exit code, and its
+  usage and outcome.
+
+### Fixed
+
+- **A resume never loses the conversation.** Stopping an agent without
+  typing, then resuming it, could fail for good: Den started a new
+  conversation under the same id, and Claude Code refused it as "already
+  in use". Now Den decides before it launches. For Claude Code it looks
+  for the conversation's transcript: if it is there, or someone typed in
+  the last session, it resumes with `--resume <id>`; if not, it starts
+  fresh under the same id, in the same folder and scope, and says "nothing
+  to resume yet; started fresh". Every launch also marks the record
+  `launched: true`, for runtimes Den can't check this way. If Claude Code
+  still says there is no conversation (Den now reads past its trailing
+  terminal codes), Den starts fresh once. If a
+  fresh start says the id is in use, Den resumes once instead. If both
+  fail, the error names the id and Start fresh (the route answers 502
+  `resume_failed`).
+- **No "+ Start agent" for a workspace that doesn't exist** (`?ws=` with
+  an unknown name).
+- **`agents stop` waits for the agent to end.** It returns once the
+  agent's session has ended, so `agents stop X && agents resume X` works.
+  It waits up to 5 seconds. Still running then, it prints
+  `X is still stopping` and exits 1. `--no-wait` returns at once, as
+  before. The stop route answers 200 with `stopped: true` once the session
+  has ended, or 202 with `stillStopping: true`.
+- **The Agents page never shows All in place of its `?ws=`.** A workspace
+  that isn't active gets one line, "Workspace west isn't active · Switch
+  to west", and the list shows that workspace alone. Clear stopped acts on
+  exactly the workspaces listed. A name no workspace has gets the same
+  line and an empty list.
+- **Den's sudo is `/usr/bin/sudo`.** A `sudo` placed earlier on `PATH` no
+  longer gets the admin password. Den looks on `PATH` only when there is no
+  `/usr/bin/sudo`. `DEN_SYSTEM_SUDO` names another absolute path.
+- **`mcp` refuses an argument it doesn't take.** A typo such as
+  `--worksapce` exits 2 with the usage, instead of starting an unscoped
+  server.
+
+### Metrics (before → after)
+
+- Share of agent sessions with attributed tokens and outcome: ~0 → ≥90%.
+  On the test fixture (11 agents): 0% → 91%. The one left out runs on
+  codex, which no usage reader covers yet.
+
+### Migrations
+
+- None needed. To remove stopped agents on their own, set
+  `agents.remove_stopped_after` in `config/local/user.yml` to `1d` or `7d`
+  (the default is `never`). Interrupted agents are never removed this way.
+  To let an orchestrator resume agents, add `agent_resume` to
+  `mcp.actions`.
+
 ## [0.4.7] - 2026-11-07
 
 Agents read slices, wait in the background and hand back plainly (den#5,

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.7/hero-dark.png">
-  <img src="docs/images/0.4.7/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.9/hero-dark.png">
+  <img src="docs/images/0.4.9/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -38,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.7/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.9/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.7/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.7/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.7/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.7/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.9/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.9/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.9/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.9/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -497,6 +497,11 @@ in the distribution's config always wins over the one in user.yml.
 `backendAvailable`, `reason` and `hasStored` (`opAvailable` is a
 deprecated alias of `backendAvailable`, kept for one minor).
 
+**Den's sudo is `/usr/bin/sudo`.** Den checks and caches the admin
+password with `/usr/bin/sudo` only, never a `sudo` found earlier on `PATH`.
+Only on a machine with no `/usr/bin/sudo` does it look on `PATH`.
+`DEN_SYSTEM_SUDO=<absolute path>` names another system sudo.
+
 The admin password is for sudo, and nothing else (LK-0). It is no sign-in
 and no access check: starting, stopping and resuming agents, sessions and
 terminals, and a service whose commands run no sudo, never ask for it.
@@ -1836,6 +1841,9 @@ the server: only registered tools (so actions only as named in
 the tool's text to stdout and exits 1 when the tool reports an error (a
 refusal, a failed action, the web server down).
 
+`mcp` takes only the arguments its usage lists. Any other (a typo such as
+`--worksapce`) exits 2 with the usage, before anything starts.
+
 ### Config
 
 Without an `mcp:` block in the org config (`config/<name>.yml`) only the read
@@ -1918,6 +1926,12 @@ Action tools (only those named in `mcp.actions`): `service_up`,
 `workspace_sync` (`/api/workspace/sync`) and `run_tests` (`/api/run`). There
 is no deploy tool.
 
+`agent_resume` (AG-14.4) resumes a stopped or interrupted agent, for an
+orchestrator. It is off unless `mcp.actions` names it. A scoped server
+(`--workspace`) resumes agents of its own workspace or a granted one, never
+itself. The web server checks the same rule, and the resume route is the
+only agent route an agent's token reaches.
+
 ### Guards
 
 - **Lifecycle only, local only.** The service tools run a manifest's `up`,
@@ -2103,7 +2117,14 @@ The routes: `GET /api/workspaces/<ws>/agents`, `POST
 agent of the workspaces in view, and their terminals in the browser.
 
 - **The list** is grouped by workspace and follows the scope bar (or the
-  page's `?ws=<ws>`, which "Open in Agents →" sets). Each row has its
+  page's `?ws=<ws>`, which "Open in Agents →" sets). A `?ws=` is never
+  replaced by All. A workspace that isn't active gets one line, "Workspace
+  west isn't active · Switch to west", and the list shows it alone.
+  Switch makes it active and views it, as the top bar's Workspace menu
+  does. A name no workspace has gets the same line, an empty list, and no
+  "+ Start agent".
+  `GET /api/sessions?ws=<ws>` lists that workspace even when it isn't
+  active, and says `requested: { workspace, active, known }`. Each row has its
   state, persona (a `sessions start` session is labelled "session"),
   runtime and directory, and "waiting" when it waits on you (once the
   session host can tell, AG-6a; not yet). An agent whose
@@ -2139,6 +2160,84 @@ text frame `{"type":"resize","cols":c,"rows":r}` resizes, and the server
 sends `{"type":"session",…}` first and `{"type":"exit","exitCode":n}` when
 the session ends.
 
+### Stopped agents: Resume, Start fresh, Remove
+
+An agent that stops stays in the list, below the running ones (AG-14, the
+stopped-agents slice). Its row says why it stopped: "Stopped by you",
+"Exited (code n)", or "Interrupted" when Den or the machine restarted under
+it. Each row has three buttons:
+
+- **Resume** continues the same conversation. Den runs the runtime's own
+  resume with the conversation id it saved (Claude Code: `--resume <id>`).
+  The agent comes back in the folder it had, with its workspace and its
+  grants. A grant you took out of the config since is gone; one you added
+  is not taken. Resume is never a new conversation fed the old prompt.
+  Den decides before it launches. For Claude Code it looks for the
+  conversation's transcript (`<id>.jsonl` under
+  `$CLAUDE_CONFIG_DIR/projects`, else `~/.claude/projects`): if it is
+  there, or someone typed in the last session, the resume is
+  `--resume <id>`. If not, nobody ever typed, so Den starts fresh under the
+  same id, folder and scope, and says "nothing to resume yet; started
+  fresh" (the route adds `fresh: true`). For a runtime Den can't check,
+  the record decides: every launch marks it `launched: true`, and a
+  launched record resumes. As a backstop, if the runtime still says there
+  is no conversation, Den starts fresh once and says so.
+  If a fresh start says the id is already in use, Den resumes once
+  instead. If both fail, the CLI exits 1 and the route answers 502 with
+  code `resume_failed`, naming the id and Start fresh.
+- **Start fresh** starts a new conversation: same persona, workspace and id.
+- **Remove** takes the row away in one click. The toast offers **Undo** for
+  10 seconds. Den keeps the removed record for an hour, then forgets it. It
+  never touches the runtime's own history.
+
+**Stop waits for the agent to end.** `agents stop <id>` returns once the
+session has ended, so a resume right after it works. It waits up to 5
+seconds. If the session is still running then, it prints `<id> is still
+stopping` and exits 1. `--no-wait` returns once TERM is sent. The route
+`POST /api/workspaces/<ws>/agents/<id>/stop` answers the same way: 200
+with `{ ok, agent, wasRunning, stopped: true }` once the session has
+ended, or 202 with `stopped: false, stillStopping: true`.
+
+A runtime that can't resume (codex, gemini, grok), or an agent with no
+saved conversation id, shows only Start fresh, and says why. **Clear
+stopped**, beside + Start agent, removes every stopped agent in view. A
+running agent is never removed: stop it first. None of this asks for the
+admin password.
+
+**After a restart**, the agents it cut off show Interrupted, and one line
+sits above the list: "2 agents were interrupted when Acme restarted ·
+Resume all · Review". Resume all resumes each one that can. Review marks
+them and moves to the first. Agents whose persona is `standing: true`, or
+has `resume_on_restart: true`, resume on their own when the web server
+starts.
+
+**Removed on their own.** Stopped agents can go after a while:
+
+```yaml
+# config/local/user.yml
+agents:
+  remove_stopped_after: 7d # never (the default), 1d or 7d
+```
+
+An interrupted agent is never removed this way. Any other value fails,
+naming the key.
+
+The CLI does the same:
+
+```sh
+./bin/acme agents list --stopped            # only the stopped ones
+./bin/acme agents resume planner            # the same conversation
+./bin/acme agents resume --all-interrupted  # every interrupted one that can
+./bin/acme agents rm planner                # one stopped agent
+./bin/acme agents rm --stopped [-w north]   # every stopped one
+```
+
+The routes (a person's only, audited): `POST
+/api/workspaces/<ws>/agents/<id>/resume`, `…/fresh` and `…/remove`, and
+`POST /api/agents/clear-stopped` (`{ workspaces }`), `/api/agents/restore`
+(`{ agents }`, the Undo) and `/api/agents/resume-interrupted` (`{
+workspaces }`).
+
 ### An agent's environment
 
 An agent's environment starts empty and gets, in order:
@@ -2302,6 +2401,11 @@ Den never writes your `~/.claude`; your own hooks still run.
   going (Claude Code's `decision: "block"`). It never blocks twice in a
   row (`stop_hook_active`), so it can't loop. Den adds no `SubagentStop` hook: a subagent reports to its parent
   agent, not to a person.
+- `PreCompact`, and `SessionStart` after a compaction or on resume
+  (`rotation-hook.ts`), count the conversation's compactions (on
+  `SessionStart` after a compaction only) and ask for a handoff once a
+  rotation is due. See Session rotation, below. While one is
+  due, the `Stop` hook also blocks once until `handoff.md` passes.
 
 **The hand-back template**, which the check enforces:
 
@@ -2355,6 +2459,108 @@ A persona of yours that replaces a default one (same id) takes your
 pack's setting, not Den's pack's. Anything but `true` or `false`, or an
 unknown key, is an error naming the key.
 
+### Session rotation: one session per objective
+
+A session that never ends re-reads its whole context on every call. So a
+session ends when its pull request merges, or after a few compactions. Its
+role then relaunches in a fresh conversation, from a handoff the session
+wrote. This is rule R2 (one session per objective) of the agent-loop
+report. It works on den-claude for personas with Den's hooks on.
+
+**How it works.**
+
+1. Den's hooks count compactions. A `SessionStart` hook with source
+   `compact` (`guardrails/rotation-hook.ts`) adds one to
+   `<stateDir>/agent-files/<id>/rotation.json` after every compaction,
+   manual or automatic. It fires only once a compaction happened.
+   `PreCompact` does not count: it also runs for a `/compact` that does
+   nothing ("Not enough messages to compact"). The count belongs to one
+   conversation, and starts at 0 for a new one.
+2. A trigger fires. Either the count reaches
+   `agents.rotate.after_compactions` (default 3), or the agent's pull
+   request merged (the `prMerged` outcome that `<cli> usage agents` saves).
+   A merge is never taken from text. The agent must have run `gh pr merge`
+   as a command (after any `cd` or `VAR=value` prefix; not `--help`, not
+   `echo gh pr merge`), and it must have exited 0. Then `usage` asks
+   `gh pr view <ref> --json state` in the agent's folder, and only
+   `MERGED` counts. With no gh, or on any error, it is not marked. That
+   query is the one thing `usage` asks outside this machine; it says so
+   when it does.
+3. Den tells the agent. The `PreCompact` hook's output asks the compaction
+   summary to keep the instruction. A `SessionStart` hook (after a
+   compaction, or on resume) adds it to the context. The `Stop` hook blocks
+   the turn once while the handoff is missing or fails the check. The
+   instruction: write `handoff.md` in the agent's files folder, then end
+   the turn.
+4. Den relaunches the role. **Relaunch from handoff** starts a fresh
+   conversation (a new conversation id) with the same persona, workspace,
+   folder and grants. Its first prompt is the handoff. The handoff moves to
+   `agent-files/<id>/handoffs/`, and the record notes the rotation.
+
+**The handoff** has five parts, each a heading, each filled in. Write it
+plainly, and explain every ID, as in a hand-back. It must stay under 20,000
+characters, since it becomes a first prompt.
+
+```markdown
+## Objective
+
+<what the work is for>
+
+## State
+
+<what is done, and where it is: branch, pull request, files>
+
+## Open items
+
+<what is left; or none>
+
+## How to QA
+
+<the steps to see it working>
+
+## Next step
+
+<the one thing to do first>
+```
+
+`<cli> agents handoff-check <id|file|-> [--json]` runs the check, on an
+agent's `handoff.md` (by its id), a file, or stdin: exit 0 when
+it passes, 1 with each missing or empty part and each unexplained ID. A
+part can also be a line such as `Next step: open the PR`.
+
+**Resume after a rotation.** Once a rotation is due and `handoff.md`
+passes, Den declines a plain Resume of that conversation:
+
+- The Agents page shows the row as "Ready to relaunch (3 compactions)" or
+  "Ready to relaunch (PR merged)". Its buttons are Relaunch from handoff
+  (the primary one), Start fresh and Remove.
+- `<cli> agents resume <id>` refuses (exit 1) and prints
+  `Relaunch from handoff: <cli> agents relaunch <id>`. The resume route
+  answers 409 with code `rotated`.
+- `<cli> agents relaunch <id> [-w <ws>]` and
+  `POST /api/workspaces/<ws>/agents/<id>/relaunch` relaunch it. A running
+  rotated agent is stopped first.
+- With `handoff.md` missing or failing the check, the row says so, and
+  Resume and Start fresh stay. Resume the agent to write or fix it.
+  Relaunch says what is wrong (409 `no_handoff`) and names Start fresh.
+- After a restart, a standing persona that rotated relaunches on its own,
+  as a standing persona resumes on its own.
+
+**Settings**, in the org config:
+
+```yaml
+agents:
+  rotate:
+    after_compactions: 3 # 1 to 100; the default is 3
+    standing: true # standing personas rotate too (the default)
+```
+
+`standing` is for standing personas, such as the planner and the
+orchestrator. With `true` (the default), they rotate like the rest: only
+their context resets, and they keep their id and workspace. With `false`,
+they never rotate. A setting takes effect at the agent's next start or
+relaunch. An unknown key, or a bad value, is an error naming the key.
+
 ### Runtimes
 
 `<cli> doctor` lists the runtime kind. Den knows the runtimes in its
@@ -2547,6 +2753,42 @@ Only the boolean `true` counts. With it, and a Sentry DSN in
 also sent, best effort. A DSN on its own never sends. `CI=true` and
 `DEV_METRICS_DISABLED=1` stop sending even when opted in.
 
+## Agent usage: tokens and outcomes, read locally
+
+`<cli> usage agents [-w <ws>] [--json]` reads each agent's transcripts on
+this machine and saves its tokens and outcome in its record: the pull
+request it opened, whether it merged, whether its last test run passed,
+and its wall-clock time. It matches transcripts to agents by the
+conversation id Den saved at start. It prints the share of agents with
+both. Transcripts never leave the machine, and their text is never kept:
+only counts. "Whether it merged" is checked: when an agent ran
+`gh pr merge`, `usage` asks `gh pr view <ref> --json state` to confirm it.
+That query, the pull request's number or URL, is the only thing it asks
+outside, and the output says when it asked.
+
+`<cli> usage report [--days 7] [--json]` writes a weekly summary to
+`<state dir>/usage/<date>.json` and `.md`, compared with the last one:
+calls, cache re-reads, polls, sleeps, compactions, corrections and the
+attributed share.
+
+For session rotation, `usage agents` also shows each agent's compactions
+(in its current conversation) and rotations (how many times Den relaunched
+it from a handoff). A merged pull request makes the agent's rotation due.
+`usage report` adds three numbers:
+
+- `long_session_context_k`: the highest average tokens per call of any
+  session in the window, in thousands. A call's tokens are its input,
+  cache reads and cache writes.
+- `never_ending_reread_pct`: the share of cache re-reads that came from
+  never-ending sessions. A never-ending session compacted more often than
+  `agents.rotate.after_compactions`.
+- `rotations`: relaunches from a handoff, over the agents listed.
+
+Den reads Claude Code's transcripts (`$CLAUDE_CONFIG_DIR/projects`, else
+`~/.claude/projects`). A plugin can add a reader for another runtime with
+the `usage` kind (server tier). A runtime with no reader shows "no usage
+source reads <runtime>".
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/schemas/den.plugin.v1.json

@@ -70,7 +70,7 @@
       "pattern": "^(?!/)(?!.*\\.\\.)[A-Za-z0-9._/-]+$"
     },
     "kind": {
-      "description": "files tier: theme, catalog, persona-pack. browser tier: page. server tier: mcp-tools, work-items, runtime, session-backend, notifier, secrets, identity, health-source.",
+      "description": "files tier: theme, catalog, persona-pack. browser tier: page. server tier: mcp-tools, work-items, runtime, session-backend, notifier, secrets, identity, health-source, usage.",
       "enum": [
         "theme",
         "catalog",
@@ -83,7 +83,8 @@
         "notifier",
         "secrets",
         "identity",
-        "health-source"
+        "health-source",
+        "usage"
       ]
     },
     "provide": {

package/src/shared/agents/den-claude.ts

@@ -21,6 +21,11 @@
  *   alongside any hooks the user has; Den never writes ~/.claude.
  * - Each launch picks a fresh conversation id (--session-id); resume
  *   continues it with --resume <id>, in the same cwd, with the same MCP.
+ *   A relaunch from handoff (den#4) is a launch whose first prompt, the
+ *   last argument, is the handoff.
+ * - Session rotation (den#4): the hooks include PreCompact and
+ *   SessionStart (rotation-hook.ts) with the agent's files dir and its
+ *   limit (LaunchInput rotateAfter), so its compactions are counted there.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
  *   --permission-mode default, unless the persona's `permission_mode` sets
  *   one of Claude Code's modes; bypassPermissions warns at every start. The
@@ -45,7 +50,8 @@ import * as fs from "fs";
 import * as path from "path";
 import { configuredRuntimeBin } from "../den-config.js";
 import { rolePrompt } from "./personas.js";
-import { guardrailHooks } from "./guardrails.js";
+import { GUARDRAILS_DIR, guardrailHooks, hookCommands } from "./guardrails.js";
+import { DEFAULT_ROTATE } from "./rotation.js";
 import {
   LaunchError,
   mcpConfigJson,
@@ -59,6 +65,7 @@ import {
 import { builtinEntry } from "./catalog.js";
 import { catalogFind } from "./catalog-runtime.js";
 import { locateRuntime, type RuntimeFind } from "./runtime-search.js";
+import { claudeProjectsDir } from "../usage/paths.js";
 
 export const DEN_CLAUDE_ID = "den-claude";
 const BIN = "claude";
@@ -226,7 +233,16 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
-  const hooks = input.persona.guardrails?.hooks ? guardrailHooks() : null;
+  // den#4: the rotation hooks count this agent's compactions in its files dir.
+  const hooks = input.persona.guardrails?.hooks
+    ? guardrailHooks(
+        GUARDRAILS_DIR,
+        hookCommands(GUARDRAILS_DIR, process.execPath, {
+          files: input.filesDir,
+          after: input.rotateAfter ?? DEFAULT_ROTATE.afterCompactions,
+        }),
+      )
+    : null;
   const settings = input.stateDir || hooks ? settingsPath(input) : null;
   return {
     argv: [
@@ -286,20 +302,40 @@ function binFor(input: LaunchInput): string {
   return d.path;
 }
 
+/**
+ * The first prompt as claude's last argument, or nothing. An agent wrote
+ * the text (its handoff), so it is never allowed to start with "-": that
+ * would be read as a flag. One that does gets a word in front.
+ */
+export function firstPromptArg(text: string | undefined): string[] {
+  const t = text?.trim();
+  if (!t) return [];
+  return [t.startsWith("-") ? `Prompt: ${t}` : t];
+}
+
 export const denClaude: Runtime = {
   id: DEN_CLAUDE_ID,
   label: DEN_CLAUDE_CATALOG.name,
   vendor: DEN_CLAUDE_CATALOG.vendor,
   catalog: DEN_CLAUDE_CATALOG,
   denTools: true,
+  firstPrompt: true,
   find: DEN_CLAUDE_FIND,
   detect,
   launch(input): LaunchOutput {
     const bin = binFor(input);
     const id = input.resumeToken ?? randomUUID();
     const c = common(input);
+    // A relaunch from handoff (den#4): the handoff is the first prompt,
+    // the last argument (firstPromptArg: never read as a flag).
     return {
-      argv: [bin, "--session-id", id, ...c.argv],
+      argv: [
+        bin,
+        "--session-id",
+        id,
+        ...c.argv,
+        ...firstPromptArg(input.firstPrompt),
+      ],
       env: {},
       files: c.files,
       resumeToken: id,
@@ -317,6 +353,24 @@ export const denClaude: Runtime = {
       warnings: c.warnings,
     };
   },
+  // Its transcript, <token>.jsonl in any project under its projects dir.
+  conversationExists(token, env = process.env) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(token)) return false;
+    const root = claudeProjectsDir(env);
+    let projects: string[] = [];
+    try {
+      projects = fs.readdirSync(root);
+    } catch {
+      return false;
+    }
+    return projects.some((p) =>
+      fs.existsSync(path.join(root, p, `${token}.jsonl`)),
+    );
+  },
+  launchFailures: {
+    noConversation: /no conversation found/i,
+    idInUse: /already in use/i,
+  },
   approvals: "terminal",
   envPassthrough: ["CLAUDE_CONFIG_DIR"],
   // Claude Code's session plumbing: the session id, its messaging socket and