@monster-orange/den 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -4,6 +4,166 @@ 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.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,
+the default-pack guardrails issue). Every persona in Den's default pack
+gets Den's shared instructions and, on Claude Code, Den's hooks, with no
+setup. `doctor` warns about polling loops it sees in the local dev metrics.
+
+### Added
+
+- **The Stop hook reads every last message.** With a `## Hand-back`
+  heading it checks the whole hand-back, as before. Any other last message
+  gets the plain-writing check: every ID explained. It still never blocks
+  twice in a row.
+- **`URL: none` in a hand-back.** Work with no page (a CLI change, a
+  refused request) says `URL: none`, with a reason if it likes. An empty
+  or missing URL still fails.
+
+- **`down --json` and `web down --json`.** The clean-up steps answer in
+  JSON like every other onboarding step: `{ ok, workspace, services }` and
+  `{ ok, url, port, running, stopped }`. Both are safe to re-run.
+
+- **Hooks for default-pack agents.** A Claude Code agent from Den's default
+  pack runs with Den's own hooks, in its own `--settings` file (never your
+  `~/.claude`). A `PreToolUse` hook on Bash and Read blocks reading all of
+  a log or a large file into the conversation (`cat`, `less`, `tail` from
+  a line such as `tail +1`, a Read with no limit; a plain `tail` passes) and says to read a slice or use a
+  subagent. It blocks a foreground `sleep`, alone or in an `until`/`while`/
+  `for` loop, and says to run in the background or use a wait primitive.
+  It blocks nothing else.
+- **Shared persona instructions.** Every default-pack persona's role prompt
+  ends with Den's `guardrails/instructions.md`: write plainly, in short
+  sentences; say what every issue or ID is; ask each decision as a numbered
+  yes/no question; no caveat sections; and the hand-back template (URL,
+  machine, branch, what changed, what to click, decisions).
+- **The hand-back check.** `<cli> agents handback-check <file|->` rejects a
+  hand-back with a missing part, an unexplained ID, or a decision that is
+  not a numbered yes/no question, and says what to fix. A `Stop` hook runs
+  the same check on a turn that ends with a `Hand-back` heading, and sends
+  Claude back to fix it once.
+- **doctor warns about polling loops.** It reads the end of the local
+  `.dev-metrics/events.jsonl` (at most 8 MB) and warns when one command,
+  run from one place, ran more than 600 times in an hour:
+  `looks like a polling loop: status in services/api, 1200 calls in an hour (…)`.
+  It is local and sends nothing.
+- **Each dev-metrics line records `cwd`**, relative to the distribution root
+  (`.` at the root, `outside` elsewhere), never an absolute or home path.
+  Like every field, it is sent only when you opt in.
+
+### Metrics (before → after)
+
+- Polling loops a week: 18,600 → under 100 expected, since the hook blocks
+  them. The "after" is counted on the candidate's first week.
+- Incomplete hand-backs: not measured → 0 for default-pack agents (the Stop
+  hook sends them back). The candidate's first run sets the baseline.
+- Hand-backs with an unexplained ID: no baseline → 0 for default-pack
+  agents. The candidate's first run sets the baseline.
+- doctor on a replay of a three-day polling burst: no warning → it warns.
+
+### Migrations
+
+- None needed. To turn the guardrails off for Den's pack, set
+  `agents.default_pack: { hooks: false, instructions: false }`. To turn
+  them on for your own pack, write its `persona_packs` entry as
+  `{ path: <dir>, hooks: true, instructions: true }`. A persona's
+  `den_hooks` / `den_instructions` front matter wins over its pack's.
+
 ## [0.4.6] - 2026-11-07
 
 Den in five minutes, set up by your own agent (ON-2, with ON-4's dry run).

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.6/hero-dark.png">
-  <img src="docs/images/0.4.6/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.8/hero-dark.png">
+  <img src="docs/images/0.4.8/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.6/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.8/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.6/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.6/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.6/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.6/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.8/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.8/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.8/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.8/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

@@ -87,6 +87,8 @@ question for the person (`ask`, sometimes with `choices`).
 | `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
 | `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
 | `<cli> mcp connect --runtime <runtime> --json`             | `{ ok, server, clients: [{ id, ok, said, file?, changed? }], restart, web }` |
+| `<cli> down <repo> --json`                                 | `{ ok, workspace, services, all? }`                                          |
+| `<cli> web down --json`                                    | `{ ok, url, port, running, stopped }`                                        |
 
 ### repo add
 
@@ -122,6 +124,10 @@ question for the person (`ask`, sometimes with `choices`).
 
 ### up, doctor and mcp connect
 
+- `down --json` and `web down --json` are the clean-up steps. Each is safe
+  to re-run: `web down` answers `stopped: false` when the server wasn't
+  running, and `ok` is true once nothing answers on its port.
+
 - `up --json` runs `up` as usual, then reports each service it touched:
   `result` is `started`, `already-running`, `failed` or `skipped`, and
   `health` is the service's health after it started (a service with a
@@ -491,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.
@@ -684,6 +695,18 @@ one is started (see Sessions).
 server, Den's MCP) and answers with one JSON object: see
 [Set up by your agent](#up-doctor-and-mcp-connect).
 
+doctor also reads the end of the local `.dev-metrics/events.jsonl` (at
+most 8 MB of it, however big the file) and warns when one command, run
+from one place, ran more than 600 times in an hour. That is almost always
+an agent polling. It is a warning, never a failure, and nothing is sent
+(see [Dev metrics](#dev-metrics-local-unless-you-opt-in)):
+
+```
+Acme doctor: dev-metrics (local, never sent)
+
+  ⚠ looks like a polling loop: status in services/api, 1200 calls in an hour (2026-11-04T09:00:00Z–2026-11-04T09:59:57Z)
+```
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -1818,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
@@ -1900,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`,
@@ -2012,6 +2044,7 @@ server scoped to its workspace.
 <cli> agents resume <id> [-w <ws>]
 <cli> agents personas [--json]
 <cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
+<cli> agents handback-check <file|->    # is a hand-back complete and plain (see Guardrails)
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -2084,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
@@ -2120,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:
@@ -2215,6 +2333,8 @@ standing: true # starts with its workspace (later slices)
 context: [docs/specs, the design system] # what to read first
 runtime: generic # default den-claude
 permission_mode: plan # den-claude only; default `default`
+den_hooks: false # Den's guardrail hooks for this persona (see Guardrails)
+den_instructions: false # Den's shared instructions for this persona
 argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
 ---
 
@@ -2236,6 +2356,104 @@ used without converting them. Files without front matter (a README) are
 skipped; two files with one id in a pack, or a pack that isn't a directory,
 are errors naming the file or the key.
 
+### Guardrails: hooks, shared instructions, hand-backs
+
+Every persona in Den's default pack gets two things with no setup: Den's
+**shared persona instructions** and, on den-claude, Den's **hooks**. Both
+are Den's own files, in `src/shared/agents/guardrails/` of the package.
+
+**Shared instructions** (`instructions.md`) are appended to the role prompt
+(den-claude's `--append-system-prompt`; any runtime that takes the role
+prompt gets them). They say:
+
+- write to people plainly, in short sentences;
+- never name an issue or ID without saying what it is;
+- ask each decision as a numbered yes/no question;
+- no caveat sections, and nothing the person doesn't need in order to act;
+- read a slice of a log, or hand it to a subagent; don't poll with `sleep`;
+- end a hand-back with the template below.
+
+**Hooks** (`hooks.json`, a Claude Code settings fragment) go in the agent's
+own settings file, `--settings <stateDir>/agent-files/<id>/settings.json`.
+Den never writes your `~/.claude`; your own hooks still run.
+
+- `PreToolUse` on `Bash|Read` (`pretooluse.mjs`, plain Node, no imports)
+  blocks, with a reason Claude sees (exit 2):
+  - reading all of a log or a large file into the conversation: a `Read`
+    with no `limit`, or `cat`, `less`, or `tail` from a line (`tail +1`,
+    `tail -n +1`), whose output reaches the conversation. A log is `*.log` or `*.log.<N>`, a `.jsonl` under
+    `.dev-metrics/`, or a `.jsonl` under `.claude/projects/` (a transcript).
+    Large is over 256 KB. `cat x.log | grep …`, `cat x.log > y`, a plain
+    `tail x.log` (10 lines) and `tail -n 100 x.log` pass. The reason says to read a slice or hand the
+    file to a subagent.
+  - `sleep` in the foreground, alone or in an `until …; do sleep …; done`,
+    `while` or `for` loop. A Bash call with `run_in_background`, and
+    `sleep … &`, pass. The reason says to run in the background or use a
+    wait primitive. Recent Claude Code versions have their own sleep guard,
+    which answers first (and also stops `sleep … &`). The sleep is blocked
+    either way; Den's hook covers runtimes and versions without that guard.
+  - Nothing else. Quoted text, heredoc bodies and other tools always pass,
+    and a hook that can't read its input lets the call through.
+- `Stop` (`stop-hook.ts`) checks a turn's last message, which is what the
+  person reads. With a `Hand-back` heading it gets the whole hand-back
+  check; any other message gets the plain-writing part only (every ID
+  explained). If the check fails, Claude is told what to fix and keeps
+  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.
+
+**The hand-back template**, which the check enforces:
+
+```markdown
+## Hand-back
+
+- URL: <the full link the person opens, with https://>
+- Machine: <the machine it runs on>
+- Branch: <the branch>
+- What changed: <what is different now>
+- What to click: <the steps to see it working>
+- Decisions:
+  1. <a question the person answers yes or no>?
+```
+
+`<cli> agents handback-check <file|-> [--json]` runs the same check on a
+file or stdin: exit 0 when the hand-back passes, 1 with each problem. It
+rejects a hand-back when:
+
+- a part is missing or empty. A part is a line starting with its label and
+  a colon (bold is fine), or a heading that is its label. URL must hold a
+  link (`://`), or say `none` for work with no page (`URL: none — a CLI
+change` is fine). `Decisions: none` is allowed.
+- an ID is bare. An ID is `#<digits>`, or 1 to 4 capitals, an optional `-`,
+  digits and an optional `.<digits>` (`R12`, `AG-14`, `KB-4.1`). Links,
+  `inline code`, code blocks, and the URL and Branch parts are not checked.
+  An ID is explained (glossed) when
+  1. a parenthetical of two or more words follows it: `#5 (the hooks issue)`;
+  2. a colon or a spaced dash and two or more words follow it:
+     `R12: plain writing`;
+  3. it sits in a parenthetical of IDs only, right after a word:
+     `plain writing (R12)`, `the issues (#5, #6)`;
+  4. or the same ID was explained earlier in the text.
+- a decision isn't a numbered yes/no question: each item must be numbered
+  (`1.` or `1)`), end in `?`, not start with what, which, how, why, when,
+  where or who, and not offer a choice (`or`).
+
+**Turning them off or on.** They are on for Den's default pack and off for
+your own packs. A pack's setting applies to each of its personas; a
+persona's front matter (`den_hooks`, `den_instructions`) wins over it:
+
+```yaml
+agents:
+  default_pack: { hooks: false } # Den's pack: no hooks, instructions kept
+  persona_packs:
+    - personas # your pack: neither
+    - { path: more-personas, hooks: true, instructions: true } # both
+```
+
+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.
+
 ### Runtimes
 
 `<cli> doctor` lists the runtime kind. Den knows the runtimes in its
@@ -2418,11 +2636,36 @@ metrics:
   share: true
 ```
 
+Each line also records `cwd`: where the command ran, relative to the
+distribution root (`.` for the root), or `outside` for anywhere else. It is
+never an absolute or home path. [`<cli> doctor`](#doctor) uses it to warn
+about polling loops.
+
 Only the boolean `true` counts. With it, and a Sentry DSN in
 `DEV_METRICS_SENTRY_DSN` (or a synced `dev-metrics.config`), each line is
 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.
+
+`<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.
+
+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.6",
+  "version": "0.4.8",
   "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/skills/install-den/SKILL.md

@@ -65,8 +65,8 @@ person (`ask`, sometimes with `choices`).
      in `package.json`. `--sidecar` asks for this explicitly, and fails if the repo has its own manifest.
    - If you can see which port the app listens on, add `--health http://localhost:<port>/`. Den then checks that it
      answers.
-2. If the answer has `ask` and `choices`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person
-   **one** question: the `ask` text, with the choices numbered. Then re-run with their answer:
+2. If the answer has `ask`, Den couldn't tell how the repo starts, and it wrote nothing. Ask the person **one**
+   question: the `ask` text, with any `choices` numbered (there may be none). Then re-run with their answer:
    `./bin/<name> repo add <repo> --run "<their command>" --json`.
 3. The answer names the repo (`repo`), the workspace it joined (`workspace`) and where its manifest is (`manifest`).
    A workspace is Den's name for a set of repos that run together. The first one is called `default`.

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

@@ -15,6 +15,10 @@
  *   `<state>/sessions/**`. It binds a
  *   cooperating agent only: the agent runs as the same OS user, so nothing
  *   stops one that ignores its permission config from reading them.
+ * - Den's guardrail hooks (den#5, guardrails.ts), when the persona's
+ *   guardrails include them: the same settings file carries
+ *   guardrails/hooks.json's `hooks` (PreToolUse on Bash and Read, and Stop),
+ *   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.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
@@ -41,6 +45,7 @@ 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 {
   LaunchError,
   mcpConfigJson,
@@ -54,6 +59,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";
@@ -221,7 +227,8 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
-  const settings = input.stateDir ? settingsPath(input) : null;
+  const hooks = input.persona.guardrails?.hooks ? guardrailHooks() : null;
+  const settings = input.stateDir || hooks ? settingsPath(input) : null;
   return {
     argv: [
       "--mcp-config",
@@ -241,13 +248,21 @@ function common(input: LaunchInput): {
     ],
     files: {
       [file]: mcpConfigJson(input.mcp),
-      ...(settings && input.stateDir
+      ...(settings
         ? {
             [settings]: `${JSON.stringify(
               {
-                permissions: {
-                  deny: stateDirDenyRules(input.stateDir, input.env?.HOME),
-                },
+                ...(input.stateDir
+                  ? {
+                      permissions: {
+                        deny: stateDirDenyRules(
+                          input.stateDir,
+                          input.env?.HOME,
+                        ),
+                      },
+                    }
+                  : {}),
+                ...(hooks ? { hooks } : {}),
               },
               null,
               2,
@@ -303,6 +318,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