@monster-orange/den 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,190 @@ 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.0] - 2026-11-06
+
+0.4.0-dev.2 and later are built on 0.3.0 and include all of it (below).
+
+### Added
+
+- **`<cli> doctor --probe`** (0.4.0-dev.3, AG spec §5a-env; a consumer's
+  dogfood finding). Opt-in: it starts a short probe session through the
+  real session host for a plain session and for each available runtime's
+  agent env (built as `agents start` builds it, running a tiny node script
+  instead of the runtime's CLI). The probe prints key names and whether
+  each is credential-shaped, never values. It 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 unavailable, not failed. Plain
+  `doctor` still never spawns anything, and adds a note to run `<cli>
+  doctor --probe` when agents are configured (an `agents:` block or an
+  agent record).
+- **`sessions start --keep-env NAME`** (0.4.0-dev.3): one exact name per
+  flag, repeatable, no globs. The session host's log names each kept
+  variable and who asked, never its value, and marks a credential-shaped one
+  (it is still passed). Refused for an agent (`DEN_AGENT` set); `agents
+  start` has no `--keep-env`.
+- **Runtime contract: `envPassthrough` and `scrubEnv`** (0.4.0-dev.3). A
+  runtime names extra caller variables it needs (den-claude:
+  `CLAUDE_CONFIG_DIR`) and names it owns that must never reach a session
+  (exact, or a prefix ending in `*`; den-claude: `CLAUDECODE`,
+  `CLAUDE_CODE_*`). Every runtime's `scrubEnv` is removed from every
+  session's env last, whatever put it back. `LaunchOutput.warnings` are
+  printed at start.
+- **den-claude passes `--permission-mode`** (0.4.0-dev.3; a consumer's
+  dogfood finding): `default` unless the persona's `permission_mode` sets
+  `default`, `acceptEdits`, `plan` or `bypassPermissions` (anything else is
+  an error naming the key), so `approvals: "terminal"` means prompts reach
+  the terminal. `bypassPermissions` prints a one-line warning at start.
+- **`GET /api/activity?address=workspace:<ws>`** (0.4.0-dev.3; a consumer's
+  dogfood finding): an agent's cross-workspace call under a grant, which has
+  no repo or service, is listed under the workspace it reached and the
+  agent's own. Before, it showed only in the server log.
+- **Agents: personas, runtimes and the agent record** (0.4.0-dev.1, AG-2a).
+  `<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>]
+  [--id <id>]` resolves the persona and the runtime, asks the runtime for
+  argv, env and files, and starts the agent as session `<dist>-<ws>:<id>`
+  in the workspace's checkout dir (what `/api/workspaces` reports as its
+  `resolvedDirs`), capped by `agents.max_concurrent`. `agents stop <id>`
+  ends its session (TERM) and marks it stopped; `agents resume <id>`, only
+  when its runtime declares resume and its session is not running, starts a
+  new session in the same cwd continuing the last run. `agents personas
+  [--json]` lists the personas. `agents list -w <ws>` now shows each
+  agent's persona, runtime, model, state and cwd. Attach with `sessions
+  attach`.
+  - **The agent record**: `<stateDir>/agents/<id>.json` (0600, directory
+    0700): id, persona, runtime, model, workspace, cwd, session, start and
+    stop times, and the runtime's resume handle. Never the env or the argv.
+    An id is unique in a distribution: the default is the persona's id, or
+    `<persona>-<ws>` when another workspace has that one.
+  - **Personas** are markdown files with YAML front matter; the body is the
+    role prompt. The format is a Claude Code agent file read as it is
+    (`name`, `description`, `model`, `tools`; `model: inherit` means none),
+    with Den's own keys beside it: `id`, `role`, `runtime`, `standing`,
+    `context` and `argv`. A pack is a directory of them; a pack with an
+    `agents/` directory (a Claude Code plugin) is read from there. Den ships
+    a default pack: planner and orchestrator (standing), fe-dev, be-dev,
+    devops, reviewer and ux-designer, with short runtime-neutral prompts.
+  - **Runtimes** are strategy kind `runtime` (`<cli> doctor` lists it).
+    `den-claude` (default) finds `claude` on PATH and reads its version from
+    the install without running it; it launches `claude --session-id <id>
+    --mcp-config <file> --strict-mcp-config [--model <m>]
+    --append-system-prompt <role prompt>` and resumes with `--resume <id>`.
+    `generic` runs the persona's `argv` template, substituting `{model}`
+    and `{mcp_config}`; it declares no resume.
+  - **An agent's MCP is pinned to its workspace**: its MCP config
+    (`<stateDir>/agent-files/<id>/mcp.json`, 0600) runs `<cli> mcp
+    --workspace <ws> --actor agent:<id>`, plus `--grant <ws>` for each
+    workspace in `agents.<id>.grants`.
+- **`<cli> mcp --grant <ws>`** (0.4.0-dev.1, AG spec §5b; repeatable): a
+  scoped server also serves that workspace, only when the org config's
+  `agents.<id>.grants` lists it (a flag alone is refused, exit 2). A call
+  naming a granted workspace is reported before it runs, and the web
+  server's audit entry names both workspaces (`workspace` and
+  `targetWorkspace`). `workspaces` lists the scoped workspace and its
+  grants; tests run when the focused workspace is either. Logs and manifest
+  checks stay on the scoped workspace's own services.
+
+- **Sessions: terminals that outlive the web server** (0.4.0-dev.0,
+  AG-3a). `<cli> sessions start --workspace <ws> --name <n> [--cwd <dir>]
+  -- <argv…>` runs argv in a PTY named `<dist>-<ws>:<n>`; `sessions list
+  [-w <ws>] [--json]` lists them (`-w` shows that workspace's only);
+  `sessions attach <name|id>` is a raw terminal on one (output fans out to
+  every attachment, scrollback replays first, SIGWINCH resizes, ctrl-]
+  detaches and leaves it running); `sessions kill <name|id> [--signal
+  INT|TERM|KILL]` signals its process group (TERM by default) or, once it
+  has exited, removes it and its scrollback. A name is the full name,
+  `<ws>:<n>`, a bare `<n>` only one session has, or the id. Usage errors
+  exit 2.
+  - A **session host** owns every PTY: `<cli> sessions host`, one detached
+    process per distribution (its own session and process group), started
+    on demand by the first client and serving `<stateDir>/sessions.sock`
+    (mode 0600). Restarting the web server, or the CLI that started a
+    session, leaves it running. A second host finds the first and stands
+    down; a socket nobody answers on is stale and is replaced. `sessions
+    host --stop` stops it (its running sessions end). The host logs to
+    `<stateDir>/logs/<cli>/sessions-host.log`. Its protocol is versioned
+    (newline JSON, v1).
+  - **Scrollback** is a 2 MB ring per session, flushed to
+    `<stateDir>/sessions/<id>.log` (0600), so after a host restart a session
+    is listed as exited and attaching replays its history. A record holds
+    the name, cwd, pid, times and exit code, never argv or env.
+  - **`agents.max_concurrent`** (default 4) caps the sessions running at
+    once; a start past it is refused, naming the key. A value that is not a
+    whole number of at least 1 is an error naming the key.
+- **`<cli> agents list -w <ws> [--json]`** (0.4.0-dev.0): that workspace's
+  sessions as agents. Persona and runtime come from the agent record
+  (0.4.0-dev.1); a session started with `sessions start` has them blank.
+- **`<cli> doctor` lists the session backend** (0.4.0-dev.0): `den-pty`,
+  available when the PTY module loads, else why not. It is never a doctor
+  failure.
+
+### Changed
+
+- **A session's environment is an allowlist** (0.4.0-dev.3, AG spec
+  §5a-env; a consumer's dogfood finding). Every session started an agent
+  with the caller's whole environment, so an agent started from inside
+  Claude Code inherited `CLAUDECODE` and `CLAUDE_CODE_*` (Claude Code then
+  turned transcripts off, so resume could not work, and the agent could
+  message peers as its parent), and every secret in the caller's env reached
+  every agent. Now every session's env starts empty: `PATH`, `HOME`, `USER`,
+  `LOGNAME`, `SHELL`, `TERM` (default `xterm-256color`), `COLORTERM`,
+  `LANG`, `LC_*`, `TZ` and `TMPDIR`; then, for a plain session, the names
+  given with `--keep-env`; for an agent, its runtime's `envPassthrough`, its
+  launch env and `DEN_AGENT=agent:<id>`; then every runtime's `scrubEnv` is
+  removed. `sessions start` names the variables it left out, never values.
+  An agent's MCP server gets the distribution's location (`DEN_ROOT`,
+  `<PREFIX>_ROOT`, `<PREFIX>_HOME`, when set) in its own config. The
+  credential patterns test workers are scrubbed with now live in Den
+  (`src/shared/secret-env.ts`), and the tests import them.
+- **`agents resume` of a session that was never prompted starts fresh**
+  (0.4.0-dev.3; a consumer's dogfood finding): there is no conversation to
+  continue, so it starts under the same conversation id (`--session-id`, not
+  `--resume`) and says "starting fresh: it was never prompted, so there is
+  no conversation to resume". The session host records whether a session
+  ever got input with a line end (`prompted`), never the input.
+- **`agents start` and `resume` report an early exit** (0.4.0-dev.3; a
+  consumer's dogfood finding): Den watches the new session for up to 3 s;
+  a non-zero exit prints the code and the last lines it printed (at most
+  10, escapes stripped, secret-shaped values redacted) and exits 1. Before,
+  it printed "resumed agent …" and exited 0 while the agent's CLI had
+  exited 1.
+- **`agents list` shows agents only** (0.4.0-dev.3; a consumer's dogfood
+  finding): a session without an agent record (from `sessions start`) is
+  left out; `sessions list` shows it.
+- **`sessions attach` prints its banner first** (0.4.0-dev.3; a consumer's
+  dogfood finding): `[attached to …]`, then the scrollback replay.
+- **An MCP scope refusal names the agent's grants** (0.4.0-dev.3; a
+  consumer's dogfood finding): `(agent:<id>; grants: <a>, <b>)` or
+  `(agent:<id>; no grants)`.
+- **A PTY module is an optional dependency** (0.4.0-dev.0, Q-AG-1):
+  `@lydell/node-pty` 1.1.0, exact. Its binaries are prebuilt per platform
+  (macOS and Linux, x64 and arm64; Windows) in packages npm installs with
+  it, with no install script and nothing downloaded. Installed with
+  `--omit=optional`, or on another platform, Den runs as before and
+  `sessions start` says den-pty is unavailable and why.
+- **`agents list --json`** (0.4.0-dev.1): each row has `state` (running,
+  exited, stopped or ended) and, for an agent with a record, `persona`,
+  `runtime`, `model`, `workspace` and `cwd`; `session` is absent for a
+  record whose session is gone.
+
+### Migrations
+
+- **Plugins with a `den` range that ends below 0.4.0** (for example
+  `>=0.3.0-0 <0.4.0`) are skipped on 0.4.0, and `validate` fails them:
+  widen the range (for example `<1.0.0`). A plugin with no `den` range,
+  as Den's own themes, needs nothing.
+- `agents:` is a new, optional block of the org config. Any key other
+  than `max_concurrent` and `persona_packs` is an agent id; an invalid value
+  is an error naming the key:
+
+  ```yaml
+  agents:
+    max_concurrent: 4
+    persona_packs: [personas] # relative to the distribution root
+    planner:
+      grants: [other-workspace] # widens agent planner's MCP scope
+  ```
+
 ## [0.3.0] - 2026-11-06
 
 0.3.0-dev.31 and later include all of 0.2.7 (below).

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
@@ -1323,8 +1328,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 +1344,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 +1460,212 @@ 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.
+
+### 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>`.
+
+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`.
+
+**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
+(`~/.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 [--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.0",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -111,5 +111,8 @@
   "homepage": "https://github.com/Monster-Orange/den",
   "bugs": {
     "url": "https://github.com/Monster-Orange/den/issues"
+  },
+  "optionalDependencies": {
+    "@lydell/node-pty": "1.1.0"
   }
 }

package/src/shared/agents/default-pack/be-dev.md

@@ -0,0 +1,20 @@
+---
+name: be-dev
+description: Implements back-end stories, test first, keeping contracts stable.
+context:
+  [
+    the story and its acceptance criteria,
+    the service's API contracts,
+    the repo's conventions,
+  ]
+---
+
+You are a back-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Keep public contracts backward compatible unless the story says otherwise;
+  call out any migration.
+- Validate input at the boundary, handle errors explicitly, and never log
+  secrets.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/devops.md

@@ -0,0 +1,14 @@
+---
+name: devops
+description: Builds and maintains pipelines, environments and service configuration.
+context: [the story, the workspace's service manifests, CI configuration]
+---
+
+You are a devops engineer. Make services easy to build, run and ship.
+
+- Prefer declarative configuration and small, reversible changes.
+- Keep secrets in the configured secret store; never write a value into a
+  file, a log or a pull request.
+- Prove each change locally (bring the service up, check its health) before
+  proposing it.
+- Explain the operational impact and the rollback in the pull request.

package/src/shared/agents/default-pack/fe-dev.md

@@ -0,0 +1,20 @@
+---
+name: fe-dev
+description: Implements front-end stories, test first, to the design system.
+context:
+  [
+    the story and its acceptance criteria,
+    the design system,
+    the front-end conventions of the repo,
+  ]
+---
+
+You are a front-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Use the design system's components and tokens; do not invent new ones
+  without the ux-designer.
+- Keep the change small and focused on the story. Check accessibility and
+  narrow screens.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/orchestrator.md

@@ -0,0 +1,16 @@
+---
+name: orchestrator
+description: Takes the next ready story, picks the persona for it and starts that agent.
+standing: true
+context: [ready work items, running agents in the workspace]
+---
+
+You are the orchestrator. Keep work flowing without overloading the machine
+or the people reviewing it.
+
+- Take the next ready story, in priority order. Pick the persona that fits it:
+  fe-dev, be-dev or devops for implementation, ux-designer for design work.
+- Start one agent per story, in its own worktree, and link it to the story.
+- Respect the workspace's concurrency cap; wait rather than queueing more.
+- When a pull request is opened, ask the reviewer for a review. Never approve
+  or merge anything yourself.

package/src/shared/agents/default-pack/planner.md

@@ -0,0 +1,17 @@
+---
+name: planner
+description: Writes stories and their acceptance criteria for the workspace.
+standing: true
+context: [the workspace's specs and docs, open work items, the design system]
+---
+
+You are the planner. Turn goals and requests into small, independently
+shippable stories, each with a clear user outcome and testable acceptance
+criteria.
+
+- Read the existing specs and work items before writing a new story; extend
+  them rather than duplicating them.
+- Keep each story to one vertical slice that can be reviewed on its own.
+- Suggest an architecture or design record (ARD, ADR or LLD) only when a story
+  changes a contract, a data model or a boundary between components.
+- Hand each ready story to the orchestrator. You do not write code.

package/src/shared/agents/default-pack/reviewer.md

@@ -0,0 +1,14 @@
+---
+name: reviewer
+description: Reviews a pull request adversarially. Never approves or merges.
+context: [the pull request and its story, the repo's conventions and tests]
+---
+
+You are the reviewer. Try to prove the change wrong before anyone relies on it.
+
+- Check it against the story's acceptance criteria, then look for what the
+  author did not test: edge cases, failure paths, security, performance.
+- Verify each finding by reading the code; drop anything you cannot show.
+- Report findings ranked by impact, each with a concrete scenario and a
+  suggested fix.
+- You never approve, merge or push. A person decides.

package/src/shared/agents/default-pack/ux-designer.md

@@ -0,0 +1,15 @@
+---
+name: ux-designer
+description: Designs flows and screens with the design system, on request.
+context: [the story, the design system, existing screens of the product]
+---
+
+You are the UX designer. Make the next step obvious for the person using the
+product.
+
+- Start from the user's goal and the story's acceptance criteria.
+- Compose from the design system's components; propose a new component only
+  when none fits, and say why.
+- Describe states (empty, loading, error, success) and narrow screens, not only
+  the happy path.
+- Hand off a short spec the developers can implement and test.