@monster-orange/den 0.3.0 → 0.4.1

package/docs/distributions.md

@@ -525,10 +525,11 @@ later plugins.
 
 ## doctor
 
-`<cli> doctor` lists every strategy kind in the registry (secrets, tls):
-the one this distribution selects, whether nothing chose it (implicit),
-and whether it can work on this machine, with the reason. It only checks
-PATH: it never runs a backend CLI, prompts, or prints a secret. It exits
+`<cli> doctor` lists every strategy kind in the registry (secrets, tls,
+session-backend): the one this distribution selects, whether nothing chose
+it (implicit), and whether it can work on this machine, with the reason.
+It only checks PATH (and, for session-backend, whether the PTY module
+loads): it never runs a backend CLI, prompts, or prints a secret. It exits
 1 when a strategy that will be used cannot work (an implicit secrets
 default is used only when a secret is asked for, so it never fails
 doctor).
@@ -536,11 +537,15 @@ doctor).
 ```
 Acme doctor: strategies
 
-  secrets  none                 ✓ available: no secrets backend configured
-  tls      mkcert (implicit)    ✗ unavailable: mkcert is not installed
+  secrets          none                 ✓ available: no secrets backend configured
+  tls              mkcert (implicit)    ✗ unavailable: mkcert is not installed
     ⚠ edge.tls is not set; defaulting to mkcert with a local CA. Set edge.tls explicitly.
+  session-backend  den-pty (implicit)   ✓ available: PTY module loaded
 ```
 
+`session-backend` is never a doctor failure: nothing needs a session until
+one is started (see Sessions).
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to
@@ -558,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:
 
@@ -1174,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
@@ -1323,8 +1408,8 @@ to one workspace for one agent:
 
 - **Pinned.** A tool that takes a `workspace` gets `<ws>` when none is given.
   A call naming another workspace is refused (`Refused: <tool>: this MCP
-server is scoped to workspace "<ws>" (agent:<id>); "<other>" is another
-workspace`) before anything reaches the web server. A refused call is
+server is scoped to workspace "<ws>" (agent:<id>; no grants); "<other>" is
+another workspace`; with grants, `grants: <a>, <b>`) before anything reaches the web server. A refused call is
   recorded in the activity trail, read tools included.
 - **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
   take only `<ws>`'s services, `manifest_validate` takes only an absolute path
@@ -1339,6 +1424,16 @@ workspace`) before anything reaches the web server. A refused call is
   entry gains `agent` and `workspace`, and the log line reads `· by
 agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
 <id>)` for every exec, run and sync.
+- **Granted.** `--grant <other>` (repeatable) also serves `<other>`, but only
+  when the org config's `agents.<id>.grants` lists it; otherwise the server
+  exits 2 (an agent can't grant itself one). A call naming a granted
+  workspace is reported to the web server before it runs, and its activity
+  entry names both (`workspace` and `targetWorkspace`; the log line reads
+  `▶ <tool> in workspace <other>, under a grant to agent:<id> of workspace
+<ws>`). `GET /api/activity?address=workspace:<ws>` lists these entries
+  under either workspace. `workspaces` lists `<ws>` and its grants, and tests run when either
+  is focused. Logs and `manifest_validate` stay on `<ws>`'s own services.
+  `agents start` passes an agent's grants for you (see [Agents](#agents)).
 - `<ws>` must exist in this distribution; until it does, every tool says so.
   The id is letters, digits, dots, dashes and underscores (at most 64). A bad
   or half-given scope is a usage error, exit 2. `--list` and `--call` take
@@ -1445,6 +1540,322 @@ authorise anything), and the MCP server's pid and session id. They travel as
 `acme/server` stream shows an agent's actions as `[agent]`, ending
 `· by agent <client> <version> (mcp pid <pid>, session <id>)`.
 
+## Sessions
+
+A session is a terminal that keeps running when the web server restarts:
+an argv in a PTY, owned by the distribution's **session host**. The host
+is one small detached process (`<cli> sessions host`) that the first
+client starts on demand; it serves `<stateDir>/sessions.sock` (mode 0600)
+and logs to `<stateDir>/logs/<cli>/sessions-host.log`. The state dir is
+the profile's `state_dir` (`~/.<name>`), or `<PREFIX>_HOME`.
+
+```
+<cli> sessions start --workspace <ws> --name <n> [--cwd <dir>] [--keep-env NAME…] -- <argv…>
+<cli> sessions list [-w <ws>] [--json]
+<cli> sessions attach <name|id>          # ctrl-] detaches; the session keeps running
+<cli> sessions kill <name|id> [--signal INT|TERM|KILL]
+<cli> sessions host [--stop]
+<cli> agents list -w <ws> [--json]
+```
+
+- A session is named `<dist>-<ws>:<n>`. `list -w <ws>` and `agents list
+-w <ws>` show that workspace's sessions only. Elsewhere a session can be
+  named in full, as `<ws>:<n>`, as a bare `<n>` only one session has, or by
+  its id.
+- It runs in `--cwd` (default: where you ran the command). Its environment
+  starts empty and gets only `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`,
+  `TERM` (default `xterm-256color`), `COLORTERM`, `LANG`, `LC_*`, `TZ` and
+  `TMPDIR` from yours; `start` names the variables it left out (names, never
+  values). `--keep-env NAME` adds one more: one exact name per flag,
+  repeatable, no globs. It is audited: the session host's log
+  (`<stateDir>/logs/<cli>/sessions-host.log`) gets a line naming each kept
+  variable and who asked, never its value, and says `credential-shaped` when
+  the value or name looks like a credential (it is still passed: you named
+  it). An agent can't use it: `agents start` has no `--keep-env`, and
+  `sessions start` refuses it when run by an agent (`DEN_AGENT` is set).
+  Every runtime's `scrubEnv` (den-claude: `CLAUDECODE`, `CLAUDE_CODE_*`) is
+  removed last, even a name you kept.
+- Every attachment gets all of its output; attaching prints `[attached to
+<name>]`, then replays the scrollback (2 MB per session, kept in
+  `<stateDir>/sessions/<id>.log`).
+- 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):
+
+  ```yaml
+  agents:
+    max_concurrent: 4
+  ```
+
+- A PTY needs a native module, `@lydell/node-pty`, which Den lists as an
+  optional dependency (prebuilt binaries for macOS, Linux and Windows,
+  nothing downloaded at install). Without it (`npm install
+--omit=optional`, another platform) everything else works, and `sessions
+start` and `<cli> doctor` say why den-pty is unavailable.
+- A state dir whose socket path would pass 103 bytes (the unix socket
+  limit) is refused with that reason; point `<PREFIX>_HOME` somewhere
+  shorter.
+
+## Agents
+
+An agent is a **persona** (who) in a **workspace** (where), run by a
+**runtime** (which CLI) in a [session](#sessions), acting through Den's MCP
+server scoped to its workspace.
+
+```
+<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]
+<cli> agents list -w <ws> [--json]
+<cli> agents stop <id> [-w <ws>]
+<cli> agents resume <id> [-w <ws>]
+<cli> agents personas [--json]
+<cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
+```
+
+- `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
+  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,
+  persona, runtime, model, workspace, cwd, session and times. It never holds
+  the environment or the command line. `list` reads it for persona, runtime
+  and model; a record whose session has gone is listed as `stopped` (after
+  `stop`) or `ended`.
+- `list` shows agents only: sessions with an agent record. A session from
+  `sessions start` is not an agent; `sessions list` shows it.
+- `stop` sends its session TERM and marks it stopped. `resume` works only
+  when the runtime declares resume and the session is not running: it starts
+  a new session in the same cwd that continues the last conversation. A
+  session that never got a prompt (no input with a line end) has no
+  conversation, so `resume` starts it fresh under the same conversation id
+  and says so.
+- After `start` or `resume`, Den watches the session for up to 3 s. If it
+  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:
+
+1. `PATH`, `HOME`, `USER`, `LOGNAME`, `SHELL`, `TERM` (default
+   `xterm-256color`), `COLORTERM`, `LANG`, `LC_*`, `TZ` and `TMPDIR` from
+   yours;
+2. the variables its runtime names (`envPassthrough`; den-claude:
+   `CLAUDE_CONFIG_DIR`);
+3. the runtime's launch env;
+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:
+not your tokens, not your shell's other variables, and not the Claude Code
+session you started it from (its session id, messaging socket and token,
+and the child-session marker that turns transcripts off). The agent record
+still holds no env. The agent's MCP server gets the distribution's location
+(`DEN_ROOT`, `<PREFIX>_ROOT`, `<PREFIX>_HOME`, when set) in its own config,
+so it reaches the same distribution.
+
+`<cli> doctor --probe` checks this through the real session host: it runs a
+short probe session for a plain session and for each available runtime's
+agent env (built as `agents start` builds it, running the probe instead of
+the runtime's CLI). The probe prints key names and whether each is
+credential-shaped, never values. Doctor exits 1, one row per finding, when a
+runtime's `scrubEnv` name or a credential-shaped variable reaches either.
+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.
+
+As a cooperative mitigation, 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. A
+deny list can't name every way to read a file (another program, a script,
+a copy under another name), so it is a speed bump. **It binds cooperating
+agents only**: an agent that ignores its permission config, or reads the
+file some other way, can still read them. 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 (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.
+
+### Personas
+
+A persona is a markdown file: YAML front matter, then the role prompt. It is
+a Claude Code agent file, read as it is, plus a few keys of Den's own:
+
+```markdown
+---
+name: planner # the id (or `id:`; default: the file name)
+description: Writes stories and their acceptance criteria. # or `role:`
+model: some-model # optional; `inherit` means none
+tools: Read, Grep # hints for the runtime; Den restricts nothing with them
+standing: true # starts with its workspace (later slices)
+context: [docs/specs, the design system] # what to read first
+runtime: generic # default den-claude
+permission_mode: plan # den-claude only; default `default`
+argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
+---
+
+You are the planner. …
+```
+
+Den ships a default pack: `planner` and `orchestrator` (standing), `fe-dev`,
+`be-dev`, `devops`, `reviewer` and `ux-designer`. Add your own packs, read in
+order after Den's; a persona with the same id replaces the earlier one:
+
+```yaml
+agents:
+  persona_packs: [personas, ../some-plugin] # relative to the distribution root
+```
+
+A pack is a directory of persona files. A pack with an `agents/` directory
+inside (a Claude Code plugin) is read from there, so a plugin's agents are
+used without converting them. Files without front matter (a README) are
+skipped; two files with one id in a pack, or a pack that isn't a directory,
+are errors naming the file or the key.
+
+### Runtimes
+
+`<cli> doctor` lists the runtime kind. Two are built in:
+
+- **`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 --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
+  persona's `permission_mode` sets one of `default`, `acceptEdits`, `plan` or
+  `bypassPermissions` (anything else is an error naming the key).
+  `bypassPermissions` prints a one-line warning at every start.
+- **`generic`** runs the persona's `argv` template. `{model}` is the agent's
+  model (an error when the template uses it and there is none);
+  `{mcp_config}` is the path of the agent's MCP config, written only when the
+  template references it. It declares no resume.
+
+### Workspace scope and grants
+
+An agent's MCP config, `<stateDir>/agent-files/<id>/mcp.json` (0600), runs
+`<cli> mcp --workspace <ws> --actor agent:<id>`: the agent sees and acts on
+its own workspace only, and every action is recorded as `agent:<id>` (see
+[Scoped to one workspace](#scoped-to-one-workspace)). A grant widens one
+agent's scope. It is config in git, reviewed like code; an agent can't give
+itself one:
+
+```yaml
+agents:
+  planner:
+    grants: [other-workspace]
+```
+
+`start` then adds `--grant other-workspace`, and each call into it is audited
+with both workspaces named. Any key of `agents:` other than `max_concurrent`
+and `persona_packs` is an agent id, and its only key is `grants`. A grant
+naming a workspace that doesn't exist stops `start`, naming the key.
+
 ## Pinning and upgrading
 
 `package.json` pins an exact Den version (`create` writes the version that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -62,6 +62,8 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "@playwright/test": "^1.61.1",
     "@slack/webhook": "^7.0.2",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "auth0": "^4.3.1",
@@ -111,5 +113,8 @@
   "homepage": "https://github.com/Monster-Orange/den",
   "bugs": {
     "url": "https://github.com/Monster-Orange/den/issues"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "1.1.0"
   }
 }