@monster-orange/den 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.2] - 2026-11-06
+
+The 0.4.1 carry-overs.
+
+### Added
+
+- **`sessions.max_concurrent`** (default 8): the cap on plain sessions
+  (`sessions start`) running at once. Past it, `sessions start` is refused
+  as the agents' cap is: "2 sessions are running and
+  sessions.max_concurrent is 2", then "Stop one first (`<cli> sessions
+  kill <name>`), or raise sessions.max_concurrent." `<cli> validate` names
+  a wrong value of it or of `agents.max_concurrent`.
+
+### Changed
+
+- **`agents.max_concurrent` counts agents only.** Plain sessions count
+  against `sessions.max_concurrent` instead, so a few plain shells never
+  stop an agent from starting (from the CLI, the Workspaces page, the
+  Agents tab or MCP). Its refusal says "1 agent is running and
+  agents.max_concurrent is 1".
+- **The Agents tab's pane title and Close** name the agent by its id
+  (its display name once AG-10 adds one), never its persona; the list row
+  still shows the persona, with the id beside it.
+- **den-claude's deny list, in the docs**: it is a convenience, not the
+  boundary. It binds cooperating agents only and does not catch every
+  spelling (a path relative to the agent's cwd, another program); the
+  server's token rules are the boundary.
+
+### Fixed
+
+- **A distribution config's `web.allow_plain_http_remote`** (ignored: it is
+  read only from `config/local/user.yml`) was warned about only in the
+  in-app server log. It is now in `web.log` too (before a bind refusal it
+  often explains), in the `web up` and `web restart` output, and in
+  `<cli> validate`.
+- **`up --help`**: `-w, --workspace <ws>` ran into its text ("<ws>act in
+  that…"); there are two spaces now. `down`, `restart` and `setup --help`
+  were already spaced.
+
+### Migrations
+
+- **More than 4 plain sessions at once**, or a script that relied on
+  `agents.max_concurrent` to cap plain sessions: set
+  `sessions.max_concurrent` (default 8). `agents.max_concurrent` no longer
+  counts them. A session host already running from 0.4.1 keeps counting
+  every session until it restarts (`sessions host --stop`, which ends its
+  sessions, or a reboot).
+
 ## [0.4.1] - 2026-11-06
 
 ### Added

package/README.md

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

package/docs/distributions.md

@@ -1581,9 +1581,16 @@ the profile's `state_dir` (`~/.<name>`), or `<PREFIX>_HOME`.
 - Stopping the host (`sessions host --stop`, or a reboot) ends its
   sessions. They stay listed as exited, with their scrollback, until
   `sessions kill` removes them.
-- `agents.max_concurrent` caps the sessions running at once (default 4):
+- `sessions.max_concurrent` caps the plain sessions (`sessions start`)
+  running at once (default 8), and `agents.max_concurrent` the agents
+  (default 4). Each counts only its own, so a few plain shells never stop
+  an agent from starting, nor agents a shell. Past either, the start is
+  refused, naming the key ("2 sessions are running and
+  sessions.max_concurrent is 2"); `<cli> validate` names a wrong value.
 
   ```yaml
+  sessions:
+    max_concurrent: 8
   agents:
     max_concurrent: 4
   ```
@@ -1614,7 +1621,7 @@ server scoped to its workspace.
 
 - `start` runs the agent as session `<dist>-<ws>:<id>` in the workspace's
   checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
-  `agents.max_concurrent`. The id defaults to the persona's id; an id is
+  `agents.max_concurrent` (agents only: plain sessions never count). The id defaults to the persona's id; an id is
   unique in the distribution, so a second workspace's planner gets
   `planner-<ws>` unless you give `--id`.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
@@ -1761,19 +1768,22 @@ 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).
+**The deny list is a convenience, not the boundary.** den-claude passes
+Claude Code a settings file (`--settings`) whose `permissions.deny` lists
+`Read` of `<state dir>/web.secret` and `<state dir>/sessions/**`, and
+`Bash` rules in Claude Code's wildcard form for the path
+(`Bash(*<state dir>/web.secret*)`, and each of `cat`, `head`, `tail`,
+`less`, `more`, `xxd`, `od`, `strings`, `base64` and `cp` followed by it),
+spelled as an absolute path, under `~` and under `$HOME`, with a path that
+has spaces also backslash-escaped. It binds cooperating agents only: an
+agent that ignores its permission config can read the files anyway. And
+it does not catch every spelling: a path relative to the agent's cwd
+(`cat ../.den/web.secret`, say), another program, a script or a copy under
+another name all get past it. The server's token rules (above)
+are the boundary: whatever an agent reads, its token reaches only its own
+session's routes, never a shell-grade route or the lock. OS-user isolation
+(a separate user, a container, a sandbox) is not in 0.4.x. `web logout
+--all` revokes every agent's token (above, under Signing in).
 
 **What the scope does not do.** An agent's MCP scope binds cooperating
 agents only. A runtime with a shell can still run `<cli>` itself, outside

package/docs/reference.md

@@ -0,0 +1,177 @@
+# Den reference
+
+The technical reference that used to be the README. It will be split into separate pages (configuration, CLI, manifests, edge, secrets, tests, MCP) as part of DOC-2.
+
+## Make it your own
+
+1. **Create** a distribution named after your product:
+
+   ```sh
+   npx @monster-orange/den create acme      # → ./acme
+   cd acme && npm install
+   ```
+
+2. **Name** it: `den.yml` holds `product: { name: acme }`, so the CLI is
+   `./bin/acme`, env vars are `ACME_*`, state lives in `~/.acme`. Pass
+   `--cli`, `--env-prefix` or `--title` to `create`, or edit `den.yml`.
+3. **Brand** it: `brand:` in `config/acme.yml` sets the name, tagline and
+   banner people see in the CLI and web UI.
+4. **Point it at your repos**: set `github_org` in `config/acme.yml`, then
+   `./bin/acme register ../shop-api` (or add a manifest per repo under
+   `manifests/`).
+5. **Run** it: `./bin/acme up`, `./bin/acme web`, `make test`.
+
+Every field, the bin shim, the make fragment and upgrading are in
+[docs/distributions.md](distributions.md);
+[examples/distribution/](../examples/distribution) is what `create acme` writes.
+
+## Distributions
+
+You run Den through a small repo of your own (a _distribution_):
+
+```
+my-dev/
+├── den.yml               # who this distribution is (below)
+├── package.json          # pins an exact @monster-orange/den version
+├── config/<name>.yml     # your org config
+├── config/environments/  # one <env>.json per environment
+├── manifests/            # manifests for repos that don't carry their own
+├── tests/pillars/<pillar>/   # your own suites (e.g. tests/pillars/perf/<module>/test.js)
+├── bin/<cli>             # shim: DEN_ROOT=<this dir> exec node_modules/@monster-orange/den/bin/den
+└── Makefile              # include node_modules/@monster-orange/den/make/den.mk
+```
+
+`den.yml` names the product. Every runtime name derives from it:
+
+```yaml
+product:
+  name:
+    acme # CLI "acme", env vars ACME_*, config/acme.yml,
+    # manifests .acme.yml, state ~/.acme,
+    # managed clones .acme-services/, workspaces acme-workspaces/
+  # Override any of them: cli, env_prefix, config, manifest, state_dir,
+  # services_dir, workspaces_dir
+```
+
+Den's own checkout is a distribution named `den`, so in this repo the CLI is
+`./bin/den`, the config is `config/den.yml`, and env vars are `DEN_*`.
+
+## Repos opt in with a manifest
+
+A repo joins by carrying a manifest at its root (`.<name>.yml`, e.g.
+`.den.yml`) whose commands delegate to the repo's own targets. Den never
+reaches inside a repo beyond that. When a repo has no manifest, the
+distribution can hold one for it in `manifests/<repo>.<name>.yml`; the repo's
+own manifest always wins.
+
+```yaml
+# demo-api: a self-contained service. Nothing it calls, so it starts alone.
+version: 1
+name: demo-api
+application: shop # the application this repo belongs to (den apps)
+compose:
+  files: [docker-compose.yml]
+  routes:
+    api: api:8080 # https://api.demo-api.<edge domain>
+services:
+  demo-api:
+    commands:
+      local:
+        setup: make setup
+        preflight: make test
+# OWASP ZAP target for the security pillar (`make test-sec-api env=local`).
+security:
+  api:
+    hosts:
+      local: ["https://api.demo-api.globex.localhost"]
+```
+
+That is `examples/demo/demo-api/.den.yml`; the other demo repos are in
+[`examples/demo/`](../examples/demo/).
+
+## What it does
+
+- **Workspaces.** A workspace is a set of repos. Each is either
+  _dev-managed_ (your checkout, your branch) or _managed_ (cloned by Den and
+  kept on a tracking branch).
+- **Derived dependency graph.** Start and stop order comes from real signals in
+  each repo — SDK imports, `*_URL` env vars, IaC references, event rules,
+  readiness probes — tuned in config with `graph.aliases`, `graph.edges` and
+  an optional shared local-infra repo (`graph.infra`).
+- **Local HTTPS edge.** One local proxy routes `https://<route>.<domain>` to
+  each service, with an optional project CA.
+- **Test pillars.** `smoke`, `browser` (synthetic Playwright), `api`,
+  `journeys` (agent-driven), `perf` (k6), `security` (OWASP ZAP against hosts
+  you own) and `suites` (a repo's own commands).
+- **Releases.** A release view over the repos and deploy workflows your config
+  lists.
+- **Agents and sessions.** `sessions start` runs a terminal that outlives the
+  web server; `agents start` runs a persona (Den ships a default pack) in a
+  workspace's checkout, with an MCP server pinned to that workspace and a
+  token of its own. The web UI's Agents tab lists them and opens their
+  terminals.
+- **Browser sign-in beyond loopback.** On localhost no route needs a sign-in.
+  Through the edge or on a non-loopback bind, every route needs one:
+  `<cli> web login` prints a one-time link (`web open` opens it).
+- **Web UI and CLI** over the same state.
+
+## Strategies
+
+Concerns that vary by org are strategies selected in config, never hard-wired:
+
+| Concern          | Built-in choices                        | Chosen in                                                                                                            |
+| ---------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| Secrets backend  | `none`, `env`, `doppler`, `1password`   | `secrets.provider` in the org config; per engineer in `config/local/user.yml`; per shell `<PREFIX>_SECRETS_PROVIDER` |
+| Test-user tokens | `local-jwt`, `cognito`, `auth0`, `none` | `auth.provider` in `config/environments/<env>.json`                                                                  |
+
+A new secrets backend implements `SecretsProvider`
+(`src/shared/secrets/types.ts`) and registers as a strategy
+(`src/shared/secrets/strategies.ts`); a distribution needs no store at all
+(`none`, see "Secrets" in `docs/distributions.md`). A new identity provider implements a token
+provider in `src/shared/auth/token-providers/`.
+
+## CLI
+
+```bash
+den up [repo]          # start the repo's derived dependency closure (-x deps only, -n dry run)
+den down [repo]        # stop it cleanly (--with-deps: and what it sits on)
+den restart [svc...]   # restart services (-A <app> for a whole application)
+den status             # service health for the active workspace
+den apps               # Org > Application > Repo > Services
+den graph [repo]       # the derived dependency graph
+den logs [repo]        # tail a repo's local logs
+den use-local [repo]   # use your checkout · use-managed [repo] to switch back
+den workspace list     # workspaces (activate · deactivate · use · create · delete)
+den run                # run test suites (interactive, or with options)
+den web                # the web UI (open · login · sessions · logout · token)
+den sessions list      # terminals that outlive the web server (start · attach · kill)
+den agents list -w ws  # a workspace's agents (start · stop · resume · personas)
+den doctor             # the strategies in use and whether each can work (--probe)
+den --help             # everything else
+```
+
+`up`, `down`, `restart` and `setup` take `-w <workspace>`. Without it, a
+service you name is found in the focused workspace first, then across the
+other active workspaces; when it is in several, the error lists the `-w`
+command for each.
+
+In a distribution the command is that distribution's `cli` name.
+
+## Developing Den
+
+```bash
+npm ci
+npm run typecheck
+npm run lint
+npm test
+DEN_ORG_NAMES_FILE=<patterns file> node scripts/org-name-gate.mjs
+```
+
+CI runs the same gates. The org-name gate fails the build when any file names
+an organisation, product, host or account; its patterns are kept out of this
+repo (a CI secret) so the list itself is never published. See
+[CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## License
+
+[MIT](../LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/den-config.ts

@@ -244,10 +244,16 @@ export interface DenConfig {
    */
   mcp?: McpConfig;
   /**
-   * Agents: `max_concurrent` caps the sessions running at once in this
-   * distribution (default 4). See readAgentsConfig.
+   * Agents: `max_concurrent` caps the agents running at once in this
+   * distribution (default 4); plain sessions never count. See
+   * readAgentsConfig.
    */
   agents?: AgentsConfig;
+  /**
+   * Plain sessions (`<cli> sessions start`): `max_concurrent` caps those
+   * running at once (default 8); agents never count. See readSessionsConfig.
+   */
+  sessions?: SessionsConfig;
   /**
    * The web UI: `port` (read by edge/config.ts readWebPort) and `service`,
    * the launchd service `<cli> service` installs. See readWebServiceConfig.
@@ -558,6 +564,7 @@ export function readDenConfig(): DenConfig {
       security: parsed?.security,
       mcp: parsed?.mcp,
       agents: parsed?.agents,
+      sessions: parsed?.sessions,
       web: parsed?.web,
       test_accounts: parsed?.test_accounts,
       defaults: parsed?.defaults,
@@ -739,7 +746,7 @@ export function readMcpConfig(
 
 /** `agents:` in the org config. */
 export interface AgentsConfig {
-  /** Sessions that may run at once (default 4). */
+  /** Agents that may run at once (default 4); plain sessions never count. */
   max_concurrent?: number;
   /**
    * Persona packs (AG-2a): directories of persona files, relative to the
@@ -845,6 +852,48 @@ export function readAgentsConfig(
   return out;
 }
 
+/** `sessions:` in the org config: plain sessions (`<cli> sessions start`). */
+export interface SessionsConfig {
+  /** Plain sessions that may run at once (default 8); agents never count. */
+  max_concurrent?: number;
+}
+
+export const DEFAULT_SESSIONS_MAX_CONCURRENT = 8;
+
+/** `sessions:` with its defaults applied. */
+export interface ResolvedSessionsConfig {
+  maxConcurrent: number;
+}
+
+/**
+ * The effective sessions config. Anything malformed throws, naming the key,
+ * as readAgentsConfig does: a typo must not lift the cap.
+ */
+export function readSessionsConfig(
+  config: DenConfig = readDenConfig(),
+): ResolvedSessionsConfig {
+  const raw = (config.sessions ?? {}) as unknown;
+  if (!isMapping(raw))
+    throw new Error(`sessions: must be a mapping (got ${JSON.stringify(raw)})`);
+  for (const k of Object.keys(raw))
+    if (k !== "max_concurrent")
+      throw new Error(
+        `sessions.${k}: unknown key (sessions: takes max_concurrent)`,
+      );
+  const out: ResolvedSessionsConfig = {
+    maxConcurrent: DEFAULT_SESSIONS_MAX_CONCURRENT,
+  };
+  const max = raw.max_concurrent;
+  if (max !== undefined) {
+    if (typeof max !== "number" || !Number.isInteger(max) || max < 1)
+      throw new Error(
+        `sessions.max_concurrent: must be a whole number of at least 1 (got ${JSON.stringify(max)})`,
+      );
+    out.maxConcurrent = max;
+  }
+  return out;
+}
+
 // ── Web UI service (`<cli> service`) ──────────────────────────────────────────
 
 /** `web:` in the org config. */

package/src/shared/sessions/client.ts

@@ -16,6 +16,7 @@ import type {
   AttachHandlers,
   Attachment,
   SessionInfo,
+  SessionPool,
   SessionSignal,
   SessionSpec,
 } from "./types.js";
@@ -125,6 +126,11 @@ export class HostClient extends EventEmitter {
     spec: SessionSpec,
     opts: {
       limit?: number;
+      /**
+       * Which running sessions `limit` counts: agents (agents.max_concurrent)
+       * or plain ones (sessions.max_concurrent). Without it, all of them.
+       */
+      pool?: SessionPool;
       /** `--keep-env` names, for the host's audit line (never values). */
       keptEnv?: { name: string; credentialShaped: boolean }[];
       /** Who asked, for that line. */
@@ -139,6 +145,7 @@ export class HostClient extends EventEmitter {
     const r = await this.request("start", {
       spec,
       ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+      ...(opts.pool !== undefined ? { pool: opts.pool } : {}),
       ...(opts.keptEnv?.length || opts.refusedEnv?.length
         ? { actor: opts.actor ?? "unknown" }
         : {}),

package/src/shared/sessions/den-pty.ts

@@ -21,6 +21,7 @@ import type {
   Attachment,
   SessionBackend,
   SessionInfo,
+  SessionPool,
   SessionRef,
   SessionSignal,
   SessionSpec,
@@ -32,8 +33,10 @@ export { BACKEND_ID as DEN_PTY_ID };
 export interface DenPtyOptions {
   /** A client of the running host (ensureHost). */
   client: HostClient;
-  /** Applied to every start: agents.max_concurrent. */
+  /** Applied to every start, counting `pool`'s running sessions. */
   limit?: number;
+  /** agents (agents.max_concurrent) or sessions (sessions.max_concurrent). */
+  pool?: SessionPool;
 }
 
 export class DenPtyBackend implements SessionBackend {
@@ -49,7 +52,12 @@ export class DenPtyBackend implements SessionBackend {
   }
 
   async start(spec: SessionSpec): Promise<SessionRef> {
-    return (await this.opts.client.start(spec, { limit: this.opts.limit })).ref;
+    return (
+      await this.opts.client.start(spec, {
+        limit: this.opts.limit,
+        ...(this.opts.pool ? { pool: this.opts.pool } : {}),
+      })
+    ).ref;
   }
   list(): Promise<SessionInfo[]> {
     return this.opts.client.list();

package/src/shared/sessions/host.ts

@@ -29,7 +29,12 @@ import {
   type Request,
 } from "./protocol.js";
 import type { PtyLoad, PtyProcess } from "./pty.js";
-import { SESSION_SIGNALS, type SessionInfo } from "./types.js";
+import {
+  SESSION_POOLS,
+  SESSION_SIGNALS,
+  type SessionInfo,
+  type SessionPool,
+} from "./types.js";
 
 export const BACKEND_ID = "den-pty";
 
@@ -58,6 +63,8 @@ interface Session {
   log: ScrollbackLog;
   /** aid → its connection. */
   attachments: Map<string, Conn>;
+  /** The cap it counts against (start's `pool`), when one was named. */
+  pool?: SessionPool;
 }
 
 class Conn {
@@ -82,6 +89,17 @@ class Refusal extends Error {
 const isInt = (n: unknown, min: number, max: number): n is number =>
   typeof n === "number" && Number.isInteger(n) && n >= min && n <= max;
 
+/**
+ * The cap refusal: "2 agents are running and agents.max_concurrent is 2".
+ * With no pool (an older client's limit) every session counts, and the key
+ * is agents.max_concurrent, as it was.
+ */
+function capMessage(live: number, limit: number, pool?: unknown): string {
+  const noun = pool === "agents" ? "agent" : "session";
+  const key = pool === "sessions" ? "sessions" : "agents";
+  return `${live} ${noun}${live === 1 ? " is" : "s are"} running and ${key}.max_concurrent is ${limit}`;
+}
+
 function pidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -528,20 +546,26 @@ export class SessionHost {
     );
     if (same.some((s) => !s.info.exited))
       throw new Refusal("exists", `${name} is already running`);
-    const live = [...this.sessions.values()].filter(
-      (s) => !s.info.exited,
-    ).length;
+    // A cap counts its own pool's running sessions: agents.max_concurrent
+    // the agents, sessions.max_concurrent the plain ones. A limit with no
+    // pool (an older client) counts every running session, as before.
+    const pool = req.pool;
+    if (pool !== undefined && !SESSION_POOLS.includes(pool as SessionPool))
+      throw new Refusal(
+        "bad-request",
+        `pool must be ${SESSION_POOLS.join(" or ")}`,
+      );
     if (req.limit !== undefined) {
       if (!isInt(req.limit, 1, 100_000))
         throw new Refusal(
           "bad-request",
           "limit must be a whole number of at least 1",
         );
+      const live = [...this.sessions.values()].filter(
+        (s) => !s.info.exited && (pool === undefined || s.pool === pool),
+      ).length;
       if (live >= req.limit)
-        throw new Refusal(
-          "cap",
-          `${live} session${live === 1 ? " is" : "s are"} running and agents.max_concurrent is ${req.limit}`,
-        );
+        throw new Refusal("cap", capMessage(live, req.limit, pool));
     }
     const load = this.opts.pty();
     if (!load.available) throw new Refusal("unavailable", load.reason);
@@ -582,6 +606,7 @@ export class SessionHost {
         },
       ),
       attachments: new Map(),
+      ...(pool !== undefined ? { pool: pool as SessionPool } : {}),
     };
     this.sessions.set(id, s);
     this.persist(s);

package/src/shared/sessions/types.ts

@@ -32,6 +32,14 @@ export interface SessionInfo {
   prompted?: boolean;
 }
 
+/**
+ * The cap a start counts against: `agents` (agents.max_concurrent) or
+ * `sessions` (sessions.max_concurrent, the plain ones), each counting only
+ * its own running sessions.
+ */
+export const SESSION_POOLS = ["agents", "sessions"] as const;
+export type SessionPool = (typeof SESSION_POOLS)[number];
+
 /** What to run. `env` is the whole environment: nothing is inherited. */
 export interface SessionSpec {
   name: string;

package/src/ui/cli/agent-ops.ts

@@ -32,7 +32,7 @@
  *           actor token; the old one stops working.
  *
  * Nothing here takes a grant: grants come from the org config only. The
- * host enforces agents.max_concurrent on every start.
+ * host enforces agents.max_concurrent on every start, counting agents only.
  */
 import * as fs from "fs";
 import * as path from "path";
@@ -515,7 +515,7 @@ async function startSession(
           cols: (tty && d.stdout.columns) || 80,
           rows: (tty && d.stdout.rows) || 24,
         },
-        { limit: d.maxConcurrent() },
+        { limit: d.maxConcurrent(), pool: "agents" },
       )
       .catch((e: unknown) => capOrThrow(d, e));
   } catch (e) {

package/src/ui/cli/agents-command.ts

@@ -26,7 +26,7 @@
  *           same conversation id (there is nothing to continue).
  *
  * Nothing here takes a grant: grants come from the org config only. The
- * host enforces agents.max_concurrent on every start.
+ * host enforces agents.max_concurrent on every start, counting agents only.
  */
 import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
 import { HostError } from "../../shared/sessions/client.js";

package/src/ui/cli/index.ts

@@ -2711,8 +2711,11 @@ class DenCLI {
     );
     console.log();
     console.log(chalk.bold("  Flags:"));
+    // Two spaces at least between a flag and its text, a long one too.
     const row = (f: string, d: string) =>
-      console.log(`    ${chalk.cyan(f.padEnd(20))}${d}`);
+      console.log(
+        `    ${chalk.cyan(f.padEnd(Math.max(20, f.length + 2)))}${d}`,
+      );
     row(
       "-x, --exclude",
       "start only the dependencies, not the current/seed repo",
@@ -4660,6 +4663,35 @@ class DenCLI {
         if (!d.available) warn(`edge.tls ${edge.tls.strategy}: ${d.reason}`);
       }
     }
+    // The web keys: a wrong value would stop `web up`; one read and
+    // ignored (the distribution's web.allow_plain_http_remote: only
+    // config/local/user.yml counts) is flagged, as `web up` says it.
+    {
+      const { ignoredConfigWarning, readWebAuthConfig } =
+        await import("../../shared/web-session.js");
+      try {
+        const w = ignoredConfigWarning(
+          readWebAuthConfig(getDistRoot(), product().configFile),
+        );
+        if (w) console.warn(chalk.yellow(`\n  ⚠  ${w}`));
+      } catch (e) {
+        console.error(chalk.red(`\n  ✗  web: ${(e as Error).message}`));
+        process.exitCode = 1;
+      }
+    }
+    // The caps: agents.max_concurrent (agents) and sessions.max_concurrent
+    // (plain sessions). A wrong value would refuse every start.
+    {
+      const { readAgentsConfig, readSessionsConfig } =
+        await import("../../shared/den-config.js");
+      for (const read of [readAgentsConfig, readSessionsConfig])
+        try {
+          read();
+        } catch (e) {
+          console.error(chalk.red(`\n  ✗  ${(e as Error).message}`));
+          process.exitCode = 1;
+        }
+    }
     const positional = args.filter((a) => !a.startsWith("-"));
     const held = args.includes("--held");
     // Bare `validate` in the distribution root (which has no manifest of its

package/src/ui/cli/sessions-command.ts

@@ -13,12 +13,16 @@
  *
  * The R8 lock is the web UI's (an in-memory admin password in the web
  * server); CLI service actions (up, down) do not consult it, so neither do
- * these. agents.max_concurrent caps every start.
+ * these. sessions.max_concurrent caps the plain sessions running at once;
+ * agents count against agents.max_concurrent instead, never this one.
  */
 import { spawn } from "child_process";
 import * as fs from "fs";
 import * as path from "path";
-import { readAgentsConfig } from "../../shared/den-config.js";
+import {
+  readAgentsConfig,
+  readSessionsConfig,
+} from "../../shared/den-config.js";
 import { cliEntrypoint } from "../../shared/engine.js";
 import { getDistRoot, getInvokeCwd, getStateDir } from "../../shared/paths.js";
 import { product } from "../../shared/product.js";
@@ -64,7 +68,7 @@ export const SESSIONS_HELP = {
     "session host (one per distribution, started on demand).",
     "",
     "{cli} sessions start --workspace <ws> --name <n> [--cwd <dir>] [--keep-env NAME…] -- <argv…>",
-    "    run argv in a PTY as <dist>-<ws>:<n> (cwd: here); capped by agents.max_concurrent",
+    "    run argv in a PTY as <dist>-<ws>:<n> (cwd: here); capped by sessions.max_concurrent",
     "    env: PATH, HOME, USER, LOGNAME, SHELL, TERM, COLORTERM, LANG, LC_*, TZ,",
     "    TMPDIR only; --keep-env NAME (exact, repeatable; audited) adds one",
     "    (never a person's credential: DEN_PERSON_TOKEN, a web.secret path)",
@@ -97,7 +101,10 @@ export interface SessionsDeps {
   connectExisting?: () => Promise<HostClient | null>;
   pty?: () => PtyLoad;
   workspaceExists?: (ws: string) => boolean;
+  /** agents.max_concurrent: the agents running at once. */
   maxConcurrent?: () => number;
+  /** sessions.max_concurrent: the plain sessions running at once. */
+  maxSessions?: () => number;
   invokeCwd?: () => string;
   env?: NodeJS.ProcessEnv;
   out?: (line: string) => void;
@@ -114,7 +121,10 @@ export interface Resolved {
   connectExisting: () => Promise<HostClient | null>;
   pty: () => PtyLoad;
   workspaceExists: (ws: string) => boolean;
+  /** agents.max_concurrent: the agents running at once. */
   maxConcurrent: () => number;
+  /** sessions.max_concurrent: the plain sessions running at once. */
+  maxSessions: () => number;
   invokeCwd: () => string;
   env: NodeJS.ProcessEnv;
   out: (line: string) => void;
@@ -180,6 +190,7 @@ export function resolveDeps(d: SessionsDeps): Resolved {
     pty: d.pty ?? (() => loadPty()),
     workspaceExists: d.workspaceExists ?? defaultWorkspaceExists,
     maxConcurrent: d.maxConcurrent ?? (() => readAgentsConfig().maxConcurrent),
+    maxSessions: d.maxSessions ?? (() => readSessionsConfig().maxConcurrent),
     invokeCwd: d.invokeCwd ?? getInvokeCwd,
     env: d.env ?? process.env,
     out: d.out ?? ((l) => console.log(l)),
@@ -437,7 +448,7 @@ async function start(args: string[], d: Resolved): Promise<number> {
     d.err(`  \`${d.cli} doctor\` shows the session backend's state.`);
     return 1;
   }
-  const limit = d.maxConcurrent();
+  const limit = d.maxSessions();
   const full = sessionName(d.dist, ws, name);
   const tty = d.stdout.isTTY;
   return withClient(d, async (c) => {
@@ -453,6 +464,7 @@ async function start(args: string[], d: Resolved): Promise<number> {
         },
         {
           limit,
+          pool: "sessions",
           // Audited by the host: each name, and whether it is
           // credential-shaped; never a value.
           ...(kept.length
@@ -480,7 +492,7 @@ async function start(args: string[], d: Resolved): Promise<number> {
       d.err(`✗ ${e.message}`);
       if (e.code === "cap")
         d.err(
-          `  Stop one first (\`${d.cli} sessions kill <name>\`), or raise agents.max_concurrent.`,
+          `  Stop one first (\`${d.cli} sessions kill <name>\`), or raise sessions.max_concurrent.`,
         );
       if (e.code === "exists")
         d.err(

package/src/ui/cli/web-command.ts

@@ -21,6 +21,7 @@ import {
   rotateWebSecret,
 } from "../../shared/web-secret.js";
 import {
+  ignoredConfigWarning,
   localhostOrigin,
   loginLink,
   mintLoginCode,
@@ -1242,7 +1243,12 @@ export async function cmdWeb(args: string[]): Promise<void> {
 
   // SEC-1b: a wrong web.allow_plain_http_remote would stop the server at
   // start; say so here, naming the key, instead of "did not become ready".
-  readWebAuthConfig(getDistRoot(), product().configFile);
+  // A key read and ignored (the distribution's web.allow_plain_http_remote:
+  // only user.yml counts) is said here too, not only in the server's log.
+  const ignored = ignoredConfigWarning(
+    readWebAuthConfig(getDistRoot(), product().configFile),
+  );
+  if (ignored) console.log(chalk.yellow(`\n  ⚠ ${ignored}`));
 
   const apiRunning = await isDenWebApiRunning(options.port);
   let running = apiRunning && (await isDenWebUiReady(options.port));

package/src/ui/server/agent-routes.ts

@@ -18,7 +18,8 @@
  *   - a person only: an agent (its actor token, SEC-1c) can't start or
  *     stop agents from the page (403; agents use MCP agent_spawn, §5,
  *     under its own guards);
- *   - agents.max_concurrent (the host's cap: 429 cap).
+ *   - agents.max_concurrent (the host's cap on agents, never plain
+ *     sessions: 429 cap).
  * The env is the CLI's (§5a-env): the allowlist and the runtime's, built
  * from this server's environment, never all of it. Every action, refused
  * or done, is audited (recordAction) with the person as its actor.

package/src/ui/server/index.ts

@@ -4543,6 +4543,17 @@ try {
   serverLog(`  ⚠ cache warm-up failed: ${(e as Error).message}`);
 }
 
+// Ignored config keys (a distribution's web.allow_plain_http_remote, the
+// old web.session lifetimes): the in-app log, and stderr, which is web.log
+// even when `web up` starts this --silent. Before the bind refusal, which
+// such a key often explains.
+{
+  const ignored = ignoredConfigWarning(WEB_AUTH);
+  if (ignored) {
+    pushLog("warn", `  ⚠ ${ignored}`);
+    if (!outputLost()) process.stderr.write(`  ⚠ ${ignored}\n`);
+  }
+}
 // §4: a non-loopback bind needs HTTPS in front, or the person's say-so.
 {
   const refusal = bindRefusal(BIND_HOST, {
@@ -4554,10 +4565,6 @@ try {
     process.exit(1);
   }
 }
-{
-  const ignored = ignoredConfigWarning(WEB_AUTH);
-  if (ignored) serverLog(`  ⚠ ${ignored}`, "warn");
-}
 // SEC-1a: the secret the CLI's person token is derived from (0600 in the
 // state dir). Never printed or logged; a failure leaves bearers unverifiable.
 try {

package/src/ui/server/public/agents-page.js

@@ -104,6 +104,12 @@ function displayName(r) {
   return r.kind === "agent" ? (r.persona ?? r.label) : r.label;
 }
 
+// A pane's title and its Close: the agent's display name (AG-10.8), else
+// its id, never the persona. There is no display name before AG-10.
+function paneName(r) {
+  return r.kind === "agent" ? r.displayName || r.agent || r.label : r.label;
+}
+
 function rowHtml(r) {
   const open = st.open.includes(r.id);
   const nm =
@@ -293,7 +299,7 @@ function paintLayout() {
 function paintBar(p) {
   const r = rowOf(p.id);
   const bar = p.el.querySelector(".bar2");
-  const name = r ? displayName(r) : p.label || p.id;
+  const name = r ? paneName(r) : p.label || p.id;
   const where = r
     ? [r.workspace, r.runtime].filter(Boolean).join(" · ")
     : p.workspace || "";