@monster-orange/den 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -4,6 +4,99 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.3] - 2026-11-06
+
+Agents start, and the edge counts as local.
+
+### Fixed
+
+- **The Start agent dialog can be submitted (AG-10.0).** A persona's whole
+  role sentence was in its option, so the select grew past the dialog and
+  pushed Cancel and Start out of sight. A persona option now shows its id,
+  with its role on a help line under the select that follows the pick. The
+  runtime's first option names what it resolves to ("Claude Code (persona
+  default)"), a runtime that can't run here says why, and Enter starts
+  from any field. The Workspaces page's agents form gets the same choices.
+
+- **Agents start on a Den run as a service (AG-0.1).** Starting any agent
+  failed with "den-claude is unavailable: claude is not on PATH" when the
+  web server ran under launchd: its PATH leaves out `~/.local/bin`, where
+  Claude Code's native installer puts `claude`, and Den searched only that
+  PATH. Den now finds a runtime's CLI as your terminal would:
+  `agents.runtimes.<id>.bin` in `config/local/user.yml` wins (an absolute
+  path, checked; a bad one is refused with its reason), then the login
+  shell's PATH (`$SHELL -lc`, asked once at server start in the
+  background, 3-second timeout, falling back to the current PATH), the
+  server's PATH, and the runtime's install directories (`~/.local/bin`,
+  `~/.claude/local`, `/opt/homebrew/bin`, `/usr/local/bin`, npm's global
+  bin). Agents and plain sessions get the same directories on their PATH.
+- **The lock is always reachable (LK-1 to LK-3).** Start agent opened its
+  dialog and only then asked for the lock, whose popover sat under the
+  dialog where nothing could reach it. The lock is now checked before the
+  dialog opens, and the dialog asks for the admin password at its top:
+  Start unlocks, then starts. The lock popover is in the top layer, so no
+  dialog covers it. A page that thinks it's locked asks the server before
+  asking you (another tab or device may have unlocked it), and, when a
+  password is stored in the vault, the first action that needs the lock
+  loads it from there on every page, not only Local Dev. A page view still
+  never wakes the vault.
+
+### Changed
+
+- **The edge from this machine needs no sign-in.** A request for the edge
+  hostname from an edge peer is treated as loopback: no sign-in on any
+  route, agents and the terminal included (0.4.2 asked for one on every
+  route). Host, Origin, CSRF and the agent-token rules stay. The client is
+  the left-most `X-Forwarded-For` entry: loopback or one of this machine's
+  own interface addresses (a Tailscale `100.x` included) is local; missing,
+  or a Docker/VM network's address (what Docker Desktop and OrbStack hand
+  the edge; the subnets of the edge's own Docker networks, `<org>-edge`
+  and those it joins, read once at start with `docker network inspect`;
+  OrbStack's host address `0.250.250.254`), is "can't tell", also local, so
+  a TCP-passthrough proxy container on the edge's network is no other
+  machine; any other address is another
+  machine and needs a sign-in. A non-loopback `DEN_BIND_HOST` bind (other
+  than the Linux edge's Docker bridge) and `web.allow_plain_http_remote`'s
+  LAN names still need one. See docs/distributions.md, "Signing in".
+
+### Added
+
+- **The Start dialog says before Start whether the agent can run
+  (AG-0.2).** Under the runtime a line names what Start will run, with its
+  version and path ("Starts Claude Code 2.1.0 from …"); the runtime's
+  option shows its version. When the runtime can't run here, Start is
+  disabled and the line says why and how to fix it: where Den looked, then
+  install it, or set `agents.runtimes.<id>.bin` in the user.yml it names,
+  or run `<cli> agents doctor`. The Workspaces page's agents form does the
+  same. `GET /api/personas` gives each runtime `version` (its version
+  command, run once under a timeout and kept), `path`, `source`
+  (`setting`, `login-shell`, `well-known` or `PATH`), `searched` and
+  `setting`, and the response a `userConfig` path.
+- **`<cli> agents doctor [--json]` (AG-0.3)**: each runtime's status, the
+  CLI it runs and where it came from, its version, the directories
+  searched (names only, never an environment value), and the fix when it
+  is missing. It exits 1 when the default runtime is unavailable.
+
+- **"Your edge is reachable from other machines".** When an edge hostname
+  resolves to an address that isn't loopback, or the edge container
+  publishes a port on every interface (`docker inspect`), Den says so once
+  in `web.log` at start and in a banner on every page (dismissed per
+  browser): "Your edge is reachable from other machines; anyone who can
+  reach it can use terminals. Auth is coming."
+- **`<cli> web login --host <name>`** mints the one-time link for an edge
+  hostname (an edge domain or alias, a VPN name among them) at its edge
+  URL, instead of localhost. A name the edge doesn't route to this server
+  is refused, naming the hostnames it does and what to add. `--origin`
+  stays.
+
+### Migrations
+
+- **A Den run as a service whose agents' CLI is somewhere unusual**: set
+  `agents.runtimes.<id>.bin` (an absolute path) in `config/local/user.yml`.
+  Nothing else changes: a runtime on the server's PATH is found as before.
+- **A page script that called `requireUnlock()`** (header.js): it now
+  returns a promise of the answer; `await` it.
+
 ## [0.4.2] - 2026-11-06
 
 The 0.4.1 carry-overs.
@@ -43,6 +136,7 @@ The 0.4.1 carry-overs.
   that…"); there are two spaces now. `down`, `restart` and `setup --help`
   were already spaced.
 
+
 ### Migrations
 
 - **More than 4 plain sessions at once**, or a script that relied on

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.1/hero-dark.png">
-  <img src="docs/images/0.4.1/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.3/hero-dark.png">
+  <img src="docs/images/0.4.3/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## What Den is
@@ -24,7 +24,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.1/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.3/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -53,10 +53,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.1/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.1/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.1/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.1/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.3/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.3/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.3/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.3/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

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
@@ -1616,6 +1658,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> sessions attach <ws>:<id>         # its terminal; ctrl-] detaches
 ```
 
@@ -1654,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.
@@ -1695,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
@@ -1721,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;
@@ -1832,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
@@ -1846,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.2",
+  "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: [],