@monster-orange/den 0.4.13 → 0.4.15

package/CHANGELOG.md

@@ -4,6 +4,181 @@ 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.15] - 2026-11-07
+
+### Added
+
+- **Onboarding reads for agents, the CLI and the browser (ON-3).** Three new
+  MCP read tools, always registered, each with a CLI twin and a web API
+  route (GET, a read in the route table) that a page can show as it is:
+  - `onboard_status`, `<cli> onboard status [--json]`,
+    `/api/onboard/status`: what's set up (a distribution, Node, git, Docker,
+    the web server, workspaces, repos, a running service, Den's MCP), each
+    `ok`, `warn` or `todo`, and the one next step in plain words with its
+    command. It never runs an agent's CLI to check Den's MCP.
+  - `repos_detect`, `<cli> repo detect <folder> [--json]`,
+    `/api/onboard/repos`: the git repos in a folder, one or two levels down,
+    how each one runs (the same detection as `repo add`), and suggested
+    workspaces (the repos in one parent folder go in one workspace named
+    after it). It never writes, runs a repo's tools or follows a symlink,
+    skips dot-folders, `node_modules` and `vendor`, and stops at 50 repos.
+  - `manifest_draft`, `<cli> repo add <path> --dry-run --json`,
+    `/api/onboard/manifest`: the side-car manifest `repo add` would write,
+    checked by the same validator, with nothing written. Several ways to
+    start the repo is a question with its choices, as `repo add` asks.
+- A path for `repos_detect` or `manifest_draft` must be a folder inside the
+  person's home folder and outside Den's state folder; anything else is
+  refused with the reason. A workspace-scoped MCP server can't scan folders,
+  and drafts only inside its workspace's repos.
+- **Onboarding writes, held for the person (ON-3).** Three new MCP write
+  tools, `workspace_create`, `repo_add` and `service_try`, on by default
+  and gated by the person's Allow (not by `mcp.actions`). They change
+  nothing by themselves: each asks Den to hold the change, and every Den page opens a
+  dialog in the person's browser, "The `<agent>` agent wants to: … ·
+  Review · Later · Deny · Allow". Den writes the line and the Review from
+  the action and its arguments (`repo_add`'s Review is its dry run); the
+  agent's note is only quoted. Allow runs it once, from the stored
+  arguments checked again, through the code paths the pages and the CLI
+  use (the Workspaces page's create, `repo add --json`, `up` as the
+  Services page starts it). Deny, 10 minutes with no answer, or the agent
+  being stopped run nothing. The agent waits up to 2 minutes, then
+  `approval_check` reads where its request stands; meanwhile it is
+  "waiting" on the Agents page. Routes: `POST /api/approvals`,
+  `GET /api/approvals`, `GET /api/approvals/<id>`,
+  `POST /api/approvals/<id>/decide`. See [Onboarding writes, held for the
+  person](docs/distributions.md#onboarding-writes-held-for-the-person).
+- **`mcp.approvals: false`** in the distribution config turns the three
+  held writes off: they aren't registered, and `POST /api/approvals`
+  answers 403 `approvals_off`. `doctor` (its `mcp:approvals` check in
+  `--json`), the MCP server's instructions and `mcp --list` (on stderr) say
+  which is in effect. A value that isn't `true` or `false` is an error.
+- **Who asked.** An agent's token shows its name ("The `<agent>` agent
+  wants to:"). A request with no agent identity reads "Something on this
+  machine (no agent identity) wants to:", with "If you didn't ask an agent
+  to do this, Deny." under it. In English, Spanish and Japanese.
+- **Only the person approves.** Allow and Deny need a browser signed in on
+  this Den and holding its approval key, even on localhost. Every sign-in
+  mints the key, handed over only in the sign-in's own answer (a 303's
+  `#ak=` fragment, or the sign-in poll); the session keeps its hash and
+  `GET /api/session` never returns it. A cookie alone (any localhost port
+  receives it), the CLI's bearer, an agent's token or an anonymous request
+  from this machine is refused with `signin_to_approve`.
+- **Only the person sees what waits.** `GET /api/approvals` needs what
+  Allow needs: the cookie, that session's CSRF token and the approval key.
+  Anything else gets 403 `signin_to_approve` with a count (`waiting`), and
+  a signed-out page shows a banner to sign in. An agent's token lists only
+  its own requests and their outcomes. An ask with no agent token gets a
+  ticket that reads that one request (`X-Den-Approval-Ticket`); Den's MCP
+  server keeps it and never shows it to the agent.
+- **The setup link.** `<cli> web claim-link [--json]` prints a one-time
+  link (`/auth?claim=<code>`, 30 minutes) that signs this browser in, for
+  an install that hands the person over to the browser. Opened twice, it
+  says it was used and that someone else may have opened it.
+
+### Changed
+
+- Pairing a device, approving one, and linking or unlinking the GitHub
+  owner (`POST /api/web/pair`, `/api/web/approve`, `/api/web/owner/link`,
+  `/api/web/owner/unlink`) need the person: the CLI's bearer, or a
+  signed-in browser holding its approval key. On plain localhost,
+  Settings › Access asks you to sign in before pairing.
+- Inside an agent's session (`DEN_AGENT` or `DEN_ACTOR_TOKEN` set), the CLI
+  refuses every command that lets a browser in: `web login`, `web approve`,
+  `web owner link|unlink`, `web claim-link`; `web open` opens the plain
+  page.
+- What a test run writes and Den serves (`/report/*`, the Playwright
+  report, and `/reports/security/*`) is served sandboxed (an opaque
+  origin, no scripts reaching Den's), with nosniff, no-store and
+  no-referrer.
+- A workspace name is at most 64 characters.
+- **A Name is the agent's id (AG-10.10b).** A Name given at start (the
+  dialog's Name, the API's `name`, the CLI's new `--name`) makes the id its
+  slug: "API spike" starts `api-spike`, titled "API spike". The dialog says
+  so as you type. A Name that matches a running agent in the workspace, by
+  id or by title, is refused: the dialog says "api-spike is already
+  running · Open it" and Start is off. A stopped one offers Resume it, or
+  Start makes `api-spike-2`. No two live agents in a workspace share a
+  title. With no Name the persona's id stays the default; `--id` is exact.
+- The Den theme's light mode (2.0.1): `--ok`, `--warn`, `--bad`,
+  `--remote` and `--accent-text` are darker, so a status pill (the token
+  on a tint of itself) meets WCAG AA (4.5:1) on every surface, `--sunken`
+  included. They measured 3.7 to 4.4:1 there. Dark mode is unchanged.
+
+### Fixed
+
+- The signed-out page's Open Terminal link was `ssh://<host>` with no
+  account, so an SSH app filled in its own default (an iPad's asked for
+  `user@…`'s password). The link and the ssh one-liner are now
+  `<user>@<host>`, the account Den runs as, and the note says "Log in with
+  your <machine> account (<user>) and its password, or an SSH key."
+  `web.ssh_user` names another account; `web.ssh_user: ""` leaves it off.
+- Text dimmed with opacity fell under WCAG AA on the light theme. Not
+  installed editors and terminals in Settings (3.1:1, their "not found"
+  2.2:1), a repo already in the workspace in Add service (1.9:1), the
+  Release table's loading sub-line (3.7:1), and a primary button on hover
+  (4.4:1). They are full-strength now, in `--muted`; hover darkens.
+- `/reports/security/*` was always 404: the `/report` prefix shadowed it.
+- Bring in on a shared repos root (the usual layout) listed every
+  conversation under the root, so workspaces showed the same 50 and their
+  own were crowded out. A conversation is a workspace's when it ran in one
+  of its repos' folders or inside one, in its own folder, or exactly at a
+  shared root; the 50 cap applies after that. Another workspace's
+  conversation is refused by id: "This conversation belongs to <folder>,
+  not to workspace <ws>" (CLI, API and MCP).
+
+### Migrations
+
+None. Sessions signed in before 0.4.15 hold no approval key: sign in again
+to approve or to pair a device.
+
+## [0.4.14] - 2026-11-07
+
+### Added
+
+- **Bring in a conversation (AG-17.1).** A Claude Code conversation you
+  started in a terminal outside Den, in the workspace's folder or in one
+  of its repos' folders (a repo added by path outside it too), can become
+  a Den agent. Agents › Bring in lists them, newest first, and asks for a
+  persona; Bring in runs `claude --resume <id>` in the folder it ran in,
+  with Den's token, MCP, hooks and guards from then on. Den reads only the
+  first and last 64 KB of each transcript. A conversation written in the
+  last minute is refused: "Still open in another terminal. Close it there
+  first". CLI: `agents import -w <ws>` lists, `agents import -w <ws>
+  --session <id> --persona <p>` brings one in. MCP `agent_import` is
+  opt-in through `mcp.actions`. Routes: `GET
+  /api/workspaces/<ws>/conversations`, `POST
+  /api/workspaces/<ws>/conversations/<id>/import`. Only den-claude can
+  bring one in for now. The dialog asks you to close the
+  conversation in any other terminal first.
+- **One persona, several agents (AG-10.10).** Starting a persona that
+  already has an agent in the workspace starts another: `be-dev`, then
+  `be-dev-2`, `be-dev-3`. A stopped agent's id is never reused by a new
+  start, only by its Resume or Start fresh. The Start dialog says the id
+  it will use ("Starts as be-dev-2") and takes an optional Name. An id
+  that is running is refused, and the dialog offers "Open the running
+  one". `--id` stays exact. The start route takes `name`; `GET
+  /api/personas?workspace=<ws>` answers `startsAs`; a 409 for a running
+  agent carries `running: {id, sessionId}`.
+
+### Changed
+
+- Without `--id`, a start of a persona whose agent is stopped in that
+  workspace no longer replaces it: it starts `<persona>-2`. To continue
+  the stopped one, Resume it or Start fresh on it.
+
+### Fixed
+
+- Bring in: a long title no longer cuts off its "Agent …" badge, and each
+  "can't bring in a conversation yet" line is its own sentence.
+  Its intro names the repos' folders too.
+
+- Start › Advanced: the Model select's default reads "Persona default
+  (latest)" for a persona with no model of its own; the longer label was
+  cut off.
+- An `up` whose service exits at once with an error no longer leaves the
+  service listed. The command could exit before Den recorded its process
+  group, and then its record stayed.
+
 ## [0.4.13] - 2026-11-07
 
 ### Added
@@ -56,6 +231,7 @@ config and manifest changes a distribution must make to move to it under
   `sessions.max_concurrent`).
 - **A tester persona** in Den's default pack.
 
+
 ### Changed
 
 - `POST /api/workspaces/<ws>/agents` takes `version`, `permission`,

package/README.md

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

@@ -83,6 +83,9 @@ question for the person (`ask`, sometimes with `choices`).
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `npx @monster-orange/den create <name> [dir] --yes --json` | `{ ok, dir, cli, existed, files, port, portPicked?, next }`                  |
 | `<cli> repo add <path\|git-url> --json`                    | `{ ok, existed, repo, workspace, mode, path, manifest, services, next }`     |
+| `<cli> repo detect <folder> --json`                        | `{ ok, path, repos, workspaces, truncated, skipped, rule, next }`            |
+| `<cli> repo add <path> --dry-run --json`                   | `{ ok, dryRun, repo, workspace, path, manifest, draft, validation, next }`   |
+| `<cli> onboard status --json`                              | `{ ok, checks: [{ id, status, detail, fix?, ask? }], next }`                 |
 | `<cli> up <repo> --json`                                   | `{ ok, workspace, services: [{ address, result, health, detail? }], next }`  |
 | `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
 | `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
@@ -121,6 +124,115 @@ question for the person (`ask`, sometimes with `choices`).
   else the focused one, else a new `default` workspace.
 - The same repo again answers `ok` with `existed: true`. A different repo
   under the same name is an error that offers `relocate` or `--name`.
+- `--dry-run` (a local path only) runs the same detection and validator and
+  writes nothing: no side-car, no workspace entry, no catalog entry. The
+  answer carries the side-car as YAML (`draft`), the validator's answer
+  (`validation`), where it would go (`manifest.file`, `written: false`) and,
+  in `next`, the same command without `--dry-run`. A git URL is refused: it
+  would have to be cloned first.
+
+### Onboarding reads
+
+Three reads help a person, or an agent, finish setting Den up. Each one is
+a CLI command, an MCP read tool and a web API route, with the same answer
+(the browser can show the route's JSON as it is):
+
+| CLI                                      | MCP tool         | Web API (GET)           |
+| ---------------------------------------- | ---------------- | ----------------------- |
+| `<cli> onboard status [--json]`          | `onboard_status` | `/api/onboard/status`   |
+| `<cli> repo detect <folder> [--json]`    | `repos_detect`   | `/api/onboard/repos`    |
+| `<cli> repo add <path> --dry-run --json` | `manifest_draft` | `/api/onboard/manifest` |
+
+- **`onboard status`** says what's set up and the one next step. `checks`
+  are, in order: `distribution` (this folder has its own `bin/<cli>`),
+  `node`, `git`, `docker` and `web` (the same probes as `doctor --json`),
+  `workspaces` (how many, and the active ones), `repos` (how many are
+  added), `service` (how many services Den started are running) and `mcp`.
+  Each is `ok`, `warn` or `todo`, with a `fix` command or an `ask` for the
+  person when there is one. `next` is `{ id, step, command }`: the step in
+  plain words and the command for it, or `id: "done"` when everything is
+  set up. `mcp` never runs an agent's CLI: it is `ok` when the question
+  came through Den's MCP, or when a client's config file names this
+  distribution's server; with only Claude Code or Codex installed (they
+  keep their list behind their own CLI) it is a `warn` pointing at
+  `<cli> mcp clients`. It exits 0 whenever it answers.
+- **`repo detect <folder>`** finds the git repos in one folder: the folder
+  itself when it is a repo, else its subfolders one and two levels down (a
+  repo's own subfolders are not scanned). For each repo: `manifest` (`repo`,
+  `sidecar` or `none`), `runs` (what [`repo add`](#repo-add) would detect)
+  or `ask` and `choices`, the suggested `workspace`, and `registered` when
+  it is already in one. `workspaces` groups them by one simple rule: the
+  repos in one parent folder go in one workspace named after that folder,
+  and a repo directly in the scanned folder gets the scanned folder's name.
+  It skips dot-folders, `node_modules` and `vendor`, never follows a
+  symlink, stops at 50 repos or 5,000 folder entries (`truncated: true`),
+  and never writes or runs a repo's tools.
+- **`repo add --dry-run`** is the draft: see [`repo add`](#repo-add).
+- **The path rule** (`repos_detect`, `manifest_draft` and both routes): a
+  path is required, absolute or starting with `~/`. It is resolved with its
+  symlinks, and must be a folder inside the person's home folder and outside
+  Den's own state folder; anything else is refused with the reason (a 400
+  from the route, `Refused:` from the tool, exit 1 from the CLI).
+
+### Onboarding writes, held for the person
+
+An agent finishes setup with three MCP write tools. None of them changes
+anything by itself: each asks Den to hold the change, and the person's
+browser opens a dialog on whatever Den page is open: "The `<agent>` agent
+wants to: … · Review · Later · Deny · Allow". A request with no agent
+token (an MCP server outside an agent's session, or anything else on this
+machine) reads "Something on this machine (no agent identity) wants to:",
+with "If you didn't ask an agent to do this, Deny." under it.
+
+| MCP tool           | What Allow runs                                         |
+| ------------------ | ------------------------------------------------------- |
+| `workspace_create` | The Workspaces page's create: an empty workspace        |
+| `repo_add`         | `repo add <path> --json`, a local folder inside home    |
+| `service_try`      | `up` for one service, as the Services page's Start does |
+
+- **Den writes the dialog.** Its line and its Review come from the action
+  and its arguments, never from the agent. `repo_add`'s Review is its dry
+  run: the folder, the workspace (new or not) and the side-car Den would
+  write. The agent's `note` is shown only quoted, as "Agent says".
+- **Bad arguments are refused before anything waits**: the same checks as
+  the page, `repo add` and the path rule of
+  [Onboarding reads](#onboarding-reads).
+- **Only the person approves.** Allow and Deny need a browser signed in on
+  this Den holding its approval key: a session cookie alone, the CLI's
+  bearer, an agent's token, or an anonymous request from this machine (an
+  agent with a shell) is refused with `signin_to_approve`. On a fresh Den,
+  `<cli> web claim-link` prints a one-time setup link that signs the
+  browser in.
+- **Allow runs it once**, from the arguments stored when it was asked,
+  checked again first. Deny, 10 minutes with no answer, or the agent being
+  stopped run nothing. An agent may have 5 requests waiting; a restart drops
+  what waits (the agent asks again).
+- **The agent waits** up to 2 minutes for the answer, then gets the request
+  id: `approval_check` says `pending`, `done` (with what the run said),
+  `denied` or `expired`. While a request waits, its agent is "waiting" on
+  the Agents page.
+- **Only the person sees what waits.** `GET /api/approvals` needs what
+  Allow needs: the session cookie, that session's CSRF token
+  (`X-Den-CSRF`) and the approval key. Anything else gets 403
+  `signin_to_approve` with only `waiting`, a count, so a signed-out page
+  can show "Something is waiting for your approval. Sign in to see it."
+  An agent's token lists its own requests and their outcomes (`mine`),
+  never another agent's. An ask with no agent token gets a `ticket` in the
+  reply; `X-Den-Approval-Ticket: <ticket>` reads that one request and no
+  other. Den's MCP server keeps it and never shows it to the agent.
+- **Routes:** `POST /api/approvals` (`{ action, args, note? }`, 202 with the
+  request), `GET /api/approvals` (the person's: what waits; an agent's
+  token: its own), `GET /api/approvals/<id>` (the asking agent's own, the
+  ticket holder's, or the person's) and
+  `POST /api/approvals/<id>/decide` (`{ decision: "allow" | "deny" }`).
+  Every ask and decision is in the activity trail.
+- **On by default; `mcp.approvals: false` turns them off.** The person's
+  Allow is the gate, not `mcp.actions`. Off, the three tools aren't
+  registered and `POST /api/approvals` answers 403 `approvals_off`.
+  `doctor` (and its `mcp:approvals` check in `--json`), the MCP server's
+  instructions and `mcp --list` (on stderr) say which is in effect. A
+  workspace-scoped MCP server refuses `workspace_create` and `repo_add`:
+  they change Den beyond its workspace.
 
 ### up, doctor and mcp connect
 
@@ -1434,6 +1546,15 @@ user, and the CLI does that for you:
   host name (up to the first dot). It is never taken from the browser's
   Host. The ssh one-liner's target is the Host the browser used, without
   the port (the machine's host name if it had none).
+- **The ssh account.** The ssh one-liner and the Open Terminal link log in
+  as `<user>@<host>`, where user is the account the Den server runs as, so
+  an SSH app doesn't fill in its own default. The note under the button
+  says "Log in with your <machine> account (<user>) and its password, or
+  an SSH key." `web.ssh_user` names another account (`config/local/user.yml`,
+  else the distribution's `config/den.yml`; read at once). `web.ssh_user:
+""` leaves the account off, for a distribution that doesn't want it on a
+  page anyone on the network can see. It takes letters, digits, `.`, `_`
+  and `-`; anything else is refused at start, naming the key.
 - **Codes.** About 30 bits (Crockford base32: no I, L, O or U; typed in any
   case, the dash optional); the page polls with a separate 128-bit id. A
   code expires after 10 minutes and works once; at most five wait at once
@@ -1785,13 +1906,17 @@ to one workspace for one agent:
   (`map: "org-wide"`: every active workspace's graph merged, `workspaces`
   naming them); with one, that workspace's (`map: "workspace"`).
 - **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
-  take only `<ws>`'s services, `manifest_validate` takes only an absolute path
-  inside one of its repos (or the content), and `workspace_sync` syncs `<ws>`.
+  take only `<ws>`'s services, `manifest_validate` and `manifest_draft` take
+  only an absolute path inside one of its repos (or, for `manifest_validate`,
+  the content), and `workspace_sync` syncs `<ws>`. `repos_detect` is refused:
+  scanning folders reaches outside any workspace, so onboarding is for the
+  unscoped server.
   Tests run against the focused workspace, so `tests_available` and
   `run_tests` are refused unless `<ws>` is the focused one.
 - **Not workspace data**, served as unscoped: `environments`,
-  `security_latest`, `release_status`, `edge_status` and `org_summary` (the
-  org's and the distribution's, not a workspace's).
+  `security_latest`, `release_status`, `edge_status`, `onboard_status` (counts
+  and checks only) and `org_summary` (the org's and the distribution's, not
+  a workspace's).
 - **The org at a glance.** `org_summary` gives every agent every workspace
   and repo with status counts, the graph, the edge and the environments
   (see [Tools](#tools)). Detail and actions stay scoped: for workspaces
@@ -1857,10 +1982,12 @@ mcp:
     envs: [local] # the default; production is refused even if listed
   logs:
     remote: false # the default; true lets the log tools read non-local sources
+  approvals: true # the default: the held writes, each run on the person's Allow
 ```
 
 An unknown action or environment name is an error, so a typo never turns a
-guard off.
+guard off; so is an `approvals` that isn't `true` or `false`. See
+[Onboarding writes, held for the person](#onboarding-writes-held-for-the-person).
 
 ### Tools
 
@@ -1883,6 +2010,9 @@ Read tools (always registered):
 | `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health; an empty list says `why`                                                                                                                                                                                              |
 | `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names; `https` (TLS strategy, who supplies the cert, whether HTTPS is serving)                                                                                                                                                       |
 | `org_summary`       | several (read only)                        | Every workspace and repo with status counts, the graph, the edge and the environments; scoped, `yours` adds your workspace's services                                                                                                                                          |
+| `onboard_status`    | `/api/onboard/status`                      | What's set up and the one next step: `checks` (`ok`, `warn`, `todo`) and `next` (`step`, `command`); see [Onboarding reads](#onboarding-reads)                                                                                                                                 |
+| `repos_detect`      | `/api/onboard/repos`                       | The git repos in `path` (one or two levels down), how each runs, and suggested `workspaces`; never writes or follows a symlink; refused on a scoped server                                                                                                                     |
+| `manifest_draft`    | `/api/onboard/manifest`                    | The side-car `repo add` would write for `path`, validated (`draft`, `validation`), nothing written; `ask` and `choices` when it can start in several ways (call again with `run`)                                                                                              |
 
 **Health states.** A service with no verdict says why in `why`: no health
 check in the manifest for the env, remote with no check or `target.url`
@@ -1932,6 +2062,13 @@ orchestrator. It is off unless `mcp.actions` names it. A scoped server
 itself. The web server checks the same rule, and the resume route is the
 only agent route an agent's token reaches.
 
+`agent_import` (AG-17.1) brings in a conversation started outside Den as an
+agent: with no `session` it lists them, with `session` and `persona` it
+brings one in (see [Bring in a conversation](#bring-in-a-conversation)). It
+is off unless `mcp.actions` names it, and a scoped server reaches its own
+workspace or a granted one. Without it, an agent's token gets 403 on both
+the list and the import.
+
 ### Guards
 
 - **Lifecycle only, local only.** The service tools run a manifest's `up`,
@@ -2038,10 +2175,12 @@ An agent is a **persona** (who) in a **workspace** (where), run by a
 server scoped to its workspace.
 
 ```
-<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]
+<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--name <name>] [--id <id>]
 <cli> agents list -w <ws> [--json]
 <cli> agents stop <id> [-w <ws>]
 <cli> agents resume <id> [-w <ws>]
+<cli> agents import -w <ws> [--runtime <r>] [--json]          # conversations to bring in
+<cli> agents import -w <ws> --session <id> --persona <p>      # bring one in
 <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)
@@ -2052,7 +2191,13 @@ server scoped to its workspace.
   checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
   `agents.max_concurrent` (agents only: plain sessions never count). The id defaults to the persona's id; an id is
   unique in the distribution, so a second workspace's planner gets
-  `planner-<ws>` unless you give `--id`.
+  `planner-<ws>` unless you give `--id`. A persona that already has an
+  agent there, running or stopped, starts another: `planner-2`,
+  `planner-3`. A stopped agent is continued by Resume or Start fresh,
+  never by a new start. `--id` is exact: a running id is refused.
+  `--name "API spike"` makes the id its slug, `api-spike`, titled as
+  typed; a running agent there with that id or title is refused, and a
+  stopped one makes it `api-spike-2`.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
   persona, runtime, model, workspace, cwd, session and times, and what it was
   started with from the Start dialog: `version` (the model's, "latest" or
@@ -2085,6 +2230,39 @@ server scoped to its workspace.
   exits non-zero, Den prints the exit code and its last lines (at most 10,
   secret-shaped values redacted) and exits 1.
 
+#### Bring in a conversation
+
+A conversation you started in a terminal outside Den (Claude Code, in the
+workspace's own folder or one inside it, or a folder of one of its repos,
+a repo added by path outside it too) can become a Den agent. When
+workspaces share one repos root, only each one's repos' folders count,
+and the root itself only exactly; another workspace's conversation is
+refused by id. Agents ›
+**Bring in** lists them, newest first, with the persona list; `agents
+import -w <ws>` lists them too.
+
+- Den reads the runtime's own history: Claude Code's
+  `~/.claude/projects/<folder>/<id>.jsonl` (or under `CLAUDE_CONFIG_DIR`).
+  It reads only the first and last 64 KB of each file, for the folder it
+  ran in, its latest `/rename` and its first prompt. It never reads a whole
+  transcript, and it lists at most 50.
+- Bringing one in runs the runtime's resume (`claude --resume <id>`) in the
+  folder it ran in, as a new agent with the persona you pick. From then on
+  Den's token, MCP config, hooks, guards and audit trail apply. It is an
+  agent like any other: stop, resume, rename. The record notes
+  `broughtInAt`.
+- **One writer only.** A conversation written in the last minute is taken
+  to be still open in another terminal: "Still open in another terminal.
+  Close it there first" (HTTP 409 `open_elsewhere`). A conversation an
+  agent already continues is refused too (409 `already_agent`).
+- The agent's id is the persona's, or `<persona>-2`, `-3`… when that is
+  taken; `--id` sets one. An existing agent is never overwritten.
+- Only den-claude can bring one in for now. Other runtimes say "<runtime>
+  can't bring in a conversation yet".
+- Routes: `GET /api/workspaces/<ws>/conversations[?runtime=<r>]` and `POST
+/api/workspaces/<ws>/conversations/<id>/import` `{ persona, runtime?, id?
+}`. A person's only, unless MCP `agent_import` is opted in.
+
 ### On the Workspaces page
 
 The selected workspace's agents are listed under its repo table, one row

package/package.json

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

package/src/shared/actor-token.ts

@@ -199,6 +199,18 @@ export function revokedAgentIds(stateDir: string): Set<string> {
   return out;
 }
 
+/**
+ * Whether agent `agentId` holds a token that isn't revoked: stopping it
+ * deletes its tokens, `web logout --all` marks them revoked (ON-3: a held
+ * write of an agent that is gone never runs).
+ */
+export function agentTokenLive(stateDir: string, agentId: string): boolean {
+  const actor = `agent:${agentId}`;
+  return Object.values(load(stateDir).tokens).some(
+    (r) => r.actor === actor && !r.revokedAt,
+  );
+}
+
 /** What a presented token was minted as, live or not; null when unknown. */
 export function lookupActorToken(
   stateDir: string,