@monster-orange/den 0.4.3 → 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,19 +377,37 @@ 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 lock (🔒 in the top bar) is asked for only when an action needs it,
-on any page: a page that thinks it's locked asks the server again first
-(another tab or device may have unlocked it), then, when a password is
-stored, loads it from the vault (once a page; a page view alone never
-wakes the vault), and only then shows the password field. Its popover is
-always on top, even over a dialog, and a dialog that needs the lock (Start
-agent) asks for the password itself.
+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.
@@ -1190,8 +1208,8 @@ 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). The edge counts as local too (0.4.3): opening
+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
@@ -1448,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
@@ -1479,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
@@ -1525,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`),
@@ -1658,7 +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 [--json]            # can each runtime run here, and why not
+<cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
 <cli> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -1708,9 +1787,10 @@ started. The workspace header counts them ("2 agents").
 - 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
@@ -1720,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).
 
@@ -1743,12 +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. It says before Start whether the runtime can run, as the
-  Workspaces page's form does. While the lock is closed, the dialog asks
-  for the admin password at its top, and Start unlocks, then starts, without
-  closing anything.
+  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
@@ -1813,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.
@@ -1835,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).
 
@@ -1884,7 +1964,8 @@ 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) runs Claude Code's `claude`, found as
   below; `<cli> doctor` reads its version from the install, without running
@@ -1899,14 +1980,64 @@ 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. **`agents.runtimes.<id>.bin`** in `config/local/user.yml`: the absolute
+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
@@ -1920,14 +2051,28 @@ first match wins:
          bin: /Users/me/.local/bin/claude
    ```
 
-2. **Your login shell's PATH**: the web server asks `$SHELL -lc` once at
+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.
-3. **The server's own PATH.**
-4. **The runtime's install directories.** 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.
+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
@@ -1936,17 +2081,19 @@ 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, its status, the CLI it
-runs and where that came from (the `agents.runtimes` setting, the login
-shell's PATH, PATH, or an install directory), its version (`claude
+**`<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; `--json` prints what the Start
-dialog gets.
+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)  [default]
+den-claude (Claude Code, Anthropic)  [default]
   status    ✗ unavailable: claude not found (searched 5 directories)
   searched  /usr/bin
             /bin
@@ -1955,9 +2102,12 @@ den-claude (Claude Code)  [default]
             then run `<cli> agents doctor` again
 ```
 
-`GET /api/personas` gives each runtime its `version`, `path`, `source`
-(`setting`, `login-shell`, `well-known` or `PATH`), `searched` and
-`setting` (the user.yml key), and `userConfig`, the user.yml to edit.
+`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.3",
+  "version": "0.4.4",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/agents/catalog-runtime.ts

@@ -0,0 +1,178 @@
+/**
+ * A runtime from a catalog entry (AG-0.5, catalog.ts): found by AG-0.1's
+ * search with the entry's binary names and install directories, and
+ * launched as its interactive CLI in the agent's directory (the entry's
+ * launch argv, "{bin}" the path found).
+ *
+ * These don't get Den's tools yet: no MCP config, no permission mode
+ * (AG-12 and AG-13 wire them per runtime). Lists tag them "Den tools:
+ * coming" (denTools: false). Claude Code is den-claude, which takes its
+ * search from the catalog and keeps its own launch.
+ *
+ * checkRuntimeBin is what "Set path…" runs: the entry's version command,
+ * and the entry's identity (its output names it, it resolves into the
+ * vendor's npm package, or under the vendor's install directory), so a
+ * path that isn't that runtime is refused.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { configuredRuntimeBin } from "../den-config.js";
+import { entryDirs, type CatalogEntry } from "./catalog.js";
+import {
+  LaunchError,
+  type DetectOptions,
+  type LaunchOutput,
+  type Runtime,
+  type RuntimeDetect,
+} from "./runtime.js";
+import {
+  locateRuntime,
+  parseVersion,
+  systemBinDirs,
+  versionOutput,
+  type RuntimeFind,
+} from "./runtime-search.js";
+
+/** An entry as AG-0.1's search takes it. */
+export function catalogFind(e: CatalogEntry): RuntimeFind {
+  return {
+    bins: e.bins,
+    dirs: (home, env) => entryDirs(e, home, env, systemBinDirs),
+    versionArgs: e.version.args,
+  };
+}
+
+/** Find an entry's CLI: a setting (workspace or global), else the search. */
+export function detectEntry(
+  e: CatalogEntry,
+  find: RuntimeFind,
+  env: NodeJS.ProcessEnv,
+  opts: DetectOptions,
+): RuntimeDetect {
+  const setting =
+    opts.bin === undefined ? configuredRuntimeBin(e.id) : opts.bin;
+  const found = locateRuntime(e.id, find, env, setting);
+  if (!found.available || !found.path)
+    return {
+      available: false,
+      why: found.why ?? `${e.bins.join(" or ")} not found`,
+      ...(found.source ? { source: found.source } : {}),
+      searched: found.searched,
+    };
+  return {
+    available: true,
+    path: found.path,
+    ...(found.source ? { source: found.source } : {}),
+    searched: found.searched,
+  };
+}
+
+/** The launch argv: the entry's template, "{bin}" the path found. */
+export function launchArgv(e: CatalogEntry, bin: string): string[] {
+  return e.launch.argv.map((a) => a.split("{bin}").join(bin));
+}
+
+/** A runtime for a catalog entry other than Claude Code (den-claude). */
+export function catalogRuntime(e: CatalogEntry): Runtime {
+  const find = catalogFind(e);
+  const detect = (
+    env: NodeJS.ProcessEnv = process.env,
+    opts: DetectOptions = {},
+  ) => detectEntry(e, find, env, opts);
+  return {
+    id: e.id,
+    label: e.name,
+    vendor: e.vendor,
+    catalog: e,
+    find,
+    denTools: false,
+    detect,
+    launch(input): LaunchOutput {
+      let bin = input.bin;
+      if (!bin) {
+        const d = detect(input.env);
+        if (!d.available || !d.path)
+          throw new LaunchError(`${e.id}: ${d.why ?? "not found"}`);
+        bin = d.path;
+      }
+      return {
+        argv: launchArgv(e, bin),
+        env: {},
+        warnings: [
+          `${e.name} runs as its own CLI in ${input.worktree}: Den's tools (MCP) and permission modes are coming for it`,
+        ],
+      };
+    },
+    approvals: "terminal",
+    scrubEnv: [],
+  };
+}
+
+/** The npm package a file resolves into (the nearest package.json's name). */
+function packageOf(real: string): string | undefined {
+  for (let dir = path.dirname(real), i = 0; i < 8; i++) {
+    try {
+      const pkg = JSON.parse(
+        fs.readFileSync(path.join(dir, "package.json"), "utf-8"),
+      ) as { name?: unknown };
+      if (typeof pkg.name === "string") return pkg.name;
+    } catch {
+      /* not here */
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return undefined;
+}
+
+export type BinCheck =
+  | { ok: true; path: string; version: string }
+  | { ok: false; why: string };
+
+/**
+ * Whether `bin` is entry `e`'s runtime: an absolute path to an executable
+ * file whose version command exits 0 and prints a version, and whose
+ * output, npm package or real location names it. Runs only that command
+ * (stdin closed, under a timeout). Never throws.
+ */
+export async function checkRuntimeBin(
+  e: CatalogEntry,
+  bin: string,
+  env: NodeJS.ProcessEnv,
+): Promise<BinCheck> {
+  const p = bin.trim();
+  const shown = p.replace(/[^\x20-\x7e]/g, "?").slice(0, 200);
+  if (!path.isAbsolute(p))
+    return { ok: false, why: `"${shown}" is not an absolute path` };
+  let real: string;
+  try {
+    const st = fs.statSync(p);
+    fs.accessSync(p, fs.constants.X_OK);
+    if (!st.isFile()) throw new Error("not a file");
+    real = fs.realpathSync(p);
+  } catch {
+    return { ok: false, why: `${shown} is not an executable file` };
+  }
+  const cmd = `${path.basename(p)} ${e.version.args.join(" ")}`;
+  const r = await versionOutput(p, e.version.args, env);
+  if (!r.ok) return { ok: false, why: `\`${cmd}\` failed: not ${e.name}` };
+  const version = parseVersion(r.out);
+  if (!version)
+    return { ok: false, why: `\`${cmd}\` printed no version: not ${e.name}` };
+  const idn = e.version.identity;
+  const home = env.HOME && path.isAbsolute(env.HOME) ? env.HOME : undefined;
+  const under = (idn.realpath_under ?? []).flatMap((d) =>
+    d.startsWith("~/") ? (home ? [path.join(home, d.slice(2))] : []) : [d],
+  );
+  const named =
+    (idn.output !== undefined && new RegExp(idn.output, "i").test(r.out)) ||
+    (idn.package !== undefined && packageOf(real) === idn.package) ||
+    under.some((d) => real === d || real.startsWith(d + path.sep));
+  if (!named)
+    return {
+      ok: false,
+      why: `${shown} is not ${e.name}: its version output, package and location don't name it`,
+    };
+  return { ok: true, path: p, version };
+}