@monster-orange/den 0.4.2 → 0.4.4

package/docs/distributions.md

@@ -352,7 +352,7 @@ where it is, under `secrets.refs`:
 
 | Ref                  | Feature                                                      |
 | -------------------- | ------------------------------------------------------------ |
-| `sudo`               | The saved local-dev sudo password (auto-unlock, "Save to …") |
+| `sudo`               | The saved admin password, for sudo (auto-load, "Save to …")  |
 | `journeys_agent_key` | The journeys agent's API key, when `CURSOR_API_KEY` is unset |
 
 ```yaml
@@ -377,12 +377,38 @@ secrets:
 and `env` need a `key` (or an env-shaped `field`). There are no defaults:
 a ref that is not set is **not configured**, and its feature says so
 ("not configured: set secrets.provider and secrets.refs.sudo in
-config/acme.yml") instead of running a CLI. The interactive unlock always
+config/acme.yml") instead of running a CLI. Typing the password always
 works; only the saved password needs `refs.sudo`.
 `/api/sudo-password/vault-status` reports `backend`, `label`,
 `configured`, `backendAvailable`, `reason` and `hasStored` (`opAvailable`
 is a deprecated alias of `backendAvailable`, kept for one minor).
 
+The admin password is for sudo, and nothing else (LK-0). It is no sign-in
+and no access check: starting, stopping and resuming agents, sessions and
+terminals, and a service whose commands run no sudo, never ask for it.
+Den asks only when a command it runs is about to run sudo without it:
+every service command (up, down, restart, setup, sync) gets a `sudo` shim
+first on its `PATH`. With a password held, the shim gives it to sudo. With
+none, sudo that needs no password (NOPASSWD, a warm cache) runs as it
+would, and anything else never prompts: the shim prints
+`<cli>: needs-sudo: sudo <command>` and fails, and the run's event stream
+carries `{ "type": "needs-sudo", "command": "sudo <command>", "step":
+"<service>" }` (sudo's own "a password is required" counts too, without
+the command). Only then does the page ask, saying "`sudo <command>` needs
+your admin password", with the 🔑 chip in the top bar while it waits. It
+asks the server first (another tab or device may have set it), then, when
+a password is stored, loads it from the vault (a page view alone never
+wakes the vault), and only then shows the password field, always on top,
+even over a dialog. After the password, the action runs again.
+
+Settings › Command line › Admin password says whether it is saved ("Saved
+in 1Password", "Saved for this session" or "Not saved"), with **Forget**:
+`POST /api/sudo-password/forget` drops the password the server holds and,
+when this server saved it to the vault or loaded it from there, clears the
+vault's copy. `GET /api/sudo-password/status` answers `set`,
+`passwordless`, `saved` (`vault`, `session` or null) and `vault` (`{
+configured, label }`, read from the config alone).
+
 A `1password` distribution with no refs gets one warning, in the web
 server's startup log and in `<cli> validate`, with the YAML to add.
 
@@ -1182,10 +1208,12 @@ are the same directory.
 ## Signing in
 
 On localhost nothing asks you to sign in: every page, the agents and the
-terminal work as they are, and the lock (R8) is the only prompt (for
-privileged actions). Signing in is for when the server is reached beyond
-this machine: through the edge hostname, a LAN address, or a bind that
-isn't loopback (`DEN_BIND_HOST`).
+terminal work as they are, and the admin password (R8) is the only prompt,
+asked only when a command Den runs needs sudo. The edge counts as local too (0.4.3): opening
+`https://acme.acme.localhost` from this machine asks for nothing.
+Signing in is for when the server is reached from another machine: the
+edge for a client the edge says is elsewhere, a LAN address, or a bind
+that isn't loopback (`DEN_BIND_HOST`).
 
 There is no password. Reading `web.secret` (32 random bytes, mode 0600 in
 the state dir, made at the first `web up`) proves you are this computer's
@@ -1205,7 +1233,11 @@ user, and the CLI does that for you:
   within 60 seconds, and only this server's secret makes one. It is printed
   only on the one line you asked for (`web login`, or `web up` when it
   couldn't open the browser), never logged. Through the edge or a LAN name,
-  the cookie belongs to that name: `web login --origin https://acme.acme.localhost`
+  the cookie belongs to that name: `web login --host acme.acme.localhost`
+  mints the link for an edge hostname (any edge domain or alias, a VPN name
+  among them; its URL comes from the edge config, and a name the edge
+  doesn't route here is refused, saying what to add), and
+  `web login --origin http://<lan name>:<port>` for any other allowed name
   (the signed-out page there shows the exact command).
 - **The cookie** (`den_session_<port>`) is HttpOnly, SameSite=Strict and
   Path=/, and Secure when the request came over HTTPS through the edge. The
@@ -1222,10 +1254,38 @@ user, and the CLI does that for you:
   open, and changes (an agent's start or resume and the terminal included)
   need only the page's own Origin and CSRF token, which the shell sends.
   The Host allowlist, the Origin check and the CSRF token are what stop
-  another site or a rebinding DNS name. Through the edge, or from another
-  machine, every page and call needs a signed-in browser (or a bearer). A
-  page there shows "Sign in to use <name>" with the command to run; it
-  never asks for a secret. `/api` answers 401 `signin_required`.
+  another site or a rebinding DNS name. From another machine, every page
+  and call needs a signed-in browser (or a bearer). A page there shows
+  "Sign in to use <name>" with the command to run; it never asks for a
+  secret. `/api` answers 401 `signin_required`.
+- **The edge counts as local.** A request for the edge hostname from the
+  edge (an edge peer, below) is treated as loopback: no sign-in on any
+  route, the agents and the terminal included. Host, Origin, CSRF and the
+  agent-token rules still apply. Who the client is comes from the left-most
+  `X-Forwarded-For` entry the edge sends:
+  - loopback, or one of this machine's own interface addresses (a LAN
+    address, or a VPN's such as a Tailscale `100.x`): local;
+  - missing, or a container/VM network's address (the Docker ranges, or a
+    subnet of one of this machine's Docker/OrbStack/VM bridges): Den can't
+    tell (Docker Desktop and OrbStack on macOS hand the edge their
+    gateway's address, and a TCP passthrough in front of the edge hides the
+    client), so local;
+  - any other address: another machine, which needs a sign-in.
+
+  With `DEN_BIND_HOST` beyond loopback (a deliberate exposure, other than
+  the Linux edge's Docker bridge address) the edge needs a sign-in as
+  before. With `forwardedHeaders.insecure` (the edge's default) Traefik
+  keeps an `X-Forwarded-For` the client sent, so this is a convenience,
+  not a boundary: whoever can reach the edge can use the terminal.
+
+- **"Your edge is reachable from other machines".** When Den can tell, at
+  start, that the edge is reachable beyond this machine (an edge hostname
+  that resolves to an address that isn't loopback, such as a LAN or
+  Tailscale address, or the edge container publishing a port on every
+  interface, from `docker inspect`), it writes "Your edge is reachable from
+  other machines; anyone who can reach it can use terminals. Auth is
+  coming." once to `web.log`, and every page shows it as a banner (dismissed
+  per browser).
 - **localhost is the canonical name.** A cookie set on `localhost` isn't
   sent to `127.0.0.1`, so the links Den prints use `localhost`.
 - **Browsers.** Chromium, Firefox and Safari 16.4 or later: a sign-in link
@@ -1406,19 +1466,40 @@ port.
 `--workspace <ws>` and `--actor agent:<id>` (both or neither) scope the server
 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>; 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.
+- **Pinned.** A tool that takes a `workspace` gets `<ws>`. The server
+  registers each workspace tool with "This workspace only" in its
+  description and without the `workspace` parameter (with grants it stays,
+  a name whose description lists `<ws>` and the granted ones; any other
+  name gets the refusal below, not a schema error). A call naming another
+  workspace is refused
+  (`Refused: <tool>: this MCP 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. The refusal
+  says how to get more: a person adds `<other>` to `agents.<id>.grants` in
+  the org config and restarts the agent; an agent can't grant itself one. A
+  refused call is recorded in the activity trail, read tools included.
+- **Says so.** Every scoped answer (`status`, `services`, `applications`,
+  `graph`, `stacks`, `workspaces`) carries a `scope` block: the workspace
+  shown, how many other workspaces there are and how much it leaves out,
+  for example `hidden: { repos: 6 }`, and a note pointing at `org_summary`.
+  A scoped `graph` is the workspace's own repos and the edges out of them
+  (`map: "workspace"`, with `outside` naming the repos they depend on
+  elsewhere). Unscoped with no `workspace` it is the org-wide map
+  (`map: "org-wide"`: every active workspace's graph merged, `workspaces`
+  naming them); with one, that workspace's (`map: "workspace"`).
 - **Filtered.** `workspaces` lists `<ws>` only. `logs_search` and `logs_tail`
   take only `<ws>`'s services, `manifest_validate` takes only an absolute path
   inside one of its repos (or the content), and `workspace_sync` syncs `<ws>`.
   Tests run against the focused workspace, so `tests_available` and
   `run_tests` are refused unless `<ws>` is the focused one.
 - **Not workspace data**, served as unscoped: `environments`,
-  `security_latest`, `release_status` and `edge_status` (the org's and the
-  distribution's, not a workspace's).
+  `security_latest`, `release_status`, `edge_status` and `org_summary` (the
+  org's and the distribution's, not a workspace's).
+- **The org at a glance.** `org_summary` gives every agent every workspace
+  and repo with status counts, the graph, the edge and the environments
+  (see [Tools](#tools)). Detail and actions stay scoped: for workspaces
+  other than `<ws>` it carries names and counts only, never logs, env
+  values, commands, URLs, paths or check output.
 - **Stamped.** Every web API call carries `x-den-mcp-agent: agent:<id>` and
   `x-den-mcp-workspace: <ws>` beside the usual audit headers. The activity
   entry gains `agent` and `workspace`, and the log line reads `· by
@@ -1437,7 +1518,9 @@ agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
 - `<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
-  the scope too.
+  the scope too: they list and validate against the pinned tools, as the
+  server registers them, and `--call` names its scope on stderr
+  (`acme mcp --call: scoped to <ws> as agent:<id>`).
 
 **It binds cooperating agents only.** The scope lives in the MCP server's
 process. The web server's HTTP API does not check it yet, so an agent that
@@ -1483,22 +1566,60 @@ guard off.
 
 Read tools (always registered):
 
-| Tool                | Web API                                    | What                                                                                                                                                                                |
-| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell, or `container <project>/<service>`); `ok` true up, false down, null not known (`pending: true` when a check has not answered) |
-| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                                                          |
-| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                                                                 |
-| `graph`             | `/api/graph`                               | The derived dependency graph and startup order                                                                                                                                      |
-| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                                                      |
-| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                                                                  |
-| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                                                                   |
-| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                                                              |
-| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                                                     |
-| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                                                                   |
-| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                                                                 |
-| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                                                              |
-| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health                                                                                                                             |
-| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names                                                                                                                                     |
+| Tool                | Web API                                    | What                                                                                                                                                                                                                                                                           |
+| ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `status`            | `/api/health`                              | Service health: `counts`, then each service's `state` (`up`, `down`, `redirect`, `pending`, `unknown`, `not-checked`) and, without a plain verdict, `why`; `url` (HTTP check) or `check` (shell, or `container <project>/<service>`); `ok` true up, false down, null not known |
+| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                                                                                                                                                     |
+| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                                                                                                                                                            |
+| `graph`             | `/api/graph`                               | The derived dependency graph (`map: "org-wide"`, every active workspace's; with `workspace`, that one's and its startup order; scoped, the workspace's own)                                                                                                                    |
+| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                                                                                                                                                 |
+| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                                                                                                                                                             |
+| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                                                                                                                                                              |
+| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                                                                                                                                                         |
+| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                                                                                                                                                |
+| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                                                                                                                                                              |
+| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                                                                                                                                                            |
+| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                                                                                                                                                         |
+| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health; an empty list says `why`                                                                                                                                                                                              |
+| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names; `https` (TLS strategy, who supplies the cert, whether HTTPS is serving)                                                                                                                                                       |
+| `org_summary`       | several (read only)                        | Every workspace and repo with status counts, the graph, the edge and the environments; scoped, `yours` adds your workspace's services                                                                                                                                          |
+
+**Health states.** A service with no verdict says why in `why`: no health
+check in the manifest for the env, remote with no check or `target.url`
+for its env, not deployed in the env (no commands and no check there), no
+manifest, or checked but no answer yet. A redirect (`302 → /login`) is
+`redirect` with its status and target (the query is dropped), not down:
+something answered. It is never green either, so an unexpected redirect
+(an ALB answering for a stopped service) is not taken for up; list the code
+in `target.expect` to count it as up. The web health row and `<cli> status`
+use the same rule: the web row shows a redirect muted (with `status` and `redirect`
+in `/api/health`), and `<cli> status` as `redirect 302 → /login`.
+
+**`org_summary`** reads `/api/workspaces`, `/api/health` (local, every
+active workspace), `/api/graph`, `/api/edge` and `/api/environments`:
+
+- `workspaces`: each workspace's name, whether it is active, focused or
+  yours, its state (`running`: every checked service answers; `partial`:
+  some are down; `stopped`: all checked ones are down; `unknown`: nothing
+  checked; `inactive`: not polled), its counts (up, down, redirect,
+  pending, not checked) and its repos, each with its rolled-up state.
+- `graph`: the org-wide map, every active workspace's repos merged (each
+  workspace's graph from the web server; `workspaces` names them, and
+  `unavailable` any whose graph failed), repo names and edge kinds only (no
+  evidence, paths or URLs).
+- `edge`: up, state, domains, the route count and `https`.
+- `environments`: the enabled names, never their values.
+- scoped, `yours`: your workspace's services as `status` gives them.
+
+**`edge_status.https`** says which TLS strategy is in use (`mkcert`,
+`files`, `none`), who supplies the cert (`den`, or `distribution` under
+`tls: files` and the legacy `issue_cert: false`) and whether HTTPS is
+serving: a TLS handshake on the edge's published https port (`serving`
+true or false, null when a proxy in front owns the port), with `detail`.
+`certIssuedByDen` replaces `certIssued`, which is kept for 0.4.4 with a
+note in `deprecated`: it said whether Den minted the cert, so it was
+`false` under `tls: files` while HTTPS worked. `edge status` prints the
+same `https` line.
 
 Action tools (only those named in `mcp.actions`): `service_up`,
 `service_down`, `service_restart` (through `/api/service/exec`),
@@ -1616,6 +1737,7 @@ server scoped to its workspace.
 <cli> agents stop <id> [-w <ws>]
 <cli> agents resume <id> [-w <ws>]
 <cli> agents personas [--json]
+<cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -1654,13 +1776,21 @@ started. The workspace header counts them ("2 agents").
   not running.
 - **+ Start agent** picks a persona (Den's pack, then
   `agents.persona_packs`) and a runtime (the persona's own unless you pick
-  one; one that can't run here is listed, disabled), then Start.
+  one; one that can't run here is listed, disabled), then Start. Under the
+  runtime a line says what Start will run, with its version and path
+  ("Starts Claude Code 2.1.0 from ~/.local/bin/claude"). When that runtime
+  can't run here, Start is disabled and the line says why and how to fix
+  it: where it looked, then "Install it, or set
+  `agents.runtimes.<id>.bin` to its path in <your user.yml>, or run
+  `<cli> agents doctor`" (see [Runtimes](#runtimes)). Nothing fails only
+  after Start.
 - The page and the CLI call the same operations and read the same agent
   records, so an agent started in one is listed in the other. A workspace
   lists its own agents only.
-- Start, Stop and Resume need the lock open (🔓, the same rule as a
-  service's Start), are capped by `agents.max_concurrent`, and are refused
-  for an agent (agents don't start agents from the page). Each one is in the
+- Start, Stop and Resume never ask for the admin password (it is for
+  sudo, and no agent action runs sudo), are capped by
+  `agents.max_concurrent`, and are refused for an agent (agents don't
+  start agents from the page). Each one is in the
   server log's activity, with you as its actor. The agent's environment is
   the one below, built from the web server's environment.
 - **Open in Agents →** (the section header) opens the Agents tab for the
@@ -1670,7 +1800,7 @@ The routes: `GET /api/workspaces/<ws>/agents`, `POST
 /api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
 /api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
 /api/personas` (personas and runtimes). Errors are the usual
-`{ ok: false, error, code, requestId }`: `locked` (423), `cap` (429),
+`{ ok: false, error, code, requestId }`: `cap` (429),
 `conflict` (409, e.g. already running, or no resume), `not_found` (404),
 `exited_at_once` (502, with the session's last lines).
 
@@ -1693,9 +1823,10 @@ agent of the workspaces in view, and their terminals in the browser.
   reload or Back reopens them.
 - **Close** (×) detaches, as leaving the page does: the session keeps
   running, and opening it again replays what you missed. **Stop** (an
-  agent only) is `agents stop`, behind the lock. **+ Start agent** (or
+  agent only) is `agents stop`. **+ Start agent** (or
   `/agents?start=1`) starts one and opens its pane; under All it asks for
-  the workspace.
+  the workspace. It says before Start whether the runtime can run, as the
+  Workspaces page's form does. It never asks for the admin password.
 - ⌘K lists each as "Agents › <ws> / <name>", and "Start agent…".
 - Several browsers and `<cli> sessions attach` can attach to one session
   at once and each sees every byte; the terminal's size is the last
@@ -1721,7 +1852,8 @@ 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;
+   yours (`PATH` with the login shell's and the runtimes' install
+   directories added: [Runtimes](#runtimes));
 2. the variables its runtime names (`envPassthrough`; den-claude:
    `CLAUDE_CONFIG_DIR`);
 3. the runtime's launch env;
@@ -1759,8 +1891,9 @@ header (agent headers without the token are recorded as an unverified
 claim).
 
 An agent's token reaches only its own session's routes, and never a
-shell-grade route, `/api/web/*`, sign-in or sign-out, or the lock: it can't
-unlock, use the sudo password or start another agent (403
+shell-grade route, `/api/web/*`, sign-in or sign-out, or the admin
+password's routes: it can't set the admin password, use it for sudo or
+start another agent (403
 `agent_forbidden`). A person's credential never reaches a session:
 `DEN_PERSON_TOKEN`, a person token's value and a path to `web.secret` are
 always removed, and `sessions start --keep-env` of one is refused and logged.
@@ -1781,7 +1914,8 @@ 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
+session's routes, never a shell-grade route or the admin password's.
+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).
 
@@ -1830,10 +1964,12 @@ are errors naming the file or the key.
 
 ### Runtimes
 
-`<cli> doctor` lists the runtime kind. Two are built in:
+`<cli> doctor` lists the runtime kind. Den knows the runtimes in its
+**catalog** (below); two are special:
 
-- **`den-claude`** (the default) needs `claude` on PATH; doctor reads its
-  version from the install, without running it. It runs `claude --session-id
+- **`den-claude`** (the default) runs Claude Code's `claude`, found as
+  below; `<cli> doctor` reads its version from the install, without running
+  it. It runs `claude --session-id
 <id> --mcp-config <file> --strict-mcp-config --settings <file> [--model <m>]
 --append-system-prompt <role prompt>`, so Den's MCP server is the agent's
   only one, and resumes with `claude --resume <id>`. Permission prompts stay
@@ -1844,7 +1980,134 @@ are errors naming the file or the key.
 - **`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.
+  template references it. It declares no resume. It is startable only for
+  a persona that has an `argv`.
+
+**The runtime catalog.** Den ships, as data, every vendor CLI it knows how
+to find. Each entry was checked against the vendor's own docs or installer:
+
+| id           | Vendor    | CLI                   | Found in (after PATH)                                            | Source                                                                                             |
+| ------------ | --------- | --------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `den-claude` | Anthropic | Claude Code, `claude` | `~/.local/bin`, `~/.claude/local`, system dirs                   | [setup](https://code.claude.com/docs/en/setup)                                                     |
+| `codex`      | OpenAI    | Codex CLI, `codex`    | `$CODEX_INSTALL_DIR`, `~/.local/bin`, system dirs                | [openai/codex](https://github.com/openai/codex), [installer](https://chatgpt.com/codex/install.sh) |
+| `gemini`     | Google    | Gemini CLI, `gemini`  | system dirs                                                      | [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)                            |
+| `grok`       | xAI       | Grok Build, `grok`    | `$GROK_BIN_DIR`, `~/.grok/bin`, `~/.local/bin`, `/usr/local/bin` | [Grok Build](https://docs.x.ai/build/overview), [installer](https://x.ai/cli/install.sh)           |
+
+"System dirs" are `/opt/homebrew/bin`, `/usr/local/bin` and npm's global
+bin. Each one's version is `<bin> --version`. Every vendor here publishes
+an official CLI, so none is left out; a vendor without one is left out
+rather than guessed at (community CLIs, such as third-party "grok" CLIs,
+are not xAI's and are not in the catalog).
+
+Claude Code runs as `den-claude` (above). Every other installed runtime
+runs its own interactive CLI (`codex`, `gemini`, `grok`) in the
+workspace's directory; Den's tools (MCP) and permission modes are coming
+for them, and lists tag them **Den tools: coming**. A runtime is offered
+as startable only when it can start here: installed (or, for `generic`,
+with the persona's `argv`).
+
+A distribution adds entries with `agents.runtime_catalog` in its config,
+and a person with the same key in `config/local/user.yml`. Both go
+through the validator the built-in entries pass; an entry can't reuse a
+catalog id (set a path instead, below):
+
+```yaml
+agents:
+  runtime_catalog:
+    - id: aider # lowercase, starts with a letter
+      vendor: Aider
+      name: Aider
+      bins: [aider] # executable names, no paths
+      version:
+        args: [--version]
+        identity: # at least one: how a path is known to be it
+          output: "aider" # a pattern its version output matches
+          # package: aider-chat        (the npm package it resolves into)
+          # realpath_under: [~/.aider] (where it really lives)
+      dirs: [~/.local/bin, $AIDER_DIR, "{system}"]
+      launch:
+        argv: ["{bin}"] # "{bin}" first: the path found
+```
+
+**Where a runtime's CLI is found.** As your terminal would find it, not
+only on the web server's own PATH (a launchd service's PATH leaves out
+`~/.local/bin`, where Claude Code's native installer puts `claude`). The
+first match wins:
+
+1. **A workspace's own path**, `<ws>.agents.runtimes.<id>.bin` in
+   `config/local/workspaces.yml`, for that workspace's agents. Checked the
+   same way as the next one.
+2. **`agents.runtimes.<id>.bin`** in `config/local/user.yml`: the absolute
+   path of the runtime's CLI. Paths are per machine, so it is read from
+   user.yml only, never from the distribution's config. A bad value (not
+   absolute, missing, not an executable file) makes the runtime
+   unavailable with that reason; Den doesn't fall back to a search.
+
+   ```yaml
+   # config/local/user.yml (gitignored)
+   agents:
+     runtimes:
+       den-claude:
+         bin: /Users/me/.local/bin/claude
+   ```
+
+3. **Your login shell's PATH**: the web server asks `$SHELL -lc` once at
+   start, in the background, under a 3-second timeout. On a timeout or
+   any failure it is left out.
+4. **The server's own PATH.**
+5. **The runtime's install directories** (its catalog entry's; for
+   den-claude: `~/.local/bin`, `~/.claude/local`, `/opt/homebrew/bin`,
+   `/usr/local/bin` and npm's global bin, `$npm_config_prefix/bin` and
+   node's own directory). Den never runs npm to find it.
+6. **Your interactive shell's PATH**, only while a catalog runtime is
+   still not found: `$SHELL -ilc` once (stdin closed, 3-second timeout,
+   the answer kept), for a PATH set only in an interactive startup file
+   such as `~/.zshrc`. Its source is `interactive-shell`.
+
+Paths are this machine's only: Den reads them from `config/local` files,
+never from the distribution's config. **Settings › Agents › Runtimes**
+shows each runtime's status, version, the path in use and its source.
+**Set path…** runs the runtime's version command and refuses a path that
+isn't that runtime (its output, npm package or install location must name
+it); **Clear** removes it. The **Paths for** selector switches between
+every workspace (`user.yml`) and one workspace (`workspaces.yml`). Only a
+person sets a path, never an agent (`POST /api/agents/runtimes/<id>/path`,
+audited).
+
+Sessions and agents Den starts get the same directories on their PATH
+(and a configured CLI's own directory), so the runtime's own tools are
+found too. Two engine variables override the search for tests and
+diagnosis: `DEN_LOGIN_SHELL` (the shell to ask instead of `$SHELL`; `off`
+for none) and `DEN_RUNTIME_DIRS` (a PATH-style list that replaces every
+runtime's install directories; empty for none).
+
+**`<cli> agents doctor`** prints, for each runtime (installed first), its
+status, the CLI it runs and where that came from (the workspace's or the
+user.yml `agents.runtimes` setting, the login shell's PATH, PATH, an
+install directory, or the interactive shell's PATH), its version (`claude
+--version`, run once under a timeout), the directories it searched (names
+only, never an environment value), and the fix when it's missing. It
+resolves the login shell's PATH first, as the web server does. It exits 1
+when the default runtime is unavailable; `-w <ws>` uses that workspace's
+paths; `--json` prints what the Start dialog gets. A search list the same
+as the one above it prints once.
+
+```
+den-claude (Claude Code, Anthropic)  [default]
+  status    ✗ unavailable: claude not found (searched 5 directories)
+  searched  /usr/bin
+            /bin
+            …
+  fix       install Claude Code, or set agents.runtimes.den-claude.bin to its absolute path in /…/config/local/user.yml
+            then run `<cli> agents doctor` again
+```
+
+`GET /api/personas` and `GET /api/agents/runtimes` (each with an optional
+`?workspace=<ws>`) give each runtime its `vendor`, `denTools`, `version`,
+`path`, `source` (`workspace`, `setting`, `login-shell`, `PATH`,
+`well-known` or `interactive-shell`), `searched`, `setting` (the user.yml
+key) and `workspaceSetting` (the workspaces.yml key), and `userConfig`,
+the user.yml to edit.
 
 ### Workspace scope and grants
 

package/package.json

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