@monster-orange/den 0.4.0 → 0.4.2

package/README.md

@@ -1,169 +1,99 @@
-# Den
-
-Den is a config-driven local development appliance. It starts the repos you
-work on in dependency order, puts them behind a local HTTPS edge, gives you a
-web UI and a CLI over all of it, and runs smoke, browser, API, journey,
-security and performance suites against the environments you declare.
-
-Den knows nothing about any particular organisation. Everything specific to
-yours — product name, repos, environments, hosts, secrets backend, test
-accounts — lives in **your distribution**, not in Den.
-
-> **Status: 0.2.0**: `npm install @monster-orange/den`. Den is pre-1.0; each release lists the changes a distribution makes under **Migrations** in [CHANGELOG.md](CHANGELOG.md).
-
-## Make it your own
-
-1. **Create** a distribution named after your product:
-
-   ```sh
-   npx @monster-orange/den create acme      # → ./acme
-   cd acme && npm install
-   ```
-
-2. **Name** it: `den.yml` holds `product: { name: acme }`, so the CLI is
-   `./bin/acme`, env vars are `ACME_*`, state lives in `~/.acme`. Pass
-   `--cli`, `--env-prefix` or `--title` to `create`, or edit `den.yml`.
-3. **Brand** it: `brand:` in `config/acme.yml` sets the name, tagline and
-   banner people see in the CLI and web UI.
-4. **Point it at your repos**: set `github_org` in `config/acme.yml`, then
-   `./bin/acme register ../shop-api` (or add a manifest per repo under
-   `manifests/`).
-5. **Run** it: `./bin/acme up`, `./bin/acme web`, `make test`.
-
-Every field, the bin shim, the make fragment and upgrading are in
-[docs/distributions.md](docs/distributions.md);
-[examples/distribution/](examples/distribution) is what `create acme` writes.
-
-## Distributions
-
-You run Den through a small repo of your own (a _distribution_):
-
-```
-my-dev/
-├── den.yml               # who this distribution is (below)
-├── package.json          # pins an exact @monster-orange/den version
-├── config/<name>.yml     # your org config
-├── config/environments/  # one <env>.json per environment
-├── manifests/            # manifests for repos that don't carry their own
-├── tests/pillars/<pillar>/   # your own suites (e.g. tests/pillars/perf/<module>/test.js)
-├── bin/<cli>             # shim: DEN_ROOT=<this dir> exec node_modules/@monster-orange/den/bin/den
-└── Makefile              # include node_modules/@monster-orange/den/make/den.mk
+<p align="center">
+  <img src="docs/images/preview/mark.svg" width="72" alt="Den">
+</p>
+<h1 align="center">Den</h1>
+<p align="center"><b>Your whole stack, up and green, in one place. Built so you and your agents work by the same rules.</b></p>
+<p align="center">
+  <a href="https://www.npmjs.com/package/@monster-orange/den"><img src="https://img.shields.io/npm/v/@monster-orange/den" alt="npm"></a>
+  <img src="https://img.shields.io/npm/l/@monster-orange/den" alt="licence">
+  <a href="https://github.com/Monster-Orange/den/actions/workflows/ci.yml"><img src="https://github.com/Monster-Orange/den/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+</p>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.1/hero-dark.png">
+  <img src="docs/images/0.4.1/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>
+
+## What Den is
+
+Den is an opinionated local development framework for solo developers and small teams. You point it at the
+repos you work on. Den starts them in the right order, puts them behind a local edge, and shows you the
+whole thing in one web shell and one CLI: what's up, what's down, why, and the fix.
+
+It doesn't replace your tools. Your repos, Docker, your test runners, your secrets store and your agents stay
+yours. Den connects them and turns on good practice from the start.
+
+<p align="center">
+  <img src="docs/images/0.4.1/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
+
+- **"How do I run this?" goes away.** Each repo declares how it starts, what it needs and how to check it's
+  healthy. Den works out the order and brings everything up, the same way on every machine.
+- **One place to look.** Health, logs, runs, routes and certificates for every service, in one shell, instead
+  of eight terminals and a wiki page.
+- **Real hostnames locally.** Every service gets a proper hostname behind a local edge, over HTTPS when you
+  turn it on (a local CA with mkcert, or certificates you bring). Cookies, OAuth redirects and CORS behave as
+  they do in production.
+- **Several workspaces at once.** Keep feature branches side by side as workspaces. Health covers every active
+  one, and `up`, `down`, `restart` and `setup` take `-w <workspace>`, or find the service you name across them.
+- **Tests are part of the loop.** Smoke, browser, API, user journeys, security and performance suites run against
+  the environments you declare.
+- **Agents work by the same rules as you.** Start an agent from a persona (planner, orchestrator, developers,
+  devops, reviewer, UX designer, or your own) in a workspace. Its terminal opens in the Agents tab and keeps
+  running when you close the page or restart the web server. Over MCP it sees your stack with the same guards
+  and audit trail as a person, under a token of its own. Agents can read and investigate. Acting is opt-in,
+  and the lock still guards starting and stopping things.
+- **Safe on localhost, signed in beyond it.** On localhost there is nothing to sign in to. Reached through the
+  edge or your network, every page and call needs a sign-in, and there is no password: `acme web login` prints a
+  one-time link.
+- **Opinionated, not locked in.** Good defaults are switched on, and almost everything can be switched off. The
+  safety guards stay on. Den never needs our accounts, secrets or certificates. Everything specific to you
+  lives in your own repo.
+
+<p align="center">
+  <img src="docs/images/0.4.1/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.1/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.1/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.1/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
+
+You need Node 22.13 or later, and Docker for anything that runs in containers. mkcert is only needed if you want Den to issue local HTTPS certificates.
+
+```sh
+npx @monster-orange/den create acme     # your own Den, named after your product
+cd acme && npm install
+./bin/acme register ../shop-api          # add a repo (repeat for each one)
+./bin/acme up                            # start everything, in order
+./bin/acme web                           # open the shell
 ```
 
-`den.yml` names the product. Every runtime name derives from it:
+That's it: `acme` is now your tool, with your name, your CLI and your config, in a repo you own.
+[Step by step →](docs/reference.md#make-it-your-own)
 
-```yaml
-product:
-  name:
-    acme # CLI "acme", env vars ACME_*, config/acme.yml,
-    # manifests .acme.yml, state ~/.acme,
-    # managed clones .acme-services/, workspaces acme-workspaces/
-  # Override any of them: cli, env_prefix, config, manifest, state_dir,
-  # services_dir, workspaces_dir
-```
+## How it fits together
 
-Den's own checkout is a distribution named `den`, so in this repo the CLI is
-`./bin/den`, the config is `config/den.yml`, and env vars are `DEN_*`.
-
-## Repos opt in with a manifest
-
-A repo joins by carrying a manifest at its root (`.<name>.yml`, e.g.
-`.den.yml`) whose commands delegate to the repo's own targets. Den never
-reaches inside a repo beyond that. When a repo has no manifest, the
-distribution can hold one for it in `manifests/<repo>.<name>.yml`; the repo's
-own manifest always wins.
-
-```yaml
-# demo-api: a self-contained service. Nothing it calls, so it starts alone.
-version: 1
-name: demo-api
-application: shop # the application this repo belongs to (den apps)
-compose:
-  files: [docker-compose.yml]
-  routes:
-    api: api:8080 # https://api.demo-api.<edge domain>
-services:
-  demo-api:
-    commands:
-      local:
-        setup: make setup
-        preflight: make test
-# OWASP ZAP target for the security pillar (`make test-sec-api env=local`).
-security:
-  api:
-    hosts:
-      local: ["https://api.demo-api.globex.localhost"]
-```
+<p align="center"><img src="docs/images/preview/how-it-fits.svg" width="100%" alt="Den, the engine, runs your distribution, which holds your config; the distribution groups repos into workspaces, and each repo declares its services"></p>
 
-That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
-[`examples/demo/`](examples/demo/).
-
-## What it does
-
-- **Workspaces.** A workspace is a set of repos. Each is either
-  _dev-managed_ (your checkout, your branch) or _managed_ (cloned by Den and
-  kept on a tracking branch).
-- **Derived dependency graph.** Start and stop order comes from real signals in
-  each repo — SDK imports, `*_URL` env vars, IaC references, event rules,
-  readiness probes — tuned in config with `graph.aliases`, `graph.edges` and
-  an optional shared local-infra repo (`graph.infra`).
-- **Local HTTPS edge.** One local proxy routes `https://<route>.<domain>` to
-  each service, with an optional project CA.
-- **Test pillars.** `smoke`, `browser` (synthetic Playwright), `api`,
-  `journeys` (agent-driven), `perf` (k6), `security` (OWASP ZAP against hosts
-  you own) and `suites` (a repo's own commands).
-- **Releases.** A release view over the repos and deploy workflows your config
-  lists.
-- **Web UI and CLI** over the same state.
-
-## Strategies
-
-Concerns that vary by org are strategies selected in config, never hard-wired:
-
-| Concern          | Built-in choices                        | Chosen in                                                                                                            |
-| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| Secrets backend  | `none`, `env`, `doppler`, `1password`   | `secrets.provider` in the org config; per engineer in `config/local/user.yml`; per shell `<PREFIX>_SECRETS_PROVIDER` |
-| Test-user tokens | `local-jwt`, `cognito`, `auth0`, `none` | `auth.provider` in `config/environments/<env>.json`                                                                  |
-
-A new secrets backend implements `SecretsProvider`
-(`src/shared/secrets/types.ts`) and registers as a strategy
-(`src/shared/secrets/strategies.ts`); a distribution needs no store at all
-(`none`, see "Secrets" in `docs/distributions.md`). A new identity provider implements a token
-provider in `src/shared/auth/token-providers/`.
-
-## CLI
-
-```bash
-den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
-den down [repo]        # stop it cleanly (--with-deps: and what it sits on)
-den status             # service health for the active workspace
-den apps               # Org > Application > Repo > Services
-den graph [repo]       # the derived dependency graph
-den logs [repo]        # tail a repo's local logs
-den use-local [repo]   # use your checkout · use-managed [repo] to switch back
-den workspace list     # workspaces (activate · deactivate · use · create · delete)
-den run                # run test suites (interactive, or with options)
-den web                # the web UI
-den --help             # everything else
-```
+- **Den** is the engine, from npm. It knows nothing about your company.
+- **Your distribution** (`acme`) is a small repo you own. It holds your product name, brand, environments,
+  hosts and secrets setup.
+- **Workspaces** group the repos you work on together. **Manifests** in each repo say how its services start,
+  connect and get checked.
 
-In a distribution the command is that distribution's `cli` name.
+## Coming next
 
-## Developing Den
+One workspace focus with Switch, agent pane layouts, and a Start dialog with personas, roles and a choice of
+runtime and model.
 
-```bash
-npm ci
-npm run typecheck
-npm run lint
-npm test
-DEN_ORG_NAMES_FILE=<patterns file> node scripts/org-name-gate.mjs
-```
+## Docs
 
-CI runs the same gates. The org-name gate fails the build when any file names
-an organisation, product, host or account; its patterns are kept out of this
-repo (a CI secret) so the list itself is never published. See
-[CONTRIBUTING.md](CONTRIBUTING.md).
+[Reference](docs/reference.md) (configuration, manifests, strategies, CLI) · [Distributions](docs/distributions.md) ·
+[Changelog](CHANGELOG.md)
 
-## License
+Found a bug or have an idea? [Open an issue](https://github.com/Monster-Orange/den/issues/new).
 
-[MIT](LICENSE)
+MIT licence.

package/docs/distributions.md

@@ -563,16 +563,16 @@ product:
   # workspaces_dir: acme-workspaces
 ```
 
-| Field            | Default              | What it names                                                     |
-| ---------------- | -------------------- | ----------------------------------------------------------------- |
-| `name`           | `den`                | The product; `[a-z][a-z0-9-]*`. Everything below derives from it  |
-| `cli`            | `<name>`             | The command shown in help, hints and the web UI                   |
-| `env_prefix`     | `<NAME>` (`-` → `_`) | Env vars: `<PREFIX>_ROOT`, `<PREFIX>_HOME`, `<PREFIX>_INVOKE_CWD` |
-| `config`         | `config/<name>.yml`  | The org config, relative to the distribution root                 |
-| `manifest`       | `.<name>.yml`        | The manifest file a repo carries; the `.json` twin is also read   |
-| `state_dir`      | `~/.<name>`          | Per-user state: web server, daemons, logs, history                |
-| `services_dir`   | `.<name>-services`   | Managed clones, relative to the distribution root                 |
-| `workspaces_dir` | `<name>-workspaces`  | Workspace checkouts, relative to the distribution root            |
+| Field            | Default              | What it names                                                                                                        |
+| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`           | `den`                | The product; `[a-z][a-z0-9-]*`. Everything below derives from it                                                     |
+| `cli`            | `<name>`             | The command shown in help, hints and the web UI                                                                      |
+| `env_prefix`     | `<NAME>` (`-` → `_`) | Env vars: `<PREFIX>_ROOT`, `<PREFIX>_HOME`, `<PREFIX>_INVOKE_CWD`                                                    |
+| `config`         | `config/<name>.yml`  | The org config, relative to the distribution root                                                                    |
+| `manifest`       | `.<name>.yml`        | The manifest file a repo carries; the `.json` twin is also read                                                      |
+| `state_dir`      | `~/.<name>`          | Per-user state: web server, daemons, logs, history (a relative path is relative to den.yml's directory, not the cwd) |
+| `services_dir`   | `.<name>-services`   | Managed clones, relative to the distribution root                                                                    |
+| `workspaces_dir` | `<name>-workspaces`  | Workspace checkouts, relative to the distribution root                                                               |
 
 Env vars, with `ACME` as the prefix:
 
@@ -1179,6 +1179,86 @@ Den's scripts run with the engine's tsx (`tsxCommand()`), never through `npx`
 or a path relative to the current directory. In Den's own checkout both roots
 are the same directory.
 
+## Signing in
+
+On localhost nothing asks you to sign in: every page, the agents and the
+terminal work as they are, and the lock (R8) is the only prompt (for
+privileged actions). Signing in is for when the server is reached beyond
+this machine: through the edge hostname, a LAN address, or a bind that
+isn't loopback (`DEN_BIND_HOST`).
+
+There is no password. Reading `web.secret` (32 random bytes, mode 0600 in
+the state dir, made at the first `web up`) proves you are this computer's
+user, and the CLI does that for you:
+
+```bash
+./bin/acme web open        # start if needed, and sign this browser in (a new tab)
+./bin/acme web login       # print a one-time sign-in link, for another browser
+./bin/acme web sessions    # the signed-in browsers: id, created, last seen, host, user agent
+./bin/acme web logout <id> # sign out one browser (an id prefix from `web sessions`)
+./bin/acme web logout      # sign out every browser
+./bin/acme web logout --all  # and rotate web.secret and revoke every agent's token
+```
+
+- **The link** is `http://localhost:<port>/auth?c=<code>`, with `&next=<path>`
+  for where to land (`web login --next /settings`). The code works once,
+  within 60 seconds, and only this server's secret makes one. It is printed
+  only on the one line you asked for (`web login`, or `web up` when it
+  couldn't open the browser), never logged. Through the edge or a LAN name,
+  the cookie belongs to that name: `web login --origin https://acme.acme.localhost`
+  (the signed-out page there shows the exact command).
+- **The cookie** (`den_session_<port>`) is HttpOnly, SameSite=Strict and
+  Path=/, and Secure when the request came over HTTPS through the edge. The
+  session lives server-side (`web-sessions.json`, 0600, in the state dir)
+  and never expires: it ends at sign-out, `web logout`, or `web logout
+--all`. The cookie asks the browser to keep it for 400 days, the most a
+  browser allows. The 0.4.1-dev `web.session.idle` and `web.session.max`
+  keys are ignored; the server logs a warning naming each one it finds.
+
+  `web sessions`' LAST SEEN is written at most once a minute (60 s), so it
+  equals CREATED right after a sign-in.
+
+- **What needs it.** On loopback, nothing: pages and read-only calls are
+  open, and changes (an agent's start or resume and the terminal included)
+  need only the page's own Origin and CSRF token, which the shell sends.
+  The Host allowlist, the Origin check and the CSRF token are what stop
+  another site or a rebinding DNS name. Through the edge, or from another
+  machine, every page and call needs a signed-in browser (or a bearer). A
+  page there shows "Sign in to use <name>" with the command to run; it
+  never asks for a secret. `/api` answers 401 `signin_required`.
+- **localhost is the canonical name.** A cookie set on `localhost` isn't
+  sent to `127.0.0.1`, so the links Den prints use `localhost`.
+- **Browsers.** Chromium, Firefox and Safari 16.4 or later: a sign-in link
+  needs the browser to send `Sec-Fetch-Site` or `Origin`.
+- **Scripts and the CLI** are unaffected: the CLI and the MCP server send
+  the person token (`web token --print` prints it for curl). After `web
+logout --all` the old token is refused; the CLI reads the new one.
+- **`web logout --all` is the "something leaked" button.** It signs out
+  every browser, rotates `web.secret` (every person token is void) and
+  revokes every agent's token: a running agent's next call gets 401
+  `token_revoked` ("restart or resume the agent to get a new one"). Plain
+  `web logout` (one browser, or every browser) leaves agent tokens alone.
+- **Another machine.** `DEN_BIND_HOST=0.0.0.0` (or any non-loopback
+  address) starts only with `web.allow_plain_http_remote: true` in
+  `config/local/user.yml`, since a session cookie would otherwise cross the
+  network in clear text. Having the edge in front is not enough: the
+  server's own port would still answer plain HTTP on every interface. Only
+  `config/local/user.yml` is read (a choice for that machine); the key in
+  the distribution config is ignored, and the server logs a warning naming
+  the file. With it, the machine's own addresses and host name are accepted
+  with the port, and every route there needs a session.
+- **The edge** reaches Den on loopback (macOS, through
+  `host.docker.internal`), so it needs no other bind. On Linux, where the
+  edge container reaches the host on the Docker bridge, the one other bind
+  allowed without the key is the bridge address (`172.16.0.0/12`, for
+  example `DEN_BIND_HOST=172.17.0.1`), and only with the edge configured.
+- **The edge hostname is believed only from the edge.** A request whose
+  `Host` is the edge hostname is accepted only from a peer the edge could
+  be (loopback, the Docker bridge range or Docker Desktop's VM network);
+  from any other address it is
+  421 `misdirected`, so a LAN client can't send the edge's name straight to
+  the server's port.
+
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
@@ -1501,9 +1581,16 @@ the profile's `state_dir` (`~/.<name>`), or `<PREFIX>_HOME`.
 - Stopping the host (`sessions host --stop`, or a reboot) ends its
   sessions. They stay listed as exited, with their scrollback, until
   `sessions kill` removes them.
-- `agents.max_concurrent` caps the sessions running at once (default 4):
+- `sessions.max_concurrent` caps the plain sessions (`sessions start`)
+  running at once (default 8), and `agents.max_concurrent` the agents
+  (default 4). Each counts only its own, so a few plain shells never stop
+  an agent from starting, nor agents a shell. Past either, the start is
+  refused, naming the key ("2 sessions are running and
+  sessions.max_concurrent is 2"); `<cli> validate` names a wrong value.
 
   ```yaml
+  sessions:
+    max_concurrent: 8
   agents:
     max_concurrent: 4
   ```
@@ -1534,7 +1621,7 @@ server scoped to its workspace.
 
 - `start` runs the agent as session `<dist>-<ws>:<id>` in the workspace's
   checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
-  `agents.max_concurrent`. The id defaults to the persona's id; an id is
+  `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`.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
@@ -1554,6 +1641,80 @@ 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.
 
+### On the Workspaces page
+
+The selected workspace's agents are listed under its repo table, one row
+per agent: its id and persona, runtime, state (`running`, `stopping`,
+`stopped`, `ended` or `exited (<code>)`), directory, and when its session
+started. The workspace header counts them ("2 agents").
+
+- **Stop** sends its session TERM, as `agents stop` does; the row reads
+  `stopping…` until the session has gone. **Resume** shows only when
+  `agents resume` would run: the runtime declares resume and the agent is
+  not running.
+- **+ Start agent** picks a persona (Den's pack, then
+  `agents.persona_packs`) and a runtime (the persona's own unless you pick
+  one; one that can't run here is listed, disabled), then Start.
+- The page and the CLI call the same operations and read the same agent
+  records, so an agent started in one is listed in the other. A workspace
+  lists its own agents only.
+- Start, Stop and Resume need the lock open (🔓, the same rule as a
+  service's Start), are capped by `agents.max_concurrent`, and are refused
+  for an agent (agents don't start agents from the page). Each one is in the
+  server log's activity, with you as its actor. The agent's environment is
+  the one below, built from the web server's environment.
+- **Open in Agents →** (the section header) opens the Agents tab for the
+  workspace, and **Open** on a row with a session opens its terminal there.
+
+The routes: `GET /api/workspaces/<ws>/agents`, `POST
+/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
+/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
+/api/personas` (personas and runtimes). Errors are the usual
+`{ ok: false, error, code, requestId }`: `locked` (423), `cap` (429),
+`conflict` (409, e.g. already running, or no resume), `not_found` (404),
+`exited_at_once` (502, with the session's last lines).
+
+### The Agents tab
+
+"Agents" in the rail (Develop, after Graph) is `/agents`: every session and
+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
+  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
+  token `web logout --all` revoked says "token revoked": stop and resume
+  it, or start it again.
+- **A pane** is the session's terminal: it shows the scrollback, then the
+  live output, and your keys go to the session; its size follows the
+  pane. Click more rows to tile up to four (a fifth closes the oldest).
+  The URL holds the open panes (`/agents?open=<id>,<id>`), so a link, a
+  reload or Back reopens them.
+- **Close** (×) detaches, as leaving the page does: the session keeps
+  running, and opening it again replays what you missed. **Stop** (an
+  agent only) is `agents stop`, behind the lock. **+ Start agent** (or
+  `/agents?start=1`) starts one and opens its pane; under All it asks for
+  the workspace.
+- ⌘K lists each as "Agents › <ws> / <name>", and "Start agent…".
+- Several browsers and `<cli> sessions attach` can attach to one session
+  at once and each sees every byte; the terminal's size is the last
+  one's to change it.
+- Terminals need the optional PTY module (`<cli> doctor`); without it the
+  page lists what there is and says so.
+- **Who can open one.** The terminal is shell-grade: on localhost the
+  page's own Origin and CSRF token, beyond loopback a signed-in browser
+  (the list says "Sign in to open terminals" otherwise), and an agent's
+  token only its own session's. Each attach and detach is in the server
+  log's activity, with its actor.
+
+The routes: `GET /api/sessions` (`{ sessions, workspaces, host, backend,
+io }`) and the WebSocket `/api/sessions/<id>/io` (subprotocol `den.io`, the
+CSRF token as `den.csrf.<token>`): binary frames are output and input, a
+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.
+
 ### An agent's environment
 
 An agent's environment starts empty and gets, in order:
@@ -1564,7 +1725,7 @@ An agent's environment starts empty and gets, in order:
 2. the variables its runtime names (`envPassthrough`; den-claude:
    `CLAUDE_CONFIG_DIR`);
 3. the runtime's launch env;
-4. `DEN_AGENT=agent:<id>`.
+4. `DEN_AGENT=agent:<id>` and `DEN_ACTOR_TOKEN` (below).
 
 Then every runtime's `scrubEnv` is removed (den-claude: `CLAUDECODE` and
 `CLAUDE_CODE_*`), whatever put it there. Nothing else of yours reaches it:
@@ -1585,10 +1746,49 @@ Without the PTY module it says the probe is unavailable; that is not a
 failure. Plain `doctor` never spawns anything; when agents are configured it
 adds a note to run `<cli> doctor --probe`.
 
+### An agent's token
+
+`agents start` (the CLI or the Workspaces page) mints a random `den_at_…`
+token for the agent and puts it in the session as `DEN_ACTOR_TOKEN`. Den
+keeps only its hash (`actor-tokens.json`, 0600, in the state dir) with the
+agent, its workspace, its grants and its session. Stop revokes it, and so
+does the session's end; resume mints a new one and the old one stops
+working. The `<cli>` and the MCP server Den starts for the agent send it, so
+the server audits their calls as the agent, from the token, never from a
+header (agent headers without the token are recorded as an unverified
+claim).
+
+An agent's token reaches only its own session's routes, and never a
+shell-grade route, `/api/web/*`, sign-in or sign-out, or the lock: it can't
+unlock, use the sudo password or start another agent (403
+`agent_forbidden`). A person's credential never reaches a session:
+`DEN_PERSON_TOKEN`, a person token's value and a path to `web.secret` are
+always removed, and `sessions start --keep-env` of one is refused and logged.
+An agent runs as your OS user, so it could still read `web.secret` itself;
+the token keeps what Den does on its behalf attributable and bounded.
+**The boundary is the server's token rules** (above), not a deny list.
+
+**The deny list is a convenience, not the boundary.** den-claude passes
+Claude Code a settings file (`--settings`) whose `permissions.deny` lists
+`Read` of `<state dir>/web.secret` and `<state dir>/sessions/**`, and
+`Bash` rules in Claude Code's wildcard form for the path
+(`Bash(*<state dir>/web.secret*)`, and each of `cat`, `head`, `tail`,
+`less`, `more`, `xxd`, `od`, `strings`, `base64` and `cp` followed by it),
+spelled as an absolute path, under `~` and under `$HOME`, with a path that
+has spaces also backslash-escaped. It binds cooperating agents only: an
+agent that ignores its permission config can read the files anyway. And
+it does not catch every spelling: a path relative to the agent's cwd
+(`cat ../.den/web.secret`, say), another program, a script or a copy under
+another name all get past it. The server's token rules (above)
+are the boundary: whatever an agent reads, its token reaches only its own
+session's routes, never a shell-grade route or the lock. OS-user isolation
+(a separate user, a container, a sandbox) is not in 0.4.x. `web logout
+--all` revokes every agent's token (above, under Signing in).
+
 **What the scope does not do.** An agent's MCP scope binds cooperating
 agents only. A runtime with a shell can still run `<cli>` itself, outside
-the scoped MCP server, and reach other workspaces; WS-3a and SEC-1 close
-that later. And the user's own Claude Code settings and hooks
+the scoped MCP server, and reach other workspaces (with its own token, so
+it is audited as the agent); WS-3a closes that later. And the user's own Claude Code settings and hooks
 (`~/.claude/settings.json`, its hooks, a project's `.claude/`) load in a
 den-claude agent, as in any `claude` you start.
 
@@ -1634,7 +1834,7 @@ are errors naming the file or the key.
 
 - **`den-claude`** (the default) needs `claude` on PATH; doctor reads its
   version from the install, without running it. It runs `claude --session-id
-<id> --mcp-config <file> --strict-mcp-config [--model <m>]
+<id> --mcp-config <file> --strict-mcp-config --settings <file> [--model <m>]
 --append-system-prompt <role prompt>`, so Den's MCP server is the agent's
   only one, and resumes with `claude --resume <id>`. Permission prompts stay
   in the agent's terminal: it passes `--permission-mode default` unless the