@monster-orange/den 0.4.1 → 0.4.3

package/docs/distributions.md

@@ -383,6 +383,14 @@ works; only the saved password needs `refs.sudo`.
 `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.
+
 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.
 
@@ -1183,9 +1191,11 @@ are the same directory.
 
 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`).
+privileged actions). 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 +1215,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 +1236,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
@@ -1581,9 +1623,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
   ```
@@ -1609,12 +1658,13 @@ 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> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
 - `start` runs the agent as session `<dist>-<ws>:<id>` in the workspace's
   checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
-  `agents.max_concurrent`. The id defaults to the persona's id; an id is
+  `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,
@@ -1647,7 +1697,14 @@ 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.
@@ -1688,7 +1745,10 @@ agent of the workspaces in view, and their terminals in the browser.
   running, and opening it again replays what you missed. **Stop** (an
   agent only) is `agents stop`, behind the lock. **+ 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. While the lock is closed, the dialog asks
+  for the admin password at its top, and Start unlocks, then starts, without
+  closing anything.
 - ⌘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
@@ -1714,7 +1774,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;
@@ -1761,19 +1822,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
@@ -1822,8 +1886,9 @@ are errors naming the file or the key.
 
 `<cli> doctor` lists the runtime kind. Two are built in:
 
-- **`den-claude`** (the default) needs `claude` on PATH; doctor reads its
-  version from the install, without running it. It runs `claude --session-id
+- **`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
@@ -1836,6 +1901,64 @@ are errors naming the file or the key.
   `{mcp_config}` is the path of the agent's MCP config, written only when the
   template references it. It declares no resume.
 
+**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
+   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
+   ```
+
+2. **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.
+
+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, 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
+--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.
+
+```
+den-claude (Claude Code)  [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` 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.
+
 ### Workspace scope and grants
 
 An agent's MCP config, `<stateDir>/agent-files/<id>/mcp.json` (0600), runs

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.3",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/shared/agents/den-claude.ts

@@ -28,27 +28,50 @@
  *   session Den starts (an agent is not a child of the session that
  *   started it).
  *
- * detect runs nothing: `claude` on PATH, and its version read from where it
- * is installed (a native install's versions/<version>, or the npm package's
- * package.json).
+ * detect runs nothing (AG-0.1, runtime-search.ts): agents.runtimes.den-claude.bin
+ * in user.yml when set, else `claude` on the login shell's PATH, the
+ * caller's PATH, then its install directories (~/.local/bin, the native
+ * installer's; ~/.claude/local; /opt/homebrew/bin; /usr/local/bin; npm's
+ * global bin). Its version is read from where it is installed (a native
+ * install's versions/<version>, or the npm package's package.json); the
+ * Start dialog and `agents doctor` ask `claude --version` once as well.
  */
 import { randomUUID } from "crypto";
 import * as fs from "fs";
 import * as path from "path";
+import { configuredRuntimeBin } from "../den-config.js";
 import { rolePrompt } from "./personas.js";
 import {
   LaunchError,
   mcpConfigJson,
   mcpConfigPath,
-  whichBin,
+  type DetectOptions,
   type LaunchInput,
   type LaunchOutput,
   type Runtime,
   type RuntimeDetect,
 } from "./runtime.js";
+import {
+  locateRuntime,
+  systemBinDirs,
+  type RuntimeFind,
+} from "./runtime-search.js";
 
 export const DEN_CLAUDE_ID = "den-claude";
 const BIN = "claude";
+
+/** Where Claude Code is found, and how its version is asked. */
+export const DEN_CLAUDE_FIND: RuntimeFind = {
+  bins: [BIN],
+  dirs: (home, env) => [
+    // The native installer's, then the older local install's.
+    ...(home
+      ? [path.join(home, ".local", "bin"), path.join(home, ".claude", "local")]
+      : []),
+    ...systemBinDirs(env),
+  ],
+  versionArgs: ["--version"],
+};
 const PACKAGE = "@anthropic-ai/claude-code";
 const SEMVER = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 
@@ -97,11 +120,29 @@ export function installedVersion(bin: string): string | undefined {
   return undefined;
 }
 
-function detect(env: NodeJS.ProcessEnv = process.env): RuntimeDetect {
-  const bin = whichBin(BIN, env);
-  if (!bin) return { available: false, why: `${BIN} is not on PATH` };
-  const version = installedVersion(bin);
-  return version ? { available: true, version } : { available: true };
+function detect(
+  env: NodeJS.ProcessEnv = process.env,
+  opts: DetectOptions = {},
+): RuntimeDetect {
+  const setting =
+    opts.bin === undefined ? configuredRuntimeBin(DEN_CLAUDE_ID) : opts.bin;
+  const found = locateRuntime(DEN_CLAUDE_ID, DEN_CLAUDE_FIND, env, setting);
+  if (!found.available || !found.path)
+    return {
+      available: false,
+      why: found.why ?? `${BIN} not found`,
+      // "setting": a bad agents.runtimes.<id>.bin is the reason, not the search.
+      ...(found.source ? { source: found.source } : {}),
+      searched: found.searched,
+    };
+  const version = installedVersion(found.path);
+  return {
+    available: true,
+    ...(version ? { version } : {}),
+    path: found.path,
+    ...(found.source ? { source: found.source } : {}),
+    searched: found.searched,
+  };
 }
 
 /**
@@ -231,13 +272,17 @@ function common(input: LaunchInput): {
 }
 
 function binFor(input: LaunchInput): string {
-  const bin = whichBin(BIN, input.env);
-  if (!bin) throw new LaunchError(`${DEN_CLAUDE_ID}: ${BIN} is not on PATH`);
-  return bin;
+  if (input.bin) return input.bin;
+  const d = detect(input.env);
+  if (!d.available || !d.path)
+    throw new LaunchError(`${DEN_CLAUDE_ID}: ${d.why ?? `${BIN} not found`}`);
+  return d.path;
 }
 
 export const denClaude: Runtime = {
   id: DEN_CLAUDE_ID,
+  label: "Claude Code",
+  find: DEN_CLAUDE_FIND,
   detect,
   launch(input): LaunchOutput {
     const bin = binFor(input);

package/src/shared/agents/generic.ts

@@ -20,6 +20,7 @@ export const GENERIC_ID = "generic";
 
 export const generic: Runtime = {
   id: GENERIC_ID,
+  label: "Generic command",
   // The CLI is the persona's; there is nothing to look for until launch.
   detect: () => ({ available: true }),
   scrubEnv: [],