@monster-orange/den 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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,

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.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.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.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.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.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

@@ -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:
@@ -2547,6 +2646,26 @@ 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.
+
+`<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.7",
+  "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/src/shared/agents/den-claude.ts

@@ -59,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";
@@ -317,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

package/src/shared/agents/personas.ts

@@ -13,7 +13,8 @@
  *   tools        "Read, Grep" or a list: hints, never a restriction Den applies
  *
  * Den's own keys sit beside them: `runtime` (default den-claude),
- * `standing` (starts with its workspace, §5), `context` (what to read
+ * `standing` (starts with its workspace, §5; resumes after a restart),
+ * `resume_on_restart` (AG-14.3: resumes after a restart too), `context` (what to read
  * first), `argv` (the generic runtime's template), and `permission_mode`
  * (den-claude's Claude Code permission mode; it checks the value), and
  * `den_hooks` / `den_instructions` (true or false: this persona's
@@ -45,6 +46,11 @@ export interface Persona {
   model?: string;
   /** Started with its workspace (planner, orchestrator). */
   standing: boolean;
+  /**
+   * `resume_on_restart: true` (AG-14.3): resumed on its own when Den or
+   * the machine restarted. Standing personas always are.
+   */
+  resumeOnRestart?: boolean;
   /** Tool hints. */
   tools: string[];
   /** What to read first (specs, the design system, workspace config). */
@@ -135,6 +141,9 @@ export function parsePersona(text: string, file: string): Persona | null {
   const standing = f.standing ?? false;
   if (typeof standing !== "boolean")
     throw new Error(`${file}: standing must be true or false`);
+  const resumeOnRestart = f.resume_on_restart ?? false;
+  if (typeof resumeOnRestart !== "boolean")
+    throw new Error(`${file}: resume_on_restart must be true or false`);
   let argv: string[] | undefined;
   if (f.argv !== undefined && f.argv !== null) {
     if (
@@ -166,6 +175,7 @@ export function parsePersona(text: string, file: string): Persona | null {
     ...(runtime ? { runtime } : {}),
     ...(model && model !== "inherit" ? { model } : {}),
     standing,
+    ...(resumeOnRestart ? { resumeOnRestart } : {}),
     tools: stringList(f, "tools", file),
     context: stringList(f, "context", file),
     ...(argv ? { argv } : {}),

package/src/shared/agents/records.ts

@@ -9,6 +9,11 @@
  * A record never holds the env or the argv: the role prompt, tokens and
  * anything else a launch passes stay out of it. An agent id is unique in a
  * distribution.
+ *
+ * AG-14: a removed agent's record moves to removed-agents/<id>.json, so
+ * Undo can bring it back; restoreRecord does, and purgeRemoved forgets
+ * the ones older than the undo window. The runtime's own conversation
+ * history is never touched.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -34,6 +39,54 @@ export interface AgentRecord {
   resumedAt?: string;
   /** The runtime's handle for resume (den-claude: the conversation id). */
   resumeToken?: string;
+  /**
+   * The runtime was launched on resumeToken at least once (0.4.8). A
+   * resume then always tries the runtime's own resume first, never a new
+   * conversation under the same id (which the runtime refuses once the
+   * conversation exists).
+   */
+  launched?: boolean;
+  /**
+   * The workspaces beyond its own its MCP served when it started
+   * (agents.<id>.grants then). A resume keeps them, never more than the
+   * config still allows (AG-14).
+   */
+  grants?: string[];
+  /** When its session was seen to end on its own (AG-14: "Exited"). */
+  endedAt?: string;
+  /** That session's exit code, when the host said it. */
+  exitCode?: number;
+  /**
+   * Set when its session was gone after Den or the machine restarted
+   * (AG-14.3: "Interrupted"); cleared by a resume or a start.
+   */
+  interruptedAt?: string;
+  /** What its run came to (den#6), filled in by `<cli> usage`. */
+  outcome?: AgentOutcome;
+  /** Its tokens, from the runtime's own transcript (den#6). */
+  usage?: AgentUsage;
+}
+
+/** What an agent's run came to (den#6). Read locally; never sent. */
+export interface AgentOutcome {
+  /** The pull request it opened, when it opened one. */
+  prOpened?: string;
+  /** That pull request merged in the run. */
+  prMerged?: boolean;
+  /** The last test run it made passed (true) or failed (false). */
+  testsGreen?: boolean;
+  /** From its start to its last activity, in milliseconds. */
+  wallClockMs?: number;
+}
+
+/** An agent's token counts (den#6), summed over its transcripts. */
+export interface AgentUsage {
+  calls: number;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  compactions: number;
 }
 
 /** An agent id: the same rules as a workspace or session name. */
@@ -85,6 +138,67 @@ export function readRecord(stateDir: string, id: string): AgentRecord | null {
   }
 }
 
+/** Where removed records wait for Undo (AG-14.1b). */
+export function removedDir(stateDir: string): string {
+  return path.join(stateDir, "removed-agents");
+}
+
+/** How long a removed record can be brought back. */
+export const UNDO_KEEP_MS = 60 * 60 * 1000;
+
+/**
+ * Forget agent `id` (its record moves aside for Undo). True when there
+ * was one. Its files and the runtime's history stay.
+ */
+export function removeRecord(stateDir: string, id: string): boolean {
+  const from = recordFile(stateDir, id);
+  if (!fs.existsSync(from)) return false;
+  ensureDir(removedDir(stateDir));
+  const to = path.join(removedDir(stateDir), `${id}.json`);
+  fs.renameSync(from, to);
+  // Its mtime is when it was removed: purgeRemoved goes by it.
+  const now = new Date();
+  fs.utimesSync(to, now, now);
+  return true;
+}
+
+/**
+ * Bring a removed record back (Undo). False when there is none to bring
+ * back, or an agent of that id exists again.
+ */
+export function restoreRecord(stateDir: string, id: string): boolean {
+  if (!AGENT_ID_RE.test(id)) return false;
+  const from = path.join(removedDir(stateDir), `${id}.json`);
+  const to = recordFile(stateDir, id);
+  if (!fs.existsSync(from) || fs.existsSync(to)) return false;
+  ensureDir(agentsDir(stateDir));
+  fs.renameSync(from, to);
+  return true;
+}
+
+/** Forget removed records older than `keepMs` for good. */
+export function purgeRemoved(
+  stateDir: string,
+  keepMs = UNDO_KEEP_MS,
+  now = Date.now(),
+): void {
+  let names: string[];
+  try {
+    names = fs.readdirSync(removedDir(stateDir));
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    if (!n.endsWith(".json") || !AGENT_ID_RE.test(n.slice(0, -5))) continue;
+    const f = path.join(removedDir(stateDir), n);
+    try {
+      if (now - fs.statSync(f).mtimeMs > keepMs) fs.unlinkSync(f);
+    } catch {
+      /* gone already */
+    }
+  }
+}
+
 export function listRecords(stateDir: string): AgentRecord[] {
   let names: string[];
   try {

package/src/shared/agents/runtime.ts

@@ -130,6 +130,18 @@ export interface Runtime {
   launch(input: LaunchInput): LaunchOutput;
   /** A new run that continues the last one; null when there is nothing to resume. */
   resume?(input: ResumeInput): Omit<LaunchOutput, "resumeToken"> | null;
+  /**
+   * Whether the runtime has a conversation for `token` on this machine
+   * (den-claude: its transcript file). Only ever a fast path: false may
+   * just mean it isn't written yet.
+   */
+  conversationExists?(token: string, env?: NodeJS.ProcessEnv): boolean;
+  /**
+   * What the runtime prints when it exits at once (0.4.8): `noConversation`
+   * when a resume finds nothing to continue, `idInUse` when a new
+   * conversation's id is taken. Den then tries the other way, once.
+   */
+  launchFailures?: { noConversation?: RegExp; idInUse?: RegExp };
   /** Where permission prompts surface (Q-AG-2). */
   approvals?: "terminal" | "hook";
   /**

package/src/shared/den-config.ts

@@ -391,6 +391,11 @@ export interface UserConfig {
     runtimes?: Record<string, { bin?: unknown } | null>;
     /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
     runtime_catalog?: unknown;
+    /**
+     * AG-14.1b: forget stopped and exited agents after this long: never
+     * (the default), 1d or 7d. Interrupted agents are never forgotten.
+     */
+    remove_stopped_after?: unknown;
   };
   /**
    * The web server's per-machine keys (src/shared/web-session.ts
@@ -465,6 +470,29 @@ export function configuredRuntimeCatalog(
   );
 }
 
+/** The values `agents.remove_stopped_after` takes, in days (AG-14.1b). */
+export const REMOVE_STOPPED_AFTER: Readonly<Record<string, number>> = {
+  never: 0,
+  "1d": 1,
+  "7d": 7,
+};
+
+/**
+ * user.yml's `agents.remove_stopped_after`, in days (0: never, the
+ * default). Throws naming the key when it is none of never, 1d, 7d.
+ */
+export function configuredRemoveStoppedAfter(
+  read: () => UserConfig = readUserConfig,
+): number {
+  const v = read().agents?.remove_stopped_after;
+  if (v === undefined || v === null) return 0;
+  if (typeof v === "string" && Object.hasOwn(REMOVE_STOPPED_AFTER, v))
+    return REMOVE_STOPPED_AFTER[v];
+  throw new Error(
+    `agents.remove_stopped_after (${path.basename(USER_CONFIG_PATH)}): must be never, 1d or 7d (got ${JSON.stringify(v)})`,
+  );
+}
+
 /**
  * Set (a path) or clear (null) `agents.runtimes.<id>.bin` in user.yml,
  * keeping everything else there. The caller checks the path first.
@@ -773,6 +801,8 @@ export const MCP_ACTIONS = [
   "service_restart",
   "workspace_sync",
   "run_tests",
+  // AG-14.4: resume another agent of its workspace (or a granted one).
+  "agent_resume",
 ] as const;
 export type McpAction = (typeof MCP_ACTIONS)[number];
 

package/src/shared/plugins/manifest.ts

@@ -58,6 +58,9 @@ export const KIND_TIERS: Readonly<Record<string, PluginTier>> = {
   secrets: "server",
   identity: "server",
   "health-source": "server",
+  // den#6: reads a runtime's own transcripts on this machine, for tokens
+  // and outcomes per agent; never sends them anywhere.
+  usage: "server",
 };
 
 export interface PluginProvide {

package/src/shared/usage/paths.ts

@@ -0,0 +1,16 @@
+/**
+ * Where Claude Code keeps its transcripts. No registration here, so the
+ * den-claude runtime can ask (conversationExists) without loading the
+ * usage sources (sources.ts registers one when it loads).
+ */
+import * as os from "os";
+import * as path from "path";
+
+/** Claude Code's transcripts: $CLAUDE_CONFIG_DIR/projects, else ~/.claude/projects. */
+export function claudeProjectsDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const base =
+    env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), ".claude");
+  return path.join(base, "projects");
+}