@monster-orange/den 0.4.14 → 0.4.16

package/CHANGELOG.md

@@ -4,6 +4,200 @@ 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.16] - 2026-11-08
+
+### Added
+
+- **Change an agent's persona (AG-18).** **Change persona…** in the
+  agent pane's ⋯ menu (running or stopped), and `<cli> agents persona
+  <id> <persona> [--model <m>] [--now | --after-turn]`. Den stops the
+  session and resumes the same conversation with the new persona's role
+  prompt, permission mode and allowed commands; the history, id, name,
+  workspace, folder, tab and the model it runs stay. The dialog marks the
+  current persona and lists what changes. Mid-turn it never stops a turn
+  unasked: "It's working. Change after this turn, or stop it now?" (409
+  `busy`); After this turn waits for the turn to end, Stop it now stops
+  it. The wait lives in the server's memory: if Den restarts first, the
+  change is dropped, the record no longer marks it pending, and the audit
+  trail says "persona change cancelled: Den restarted". A person's only: an agent's token is refused (403), and there is no
+  MCP tool. Only a runtime that can resume offers it. The record keeps
+  `personaChanges`, and the audit trail records each change. Route `POST
+  /api/workspaces/<ws>/agents/<id>/persona`.
+
+### Changed
+
+- **Bring in keeps the conversation's model, and says what the persona
+  changes (AG-17.1c).** It used to switch the conversation to the
+  persona's model, and drop MCP servers the conversation had outside Den,
+  without a word. Now the model stays the one its last answer came from
+  ("Keeps <model> from the conversation"; Advanced or `--model` picks
+  another), and a short list under the persona says "From now on it works
+  as <persona>: its role, its permissions (<mode>), Den's tools and
+  guards. Its history stays.", plus "It won't have: <servers>." for MCP
+  servers seen in its transcript that Den won't load. The persona of the
+  latest agent that worked in its folder is preselected (`suggest`), never
+  submitted. The list adds `model`, `lost` and `suggest`; the import takes
+  `model` and `version`.
+- **The signed-out page shows Sign in with GitHub once the owner is
+  linked, with no reload.** With no owner yet it watches the session
+  probe (which now says `github.state` to a signed-out browser), and step 1
+  turns done and the button appears as soon as `web owner link` finishes.
+
+- **The signed-out page explains Sign in with GitHub (SEC-2a-UX).** It
+  shows the same three steps whether or not an owner is linked: on the
+  machine Den runs on, run `<cli> web owner link` (or use Settings ›
+  Access there); enter the code it shows at github.com/login/device and
+  approve; come back and press Sign in with GitHub with the same account.
+  Once an owner is linked, step 1 shows as done ("Owner: @login") and the
+  button follows the steps. Below them: only the owner's GitHub account
+  can sign in this way, anyone else uses Approve this computer, and Learn
+  more opens docs/distributions.md, "Signing in with GitHub". English,
+  Spanish and Japanese.
+- Another GitHub account is refused with "@login isn't the owner of this
+  Den. Only the owner's account can use Sign in with GitHub. Use Approve
+  this computer instead." It no longer says to ask the owner to add you:
+  a Den has one owner, and no one to add.
+
+### Fixed
+
+- An open agent pane stayed on the old session after Change persona, Resume
+  or a rotation, showing "[the session exited (143)]" while the list showed
+  the new one running. A pane now follows its agent: it moves to the new
+  session in the same slot, keeps its scrollback, and says "Switched to
+  <persona>". After a session ends the page looks again every second for
+  15 s, so the switch shows within about 2 s.
+
+### Migrations
+
+- None.
+
+## [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

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.14/hero-dark.png">
-  <img src="docs/images/0.4.14/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.16/hero-dark.png">
+  <img src="docs/images/0.4.16/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.14/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.16/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.14/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.14/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.14/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.14/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.16/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.16/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.16/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.16/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
@@ -1566,14 +1687,31 @@ the account's id and login, never a token, and no other account gets in.
   `web owner unlink`. Settings › Access does the same in the browser
   (Link your GitHub account, Unlink): shell-grade actions, for a signed-in
   browser and never an agent's token.
-- **Sign in with GitHub** on the signed-out page shows a code and
-  `github.com/login/device`. The server runs the flow, and when the owner
-  approves it sets the same never-expiring session cookie a one-time link
-  sets, and the page reloads signed in. Another account sees "@<login>
-  isn't allowed on this Den". The token is thrown away either way. At most
-  three sign-ins wait for GitHub at once; a code expires as GitHub says
-  (15 minutes). With no owner linked the page says to run
-  `web owner link`.
+- **Sign in with GitHub** on the signed-out page shows the same three
+  steps whether or not an owner is linked:
+  1. On the machine Den runs on, run `web owner link`, or use
+     Settings › Access there.
+  2. It shows a code. Enter it at `github.com/login/device` and approve.
+  3. Come back to the signed-out page and press **Sign in with GitHub**,
+     with the same GitHub account.
+
+  Once an owner is linked, step 1 shows as done ("Owner: @<login>") and
+  the button follows the steps; before that there is no button. Below the
+  steps the page says only the owner's GitHub account can sign in this
+  way, and that anyone else uses **Approve this computer**; **Learn more**
+  opens this section. With no owner yet, the page watches (the session
+  probe, `GET /api/session`, says `github.state` to a signed-out
+  browser): once the owner is linked on the machine, step 1 shows done
+  and the button appears, with no reload.
+
+- Pressing the button shows a code and `github.com/login/device`. The
+  server runs the flow, and when the owner approves it sets the same
+  never-expiring session cookie a one-time link sets, and the page reloads
+  signed in. Another account sees "@<login> isn't the owner of this Den.
+  Only the owner's account can use Sign in with GitHub. Use Approve this
+  computer instead." Den has one owner, so there is no one to add. The
+  token is thrown away either way. At most three sign-ins wait for GitHub
+  at once; a code expires as GitHub says (15 minutes).
 - **Settings › Access** lists the linked devices (the browser, how it
   signed in, the client address when the edge vouched for one, created and
   last seen; "This device" on yours), each with **Revoke**, which ends its session at once (its
@@ -1785,13 +1923,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 +1999,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 +2027,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`
@@ -2045,12 +2192,13 @@ 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 import -w <ws> --session <id> --persona <p> [--model <m>]  # bring one in
+<cli> agents persona <id> <persona> [-w <ws>] [--model <m>] [--now | --after-turn]  # change its persona
 <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)
@@ -2065,6 +2213,9 @@ server scoped to its workspace.
   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
@@ -2100,8 +2251,11 @@ server scoped to its workspace.
 #### Bring in a conversation
 
 A conversation you started in a terminal outside Den (Claude Code, in the
-workspace's folder, a folder inside it, or a folder of one of its repos,
-a repo added by path outside it too) can become a Den agent. Agents ›
+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.
 
@@ -2115,6 +2269,24 @@ import -w <ws>` lists them too.
   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`.
+- **What the persona changes.** The persona is the role it takes on from
+  now on: its role prompt, its permission mode and allowed commands, and
+  Den's tools and guards. The history stays. The dialog says so under the
+  persona list: "From now on it works as <persona>: its role, its
+  permissions (<mode>), Den's tools and guards. Its history stays."
+- **The model stays the conversation's own.** Den reads the model of its
+  last answer (`message.model` on the last assistant record, in the ends
+  it reads) and runs it on that: "Keeps <model> from the conversation".
+  Advanced (or `--model`) picks another. With no model in the
+  transcript, the persona's applies.
+- **The MCP servers it won't have.** An agent runs with Den's MCP only
+  (`--strict-mcp-config`). When the transcript shows tool calls from other
+  servers (`mcp__<server>__…`), the dialog names them: "It won't have:
+  <servers>." The list's `lost` field has them.
+- **A suggested persona.** The list's `suggest` is the persona of the
+  latest agent of the workspace that worked in the conversation's folder
+  (or a folder inside it, or one containing it), else the workspace's
+  latest agent's. The dialog preselects it; you confirm with Bring in.
 - **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
@@ -2124,8 +2296,43 @@ import -w <ws>` lists them too.
 - 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.
+/api/workspaces/<ws>/conversations/<id>/import` `{ persona, runtime?, id?,
+model?, version? }`. A person's only, unless MCP `agent_import` is opted
+  in.
+
+#### Change an agent's persona
+
+**Change persona…** (the agent pane's ⋯ menu, running or stopped) and
+`agents persona <id> <persona>` switch an agent to another persona on the
+same conversation. Den stops its session and resumes the conversation with
+the new persona's role prompt, permission mode and allowed commands (the
+old persona's mode and commands go). The history stays, and so do the
+agent's id, name, workspace, folder, grants, tab and slot, and the model it
+runs unless Advanced (`--model`) picks another. The dialog lists the
+personas with the current one marked, and the same "From now on it works
+as…" line as Bring in.
+
+- **Never mid-turn without asking.** While it works (den-claude: its
+  transcript's last record is a tool call, or a prompt or tool result with
+  no answer yet), the change is refused: "It's working. Change after this
+  turn, or stop it now?" (HTTP 409 `busy`). **After this turn**
+  (`--after-turn`, `when: "after-turn"`) waits for the turn to end, up to
+  30 minutes, and then switches (the API answers 202 `pending` at once;
+  the record marks it `pendingPersona` while it waits). The wait lives in
+  the server's memory: if Den restarts first, the change is dropped, the
+  mark is cleared at start, and the audit trail records "persona change
+  cancelled: Den restarted";
+  **Stop it now** (`--now`, `when: "now"`) stops it and switches.
+- **A person's only.** An agent could widen its own permissions with it,
+  so an agent's token is refused (403), the CLI refuses inside an agent's
+  session, and there is no MCP tool.
+- Only a runtime that can resume offers it (`personaChange: true` on the
+  agent's row); others can't.
+- The record keeps each change in `personaChanges` (from, to, when, and
+  who), and the audit trail records "persona <id> in <ws>: <from> → <to>,
+  by <who>".
+- Route: `POST /api/workspaces/<ws>/agents/<id>/persona` `{ persona, model?,
+version?, when? }`.
 
 ### On the Workspaces page
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "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,