@monster-orange/den 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,599 @@ 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.1] - 2026-11-06
+
+### Added
+
+- **The Agents tab** (0.4.1-dev.5, AG-4a-term, AG spec §5d): "Agents" in
+  the rail under Develop, after Graph, at `/agents`. The list holds every
+  session and agent of the workspaces in view (the scope bar, or `?ws=`),
+  grouped by workspace: state, persona and runtime, and a waiting badge
+  (shown once the host can tell, AG-6a);
+  a plain session (`sessions start`) is labelled "session", an agent whose
+  token `web logout --all` revoked says "token revoked". Click a row to
+  open its terminal (xterm.js, served from Den's own node_modules: no CDN):
+  the scrollback, then the live output, and your keys go to the session.
+  Up to four panes tile (a fifth closes the oldest), and the URL holds them
+  (`/agents?open=<id>,<id>`), so a reload or Back reattaches each with its
+  scrollback. A pane's bar has its name, workspace and runtime, Stop (an
+  agent, behind the lock) and Close, which detaches: the session keeps
+  running, as it does when you leave the page. "+ Start agent" (or
+  `/agents?start=1`) asks for the workspace under All, starts it and opens
+  its pane. ⌘K offers "Agents › <ws> / <name>" for each and "Start agent…".
+  The Workspaces page's Agents section links to it ("Open in Agents →",
+  and Open on a row with a session). In English, Japanese and Spanish;
+  light and dark; one column on a phone. Without the optional PTY module
+  the list says terminals need it, and nothing else changes.
+- **`GET /api/sessions` and the `/api/sessions/<id>/io` WebSocket**
+  (0.4.1-dev.5). The list: the sessions and agents of the active
+  workspaces, this distribution's only (asking never starts a session
+  host). The io socket is the session host's attach: binary frames carry
+  output and input, a text frame `{"type":"resize","cols":c,"rows":r}`
+  resizes, and the server says `{"type":"session",…}` first and
+  `{"type":"exit","exitCode":n}` at the end. Closing it detaches and never
+  signals the session; several browsers and the CLI can attach at once
+  (the size is the last one's). It is shell-grade: this server's Host, the
+  page's Origin, the CSRF token as the `den.csrf.<token>` subprotocol (a
+  browser's WebSocket can't send a header), a sign-in beyond loopback, and
+  an agent token reaches its own session's io only. Every attach and
+  detach is in the audit trail, with the actor from the credential. A
+  plain GET of it is 426.
+
+- **`web logout --all` revokes every agent's token** (0.4.1-dev.4, SEC-1
+  §6c.2): it is the "something leaked" button, so it ends everything. A
+  running agent's next call gets 401 `token_revoked`: "This agent's token
+  was revoked (`web logout --all`): restart or resume the agent to get a
+  new one." (its stdio MCP server refuses to start with one). The output
+  says how many it revoked. Plain `web logout` (one browser, or every
+  browser) leaves agent tokens alone.
+- **den-claude denies Den's state dir to the agent** (0.4.1-dev.4, SEC-1
+  §6c.1): `--settings <file>` (0600) with `permissions.deny` for `Read` and
+  `Bash` of `<state>/web.secret` and `<state>/sessions/**`. It binds
+  cooperating agents only: an agent runs as the same OS user, and the
+  server's token rules are the boundary.
+- **`setup`, `up`, `down` and `restart` across active workspaces**
+  (0.4.1-dev.4). `-w <workspace>` names the workspace (`setup` takes one
+  now; several still go with `--plan`). With no `-w`, a named service
+  resolves in the focus first, then across the other active workspaces, as
+  the web API's `&workspace=` does: in exactly one, it runs there (the CLI
+  says which); in several, an error lists them with the `-w` command for
+  each; in none, or names in different workspaces, an error. Each exits 1
+  and runs nothing. Before, a service in an active workspace that wasn't
+  the focus made `setup` print nothing and exit 0, `restart` say "not
+  found" and `up` say "no derived dependencies".
+
+- **Agent actor tokens** (0.4.1-dev.3, SEC-1c, SEC-1 spec §1, §5, §7).
+  - **`agents start`** (the CLI and `POST /api/workspaces/<ws>/agents`)
+    mints a random `den_at_…` token for the agent and hands it to the
+    session as `DEN_ACTOR_TOKEN`, through the §5a-env allowlist's Den
+    markers (a caller's, a runtime's or a `--keep-env` value of it is
+    dropped). Only its sha256 is stored, in `actor-tokens.json` (0600) in
+    the state dir, with the agent, its workspace, its grants and its
+    session. One live token per agent: **resume** mints a fresh one and the
+    old one stops working; **stop** revokes it, and so does the session's
+    end (an exit or a crash), checked when the token is presented.
+  - **The scrub always strips a person's credential** from every session's
+    env, whatever put it there: `DEN_PERSON_TOKEN`, any value carrying a
+    person token, a path to `web.secret`. **`sessions start --keep-env`**
+    of one (or of `DEN_ACTOR_TOKEN`) is refused, exit 1, and the session
+    host's log records the refusal and who asked (the name, never a value).
+  - **The server accepts the agent's bearer.** The CLI inside an agent
+    sends its `DEN_ACTOR_TOKEN`, never the person token (an agent without
+    one sends none). The audit actor comes from the credential: an entry
+    reads `actor: "agent"` only for a verified agent token. Agent headers
+    (`X-Den-Agent`, …) next to another credential, or alone, are recorded
+    as `claimed` with `unverified: true`, and the Activity panel shows
+    them as "(unverified)".
+  - **What an agent token can't do**: open another session's routes
+    (`/api/sessions/<id>/…`: only its own session; the routes themselves
+    come with the terminal), any other shell-grade route (start, resume,
+    the session admin routes, so it mints no tokens), `/api/web/*`,
+    `/auth`, `/signin`, sign out or rotate; and it never passes the lock
+    (R8): no unlock, no sudo password, no prewarmed sudo, and the lock reads
+    closed to it. Each answers 403 `agent_forbidden`. A workspace check
+    (WS-3a) has its seam in the request guard, allowing everything for now.
+  - **The stdio MCP server Den starts for an agent** carries that agent's
+    token: its calls are audited as the agent, and `--actor` /
+    `--workspace` that don't match the token's record refuse to start.
+- **Signing in the browser** (0.4.1-dev.2, SEC-1b, SEC-1 spec §2, §4). No
+  password: reading `web.secret` proves you are this computer's user, and
+  the CLI does it.
+  - **`<cli> web open`** starts the server if needed and opens a fresh tab
+    on a sign-in link; **`<cli> web up`** opens one too when it doesn't find
+    an existing tab. **`<cli> web login [--next <path>] [--origin <url>]`**
+    prints a fresh link, for another browser.
+    The link is `http://localhost:<port>/auth?c=<code>&next=<path>`: the
+    code works once, within 60 seconds, and is an HMAC of a random nonce
+    and its expiry under `web.secret` (the server records the nonce as
+    used). It is printed only on that one line and never logged. `next`
+    must be a same-origin path (`//evil`, `http://evil`, `/\evil` go to
+    `/`).
+  - **`GET /auth?c=…`** swaps the code for a session and answers 303 to
+    `next`. A bad, expired or used code gets the signed-out page: "That
+    sign-in link expired or was used. Run `<cli> web login` for a new one."
+  - **The cookie** `den_session_<port>` (an opaque random id; per port, so
+    two distributions on one machine keep their own): HttpOnly,
+    SameSite=Strict, Path=/, and Secure when the request came over HTTPS
+    (the edge's `X-Forwarded-Proto` counts only on the edge hostname from
+    a loopback or Docker peer). The record is server-side, in
+    `web-sessions.json` (0600) in the state dir, keyed by an HMAC of the id
+    under the secret: created, last seen, the user agent (truncated), the
+    host it was issued on and its own CSRF token. It never expires
+    (0.4.1-dev.4, above).
+  - **`GET /api/session`** answers `{ csrf, actor: "person-browser",
+    signedIn: true }` for a signed-in browser, with the session's own CSRF
+    token (a signed-in browser's mutations must carry that one). Signed out
+    on loopback it answers as before.
+  - **The route classes (§4).** On loopback no route needs a sign-in
+    (0.4.1-dev.4): read-only is open; mutating and **shell-grade** (an
+    agent's start and resume, the session admin routes, later the terminal)
+    need Origin and CSRF (as in SEC-1a), or the person's bearer (the CLI and
+    MCP need no setup). Beyond loopback (the edge hostname, a LAN name, or
+    a peer that isn't loopback): every route needs a session or a bearer,
+    so a LAN or edge Host is usable again once signed in. Only `/auth`,
+    `/signin`, `/api/session` and the UI's static files need none.
+  - **The signed-out page** (beyond loopback), in the shell frame: "Sign in
+    to use <name>", "Run `<cli> web login` and open the link." with a copy
+    button (through the edge the command names its origin), and on
+    `127.0.0.1` or `[::1]` a link to the same page on `localhost`, where the
+    cookie is. It never offers a form for a secret or a token. `/api`
+    answers 401 `signin_required` (R26's shape). In en, ja and es.
+  - **localhost is canonical**: the links Den prints use it, and following
+    the signed-out page's link from 127.0.0.1 lands signed in.
+  - **`<cli> web sessions [--json]`** lists the signed-in browsers (id
+    prefix, created, last seen, host, user agent); **`<cli> web logout
+    [<id prefix>]`** signs out one, or every browser; **`--all`** also
+    rotates `web.secret`, which ends every session and every person token
+    (the CLI re-reads it and keeps working), and (0.4.1-dev.4) revokes every
+    agent's token. They ask the running server
+    with the person token, or edit the state files when it isn't running.
+  - **Settings → Command line → Browser sign-in** says whether this
+    browser is signed in, with **Sign out** (`POST /api/session/logout`).
+  - **A non-loopback bind refuses to start** (`DEN_BIND_HOST=0.0.0.0` or a
+    LAN address) without HTTPS in front (the edge, with `edge.tls`), unless
+    `web.allow_plain_http_remote: true` is in `config/local/user.yml`: the
+    error says a session cookie would cross the network in clear text.
+    With it, the machine's own addresses and host name are accepted with
+    the port.
+- **Request checks on every request** (0.4.1-dev.1, SEC-1a, SEC-1 spec §3).
+  Hardening for everyone; no sign-in yet (that is SEC-1b).
+  - **Host allowlist** (DNS rebinding): `localhost`, `127.0.0.1` and
+    `[::1]` with the server's port, plus the edge hostnames that route to
+    Den. Anything else answers 421 `misdirected` (R26's JSON for `/api`, the
+    shell-frame error page for a page, which links to the same path on
+    `localhost`). The product's own name is accepted when `/etc/hosts` maps
+    it to 127.0.0.1 (the URL `web up` opens then), and so is a specific
+    address `DEN_BIND_HOST` binds.
+  - **Origin** on POST, PUT, PATCH, DELETE and every WebSocket upgrade: an
+    allowed host, http or https. A missing Origin needs a valid
+    `Authorization`. Otherwise 403 `origin_rejected`.
+  - **CSRF**: the shell sends `X-Den-CSRF` on every same-origin mutation,
+    through `denShell.api()` or a page's own `fetch()`, with the token the
+    new `GET /api/session` hands out (`{ csrf, actor }`, same-origin callers
+    only). The token is per server start; after a restart the shell fetches
+    a fresh one and retries once. A browser mutation without it answers 403
+    `csrf`.
+  - **GETs that run something** (they stream over GET, for EventSource):
+    `/api/service/exec`, `/api/run`, `/api/workspace/exec`,
+    `/api/workspace/sync` and `/api/aws/login`. They answer this server's
+    own pages only (`Sec-Fetch-Site: same-origin`, or `none` for a typed
+    URL), or a caller with neither header and a valid bearer (the CLI,
+    MCP, curl). Another site's `<img src>` or no-cors fetch answers 403
+    `cross_site` (or `origin_rejected`), and nothing runs.
+  - **One route table** (`route-classes.ts`): every route the server
+    dispatches is `readonly`, `mutating` or `shell-grade` (§4), by method
+    and path; the checks read it, and SEC-1b will too. A test scans the
+    dispatchers and fails on a route the table doesn't classify.
+  - Other GETs, pages and SSE streams are unchanged on loopback (§6).
+- **`web.secret` and the CLI's person token** (SEC-1a, §5). The server
+  creates `web.secret` (32 random bytes, mode 0600) in the state dir at
+  start. The CLI and the stdio MCP server send `Authorization: Bearer
+  den_pt_…`, derived from it, on every call: nothing to set up. The server
+  verifies it in constant time; an invalid bearer answers 401
+  `unauthorized`. The audit entry of a call made with it gains `principal:
+  "person:<os user>"`, from the credential, never from a header.
+  `<cli> web token --print` prints it for curl (stdout only, with a
+  one-line note on stderr that it grants your access).
+- **Agents on the Workspaces page** (0.4.1-dev.0, AG-4a, AG spec §5c).
+  Under the selected workspace's repo table, one row per agent: id and
+  persona, runtime, state (`running`, `stopping`, `stopped`, `ended`,
+  `exited (<code>)`), directory and when its session started. **Stop**, and
+  **Resume** where the record allows it (the runtime declares resume and the
+  agent isn't running). **+ Start agent** picks a persona and a runtime. The
+  workspace header counts them ("n agents"). In en, ja and es.
+  - Routes: `GET /api/workspaces/<ws>/agents`, `POST
+    /api/workspaces/<ws>/agents` (start), `POST
+    /api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, `GET
+    /api/personas`. They call the CLI's own operations (the new
+    `agent-ops.ts`, which `<cli> agents` is now a front for): neither keeps
+    state of its own, and a workspace lists its own agents only.
+  - Guards: the lock (R8) gates Start, Stop and Resume (423 `locked`;
+    the page opens the lock first, as for a service action),
+    `agents.max_concurrent` caps starts (429 `cap`), and an agent actor is
+    refused (403). Errors are R26's shape and reach the page as error
+    toasts. The agent's env is the CLI's allowlist (§5a-env), and every
+    action is audited with the person as its actor.
+  - Listing never starts a session host: with none running, every agent
+    reads `ended`.
+  - No terminal and no Open in dev.0 to dev.4: dev.5 adds them (the Agents
+    tab, above).
+
+### Changed
+
+- **No browser sign-in on loopback, for any route** (0.4.1-dev.4; Ward,
+  2026-11-06; SEC-1 Q-SEC-1). On localhost the agents (start, resume), the
+  browser-session routes, `/signin` and, later, the terminal need only what
+  any change needs: this server's Host, the page's Origin and its CSRF
+  token. The lock (R8) stays the only prompt. A sign-in is still required
+  for every route when the server is reached beyond loopback: the edge
+  hostname, a LAN name or address, or a peer that isn't loopback (a
+  `DEN_BIND_HOST` bind). The Host allowlist, the Origin check,
+  `X-Den-CSRF`, `web.secret`, the person token and agent tokens (and what
+  an agent token can't do) are unchanged.
+- **A browser session never expires** (0.4.1-dev.4; SEC-1 Q-SEC-2): it ends
+  at sign-out, `web logout` or `web logout --all`. The cookie asks to be
+  kept 400 days, a browser's most. `web.session.idle` and
+  `web.session.max` are gone: if either is still in a config file the
+  server logs that it is ignored, naming the key and the file, and starts.
+- **Health covers every active workspace, whatever is in view**
+  (0.4.1-dev.4, WS-6.4). `/api/health` and its stream check every active
+  workspace's services; each row carries `inView` (one of its workspaces is
+  in the view scope). The top bar's chip and drawer count only the rows in
+  view; the pages get every row, so the Workspaces page shows a workspace's
+  real health when it is outside the view (it read "unknown (not
+  checked)").
+- **The stdio MCP server's startup line says `unverified`** (0.4.1-dev.4,
+  SEC-1 §6c.3) when no `DEN_ACTOR_TOKEN` verified its `--actor`: "scoped
+  to north as agent:planner (unverified: no DEN_ACTOR_TOKEN)".
+- **`/signin` is read-only** (0.4.1-dev.3). Signed in, or on loopback, it
+  answers 303 to its (same-origin) `next`; signed out beyond loopback, the
+  signed-out page. It was shell-grade, so the route's own check never ran
+  beyond loopback.
+- **`web up` and `web restart` print the server's refusal** (0.4.1-dev.3):
+  when the server exits at start (a non-loopback bind without HTTPS, a
+  wrong `web.allow_plain_http_remote` value) the CLI prints "<name> web refused to start:
+  <the reason line>" and then where the log is, instead of waiting out
+  "did not become ready". Secrets in the line are redacted.
+- **`web sessions --help`** says that LAST SEEN is written at most once a
+  minute, so it equals CREATED right after a sign-in, and that a session
+  never expires.
+- **`agents list` shows `stopping`** for an agent that was stopped while its
+  session is still on its way out (it was `running`), and its `--json` rows
+  gain `startedAt` and `resumable`.
+
+### Fixed
+
+- **A non-loopback bind needs `web.allow_plain_http_remote`, edge or no
+  edge** (0.4.1-dev.5, a dev.4 dogfood finding). With the edge configured,
+  `DEN_BIND_HOST=0.0.0.0` started, but the server's own port still answered
+  plain HTTP on every interface. It is refused now unless
+  `web.allow_plain_http_remote: true` is in `config/local/user.yml`; the
+  one exception is the Docker bridge address (`172.16.0.0/12`, as
+  `DEN_BIND_HOST=172.17.0.1`) with the edge configured, for an edge that
+  reaches the host there (Linux). The edge on macOS reaches Den on
+  loopback and needs neither.
+- **The edge hostname is believed only from the edge** (0.4.1-dev.5): a
+  request whose `Host` is the edge hostname from a peer the edge can't be
+  (not loopback, the Docker bridge or Docker Desktop's network) is 421
+  `misdirected`. A LAN client could send the edge's name straight to a
+  non-loopback bind and be treated as coming through the edge.
+- **`web.allow_plain_http_remote` in the distribution config is said to be
+  ignored** (0.4.1-dev.5): it is read only from `config/local/user.yml` (a
+  choice for one machine); the server logs a warning naming the file it
+  found it in, and the refusal names the file to set it in.
+- **den-claude's Bash denies match** (0.4.1-dev.5): Claude Code 2.1.x asked
+  for approval of `cat <state>/web.secret` instead of denying it; the
+  legacy `Bash(cat <path>:*)` shape didn't match. The rules are Claude
+  Code's wildcard form now (`Bash(*<path>*)`, and `cat`, `head`, `tail`,
+  `less`, `more`, `xxd`, `od`, `strings`, `base64` and `cp` of it), with
+  the path under `~` and `$HOME` too, and a path with spaces escaped. The
+  `Read` rules are unchanged.
+- **`restart <repo>/<svc>` of a single-service repo restarts it** after
+  `up <repo>` (0.4.1-dev.5, a dev.4 dogfood finding). The record was kept
+  under `<repo>`, so the restart found none, adopted the running process
+  and printed ✔ without restarting anything, leaving two records on one
+  process group. For a repo with one service, `<repo>` and `<repo>/<svc>`
+  are one daemon now; a duplicate left by dev.4 is merged at the next
+  command; and a restart that adopts a process restarts it.
+- **`up`, `down`, `restart` and `setup --help` mention `-w <workspace>`**
+  (0.4.1-dev.5).
+- **A subcommand's `--help` is its own** (0.4.1-dev.4): `web sessions`,
+  `web login`, `web logout` and `web token --help` (or `-h`) printed the
+  general web help, and `mcp connect|disconnect|clients|config --help`
+  printed `mcp`'s, because the dispatcher answered `<command> --help`
+  first. `web login`, `web logout` and `web token` have a help of their own
+  now (`web token --help` exited 2).
+- **A relative `product.state_dir` is relative to den.yml's directory**
+  (0.4.1-dev.4), the distribution root. It was resolved against the cwd, so
+  an agent's CLI or MCP server started in its workspace's directory read
+  and wrote another state dir (another `web.secret`, other tokens).
+- **Den's test servers are all tracked** (0.4.1-dev.4): every suite and
+  helper that starts a web or MCP server starts it in a process group of
+  its own and stops the group (tests/child-servers.ts), so none outlives a
+  run.
+- **A command name that isn't declared never runs** (0.4.1-dev.3, SEC-1
+  §6b.2). `/api/service/exec?cmd=constructor` (or `toString`, any name an
+  object inherits) ran `undefined` as a shell command; the service and
+  workspace command lookups now read the declared commands only. `/api/run`
+  refuses a `module` that isn't a module name (a `..` segment, a slash at
+  the start), 400.
+- **A web server whose output's reader is gone no longer spins**
+  (0.4.1-dev.3). When the terminal, script or test runner that started the
+  server was killed, the next log line failed with EPIPE and the "continue"
+  guard for uncaught errors logged that to the equally closed stderr, which
+  failed again: a loop at a full core that stopped the server answering,
+  for as long as the orphan lived. The server now writes nothing once its
+  output is gone, and shuts down (as for SIGTERM: services it started stay
+  up). A server `<cli> web up` starts logs to a file and is not affected.
+- **The server's exit is bounded** (0.4.1-dev.3). A SIGTERM or SIGINT with
+  no prompt waiting on the person forces the exit after 10 s
+  (`DEN_SHUTDOWN_DEADLINE_MS`) if the shutdown hasn't finished, and a
+  second signal exits at once (it was ignored, so a stuck shutdown left the
+  server deaf to every later SIGTERM).
+- **Den's own test servers never outlive a test run** (0.4.1-dev.3): they
+  start in a process group of their own, a test stops the whole group, and
+  the run's global teardown (or the next run's setup) stops any group a
+  killed or timed-out test left behind.
+- **The Release page with no deploy environment** (`environments: [local]`
+  only) no longer asks `/api/release/status?env=undefined` (a 400 on every
+  load); it says no deploy environment is configured.
+- **An agent's persona shows on every row** (0.4.1-dev.1), an id that is
+  its persona too ("planner persona planner").
+- **The unlock popover names agents** (0.4.1-dev.1): "Unlock to start, stop
+  and restart services and agents", in en, ja and es.
+- **Another workspace's agent is a 404 before the lock** (0.4.1-dev.1):
+  Stop or Resume of an agent id that belongs to another workspace answers
+  "no agent here" even while the lock is closed (it answered 423), and
+  still never names the other workspace.
+- **The 421 page and the signed-out page start no polls** (0.4.1-dev.2, a
+  consumer's SEC-1a dogfood). Every `/api` call from them would answer the
+  same refusal, so the server marks them and the shell, as for an invalid
+  config, starts none of its polls and streams (health, the lock, the env
+  list, themes, the changelog, the stale-server check); the status chip
+  reads "Status unknown" instead of "Checking…" forever.
+- **No config polls under an invalid config.** The server marks every page
+  it serves while the config fails validation, and the shell also learns it
+  from the first `422 config_invalid` answer. From then on it starts none of
+  the polls and streams that read the config (health and its stream, edge,
+  workspaces, applications, the org config, the sudo vault status, Logs'
+  services, Settings' workspace settings), so the browser console no longer
+  logs a "Failed to load resource … 422" line for each of them. A reload
+  once the config is fixed starts them again.
+
+### Migrations
+
+- **Scripts that POST to `/api` with curl** need `Authorization: Bearer
+  $(<cli> web token --print)` or an `Origin` (SEC-1a), and so do curl GETs
+  of the routes that run something (`/api/service/exec`, `/api/run`,
+  `/api/workspace/exec`, `/api/workspace/sync`, `/api/aws/login`). Other
+  GETs work unchanged.
+- **A Host other than `localhost`, `127.0.0.1`, `[::1]` or Den's edge
+  hostname** answers 421 (SEC-1a). A server exposed with
+  `DEN_BIND_HOST=0.0.0.0` goes through the edge, or sets
+  `web.allow_plain_http_remote: true` in `config/local/user.yml`: then the
+  machine's own addresses and host name work again, signed in (SEC-1b).
+  Without either, a non-loopback bind now refuses to start, saying why.
+- **SEC-1: nothing asks for a sign-in on localhost.** Pages, read-only
+  calls, the shell's changes, agents and (later) the terminal work as
+  before; the lock (R8) is the only prompt. A sign-in is needed only when
+  the server is reached beyond loopback (below).
+- **`web.session.idle` and `web.session.max` are ignored** (a session never
+  expires). Remove them; until then the server logs a warning naming each,
+  and starts.
+- **Supported browsers for signing in**: Chromium, Firefox and Safari 16.4
+  or later. A browser that sends neither `Sec-Fetch-Site` nor `Origin`
+  (Safari before 16.4) can't sign in (it can still use localhost, where no
+  sign-in is asked).
+- **Edge-fronted or remote users** see the signed-out page once; `<cli> web
+  login --origin <the edge's URL>` (the page shows the exact command) signs
+  that browser in.
+- **Scripts that call `/api` with curl from loopback**: GETs work
+  unchanged; mutations need `Authorization: Bearer $(<cli> web token
+  --print)` or an `Origin`. Through the edge every call needs the bearer.
+- **The GETs that run a service's, a workspace's or a test's command**
+  (`/api/service/exec`, `/api/run`, `/api/workspace/exec`,
+  `/api/workspace/sync`, `/api/aws/login`) are classed `mutating`, as §4
+  lists up, down and restart, not `shell-grade`: they need no sign-in on
+  loopback, and keep SEC-1a's same-origin-or-bearer check.
+- **Audit entries (SEC-1c).** `actor: "agent"` now means a verified agent
+  token. Agent headers without one (an MCP server started with `--actor`
+  but no token, a script that sets `X-Den-Agent`) record the person (or
+  `user`) as the actor, with the headers under `claimed` and `unverified:
+  true`. A reader that filtered on `actor: "agent"` and the headers should
+  read `claimed` for those.
+- **An agent's MCP server** is audited as the agent only when it inherits
+  the agent's `DEN_ACTOR_TOKEN` from the session (Den starts it so); a
+  hand-written MCP entry with `--actor agent:<id>` and no token is now a
+  claim.
+- **`sessions start --keep-env DEN_PERSON_TOKEN`** (or of a variable that
+  holds a person token or a path to `web.secret`) is refused; it was
+  passed with a warning.
+
+## [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).