@monster-orange/den 0.4.14 → 0.4.15

package/CHANGELOG.md

@@ -4,6 +4,133 @@ 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.15] - 2026-11-07
+
+### Added
+
+- **Onboarding reads for agents, the CLI and the browser (ON-3).** Three new
+  MCP read tools, always registered, each with a CLI twin and a web API
+  route (GET, a read in the route table) that a page can show as it is:
+  - `onboard_status`, `<cli> onboard status [--json]`,
+    `/api/onboard/status`: what's set up (a distribution, Node, git, Docker,
+    the web server, workspaces, repos, a running service, Den's MCP), each
+    `ok`, `warn` or `todo`, and the one next step in plain words with its
+    command. It never runs an agent's CLI to check Den's MCP.
+  - `repos_detect`, `<cli> repo detect <folder> [--json]`,
+    `/api/onboard/repos`: the git repos in a folder, one or two levels down,
+    how each one runs (the same detection as `repo add`), and suggested
+    workspaces (the repos in one parent folder go in one workspace named
+    after it). It never writes, runs a repo's tools or follows a symlink,
+    skips dot-folders, `node_modules` and `vendor`, and stops at 50 repos.
+  - `manifest_draft`, `<cli> repo add <path> --dry-run --json`,
+    `/api/onboard/manifest`: the side-car manifest `repo add` would write,
+    checked by the same validator, with nothing written. Several ways to
+    start the repo is a question with its choices, as `repo add` asks.
+- A path for `repos_detect` or `manifest_draft` must be a folder inside the
+  person's home folder and outside Den's state folder; anything else is
+  refused with the reason. A workspace-scoped MCP server can't scan folders,
+  and drafts only inside its workspace's repos.
+- **Onboarding writes, held for the person (ON-3).** Three new MCP write
+  tools, `workspace_create`, `repo_add` and `service_try`, on by default
+  and gated by the person's Allow (not by `mcp.actions`). They change
+  nothing by themselves: each asks Den to hold the change, and every Den page opens a
+  dialog in the person's browser, "The `<agent>` agent wants to: … ·
+  Review · Later · Deny · Allow". Den writes the line and the Review from
+  the action and its arguments (`repo_add`'s Review is its dry run); the
+  agent's note is only quoted. Allow runs it once, from the stored
+  arguments checked again, through the code paths the pages and the CLI
+  use (the Workspaces page's create, `repo add --json`, `up` as the
+  Services page starts it). Deny, 10 minutes with no answer, or the agent
+  being stopped run nothing. The agent waits up to 2 minutes, then
+  `approval_check` reads where its request stands; meanwhile it is
+  "waiting" on the Agents page. Routes: `POST /api/approvals`,
+  `GET /api/approvals`, `GET /api/approvals/<id>`,
+  `POST /api/approvals/<id>/decide`. See [Onboarding writes, held for the
+  person](docs/distributions.md#onboarding-writes-held-for-the-person).
+- **`mcp.approvals: false`** in the distribution config turns the three
+  held writes off: they aren't registered, and `POST /api/approvals`
+  answers 403 `approvals_off`. `doctor` (its `mcp:approvals` check in
+  `--json`), the MCP server's instructions and `mcp --list` (on stderr) say
+  which is in effect. A value that isn't `true` or `false` is an error.
+- **Who asked.** An agent's token shows its name ("The `<agent>` agent
+  wants to:"). A request with no agent identity reads "Something on this
+  machine (no agent identity) wants to:", with "If you didn't ask an agent
+  to do this, Deny." under it. In English, Spanish and Japanese.
+- **Only the person approves.** Allow and Deny need a browser signed in on
+  this Den and holding its approval key, even on localhost. Every sign-in
+  mints the key, handed over only in the sign-in's own answer (a 303's
+  `#ak=` fragment, or the sign-in poll); the session keeps its hash and
+  `GET /api/session` never returns it. A cookie alone (any localhost port
+  receives it), the CLI's bearer, an agent's token or an anonymous request
+  from this machine is refused with `signin_to_approve`.
+- **Only the person sees what waits.** `GET /api/approvals` needs what
+  Allow needs: the cookie, that session's CSRF token and the approval key.
+  Anything else gets 403 `signin_to_approve` with a count (`waiting`), and
+  a signed-out page shows a banner to sign in. An agent's token lists only
+  its own requests and their outcomes. An ask with no agent token gets a
+  ticket that reads that one request (`X-Den-Approval-Ticket`); Den's MCP
+  server keeps it and never shows it to the agent.
+- **The setup link.** `<cli> web claim-link [--json]` prints a one-time
+  link (`/auth?claim=<code>`, 30 minutes) that signs this browser in, for
+  an install that hands the person over to the browser. Opened twice, it
+  says it was used and that someone else may have opened it.
+
+### Changed
+
+- Pairing a device, approving one, and linking or unlinking the GitHub
+  owner (`POST /api/web/pair`, `/api/web/approve`, `/api/web/owner/link`,
+  `/api/web/owner/unlink`) need the person: the CLI's bearer, or a
+  signed-in browser holding its approval key. On plain localhost,
+  Settings › Access asks you to sign in before pairing.
+- Inside an agent's session (`DEN_AGENT` or `DEN_ACTOR_TOKEN` set), the CLI
+  refuses every command that lets a browser in: `web login`, `web approve`,
+  `web owner link|unlink`, `web claim-link`; `web open` opens the plain
+  page.
+- What a test run writes and Den serves (`/report/*`, the Playwright
+  report, and `/reports/security/*`) is served sandboxed (an opaque
+  origin, no scripts reaching Den's), with nosniff, no-store and
+  no-referrer.
+- A workspace name is at most 64 characters.
+- **A Name is the agent's id (AG-10.10b).** A Name given at start (the
+  dialog's Name, the API's `name`, the CLI's new `--name`) makes the id its
+  slug: "API spike" starts `api-spike`, titled "API spike". The dialog says
+  so as you type. A Name that matches a running agent in the workspace, by
+  id or by title, is refused: the dialog says "api-spike is already
+  running · Open it" and Start is off. A stopped one offers Resume it, or
+  Start makes `api-spike-2`. No two live agents in a workspace share a
+  title. With no Name the persona's id stays the default; `--id` is exact.
+- The Den theme's light mode (2.0.1): `--ok`, `--warn`, `--bad`,
+  `--remote` and `--accent-text` are darker, so a status pill (the token
+  on a tint of itself) meets WCAG AA (4.5:1) on every surface, `--sunken`
+  included. They measured 3.7 to 4.4:1 there. Dark mode is unchanged.
+
+### Fixed
+
+- The signed-out page's Open Terminal link was `ssh://<host>` with no
+  account, so an SSH app filled in its own default (an iPad's asked for
+  `user@…`'s password). The link and the ssh one-liner are now
+  `<user>@<host>`, the account Den runs as, and the note says "Log in with
+  your <machine> account (<user>) and its password, or an SSH key."
+  `web.ssh_user` names another account; `web.ssh_user: ""` leaves it off.
+- Text dimmed with opacity fell under WCAG AA on the light theme. Not
+  installed editors and terminals in Settings (3.1:1, their "not found"
+  2.2:1), a repo already in the workspace in Add service (1.9:1), the
+  Release table's loading sub-line (3.7:1), and a primary button on hover
+  (4.4:1). They are full-strength now, in `--muted`; hover darkens.
+- `/reports/security/*` was always 404: the `/report` prefix shadowed it.
+- Bring in on a shared repos root (the usual layout) listed every
+  conversation under the root, so workspaces showed the same 50 and their
+  own were crowded out. A conversation is a workspace's when it ran in one
+  of its repos' folders or inside one, in its own folder, or exactly at a
+  shared root; the 50 cap applies after that. Another workspace's
+  conversation is refused by id: "This conversation belongs to <folder>,
+  not to workspace <ws>" (CLI, API and MCP).
+
+### Migrations
+
+None. Sessions signed in before 0.4.15 hold no approval key: sign in again
+to approve or to pair a device.
+
 ## [0.4.14] - 2026-11-07
 
 ### Added

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.14/hero-dark.png">
-  <img src="docs/images/0.4.14/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.15/hero-dark.png">
+  <img src="docs/images/0.4.15/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>
 
 ## Set up by your agent
@@ -38,7 +38,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.14/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.15/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
@@ -68,10 +68,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.14/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.14/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.14/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.14/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.15/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.15/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.15/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.15/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

@@ -83,6 +83,9 @@ question for the person (`ask`, sometimes with `choices`).
 | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `npx @monster-orange/den create <name> [dir] --yes --json` | `{ ok, dir, cli, existed, files, port, portPicked?, next }`                  |
 | `<cli> repo add <path\|git-url> --json`                    | `{ ok, existed, repo, workspace, mode, path, manifest, services, next }`     |
+| `<cli> repo detect <folder> --json`                        | `{ ok, path, repos, workspaces, truncated, skipped, rule, next }`            |
+| `<cli> repo add <path> --dry-run --json`                   | `{ ok, dryRun, repo, workspace, path, manifest, draft, validation, next }`   |
+| `<cli> onboard status --json`                              | `{ ok, checks: [{ id, status, detail, fix?, ask? }], next }`                 |
 | `<cli> up <repo> --json`                                   | `{ ok, workspace, services: [{ address, result, health, detail? }], next }`  |
 | `<cli> web up --no-open --json`                            | `{ ok, url, port, version? }`                                                |
 | `<cli> doctor --json`                                      | `{ ok, checks: [{ id, status, detail, url?, port?, fix?, ask? }] }`          |
@@ -121,6 +124,115 @@ question for the person (`ask`, sometimes with `choices`).
   else the focused one, else a new `default` workspace.
 - The same repo again answers `ok` with `existed: true`. A different repo
   under the same name is an error that offers `relocate` or `--name`.
+- `--dry-run` (a local path only) runs the same detection and validator and
+  writes nothing: no side-car, no workspace entry, no catalog entry. The
+  answer carries the side-car as YAML (`draft`), the validator's answer
+  (`validation`), where it would go (`manifest.file`, `written: false`) and,
+  in `next`, the same command without `--dry-run`. A git URL is refused: it
+  would have to be cloned first.
+
+### Onboarding reads
+
+Three reads help a person, or an agent, finish setting Den up. Each one is
+a CLI command, an MCP read tool and a web API route, with the same answer
+(the browser can show the route's JSON as it is):
+
+| CLI                                      | MCP tool         | Web API (GET)           |
+| ---------------------------------------- | ---------------- | ----------------------- |
+| `<cli> onboard status [--json]`          | `onboard_status` | `/api/onboard/status`   |
+| `<cli> repo detect <folder> [--json]`    | `repos_detect`   | `/api/onboard/repos`    |
+| `<cli> repo add <path> --dry-run --json` | `manifest_draft` | `/api/onboard/manifest` |
+
+- **`onboard status`** says what's set up and the one next step. `checks`
+  are, in order: `distribution` (this folder has its own `bin/<cli>`),
+  `node`, `git`, `docker` and `web` (the same probes as `doctor --json`),
+  `workspaces` (how many, and the active ones), `repos` (how many are
+  added), `service` (how many services Den started are running) and `mcp`.
+  Each is `ok`, `warn` or `todo`, with a `fix` command or an `ask` for the
+  person when there is one. `next` is `{ id, step, command }`: the step in
+  plain words and the command for it, or `id: "done"` when everything is
+  set up. `mcp` never runs an agent's CLI: it is `ok` when the question
+  came through Den's MCP, or when a client's config file names this
+  distribution's server; with only Claude Code or Codex installed (they
+  keep their list behind their own CLI) it is a `warn` pointing at
+  `<cli> mcp clients`. It exits 0 whenever it answers.
+- **`repo detect <folder>`** finds the git repos in one folder: the folder
+  itself when it is a repo, else its subfolders one and two levels down (a
+  repo's own subfolders are not scanned). For each repo: `manifest` (`repo`,
+  `sidecar` or `none`), `runs` (what [`repo add`](#repo-add) would detect)
+  or `ask` and `choices`, the suggested `workspace`, and `registered` when
+  it is already in one. `workspaces` groups them by one simple rule: the
+  repos in one parent folder go in one workspace named after that folder,
+  and a repo directly in the scanned folder gets the scanned folder's name.
+  It skips dot-folders, `node_modules` and `vendor`, never follows a
+  symlink, stops at 50 repos or 5,000 folder entries (`truncated: true`),
+  and never writes or runs a repo's tools.
+- **`repo add --dry-run`** is the draft: see [`repo add`](#repo-add).
+- **The path rule** (`repos_detect`, `manifest_draft` and both routes): a
+  path is required, absolute or starting with `~/`. It is resolved with its
+  symlinks, and must be a folder inside the person's home folder and outside
+  Den's own state folder; anything else is refused with the reason (a 400
+  from the route, `Refused:` from the tool, exit 1 from the CLI).
+
+### Onboarding writes, held for the person
+
+An agent finishes setup with three MCP write tools. None of them changes
+anything by itself: each asks Den to hold the change, and the person's
+browser opens a dialog on whatever Den page is open: "The `<agent>` agent
+wants to: … · Review · Later · Deny · Allow". A request with no agent
+token (an MCP server outside an agent's session, or anything else on this
+machine) reads "Something on this machine (no agent identity) wants to:",
+with "If you didn't ask an agent to do this, Deny." under it.
+
+| MCP tool           | What Allow runs                                         |
+| ------------------ | ------------------------------------------------------- |
+| `workspace_create` | The Workspaces page's create: an empty workspace        |
+| `repo_add`         | `repo add <path> --json`, a local folder inside home    |
+| `service_try`      | `up` for one service, as the Services page's Start does |
+
+- **Den writes the dialog.** Its line and its Review come from the action
+  and its arguments, never from the agent. `repo_add`'s Review is its dry
+  run: the folder, the workspace (new or not) and the side-car Den would
+  write. The agent's `note` is shown only quoted, as "Agent says".
+- **Bad arguments are refused before anything waits**: the same checks as
+  the page, `repo add` and the path rule of
+  [Onboarding reads](#onboarding-reads).
+- **Only the person approves.** Allow and Deny need a browser signed in on
+  this Den holding its approval key: a session cookie alone, the CLI's
+  bearer, an agent's token, or an anonymous request from this machine (an
+  agent with a shell) is refused with `signin_to_approve`. On a fresh Den,
+  `<cli> web claim-link` prints a one-time setup link that signs the
+  browser in.
+- **Allow runs it once**, from the arguments stored when it was asked,
+  checked again first. Deny, 10 minutes with no answer, or the agent being
+  stopped run nothing. An agent may have 5 requests waiting; a restart drops
+  what waits (the agent asks again).
+- **The agent waits** up to 2 minutes for the answer, then gets the request
+  id: `approval_check` says `pending`, `done` (with what the run said),
+  `denied` or `expired`. While a request waits, its agent is "waiting" on
+  the Agents page.
+- **Only the person sees what waits.** `GET /api/approvals` needs what
+  Allow needs: the session cookie, that session's CSRF token
+  (`X-Den-CSRF`) and the approval key. Anything else gets 403
+  `signin_to_approve` with only `waiting`, a count, so a signed-out page
+  can show "Something is waiting for your approval. Sign in to see it."
+  An agent's token lists its own requests and their outcomes (`mine`),
+  never another agent's. An ask with no agent token gets a `ticket` in the
+  reply; `X-Den-Approval-Ticket: <ticket>` reads that one request and no
+  other. Den's MCP server keeps it and never shows it to the agent.
+- **Routes:** `POST /api/approvals` (`{ action, args, note? }`, 202 with the
+  request), `GET /api/approvals` (the person's: what waits; an agent's
+  token: its own), `GET /api/approvals/<id>` (the asking agent's own, the
+  ticket holder's, or the person's) and
+  `POST /api/approvals/<id>/decide` (`{ decision: "allow" | "deny" }`).
+  Every ask and decision is in the activity trail.
+- **On by default; `mcp.approvals: false` turns them off.** The person's
+  Allow is the gate, not `mcp.actions`. Off, the three tools aren't
+  registered and `POST /api/approvals` answers 403 `approvals_off`.
+  `doctor` (and its `mcp:approvals` check in `--json`), the MCP server's
+  instructions and `mcp --list` (on stderr) say which is in effect. A
+  workspace-scoped MCP server refuses `workspace_create` and `repo_add`:
+  they change Den beyond its workspace.
 
 ### up, doctor and mcp connect
 
@@ -1434,6 +1546,15 @@ user, and the CLI does that for you:
   host name (up to the first dot). It is never taken from the browser's
   Host. The ssh one-liner's target is the Host the browser used, without
   the port (the machine's host name if it had none).
+- **The ssh account.** The ssh one-liner and the Open Terminal link log in
+  as `<user>@<host>`, where user is the account the Den server runs as, so
+  an SSH app doesn't fill in its own default. The note under the button
+  says "Log in with your <machine> account (<user>) and its password, or
+  an SSH key." `web.ssh_user` names another account (`config/local/user.yml`,
+  else the distribution's `config/den.yml`; read at once). `web.ssh_user:
+""` leaves the account off, for a distribution that doesn't want it on a
+  page anyone on the network can see. It takes letters, digits, `.`, `_`
+  and `-`; anything else is refused at start, naming the key.
 - **Codes.** About 30 bits (Crockford base32: no I, L, O or U; typed in any
   case, the dash optional); the page polls with a separate 128-bit id. A
   code expires after 10 minutes and works once; at most five wait at once
@@ -1785,13 +1906,17 @@ to one workspace for one agent:
   (`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>`.
+  take only `<ws>`'s services, `manifest_validate` and `manifest_draft` take
+  only an absolute path inside one of its repos (or, for `manifest_validate`,
+  the content), and `workspace_sync` syncs `<ws>`. `repos_detect` is refused:
+  scanning folders reaches outside any workspace, so onboarding is for the
+  unscoped server.
   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`, `edge_status` and `org_summary` (the
-  org's and the distribution's, not a workspace's).
+  `security_latest`, `release_status`, `edge_status`, `onboard_status` (counts
+  and checks only) 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
@@ -1857,10 +1982,12 @@ mcp:
     envs: [local] # the default; production is refused even if listed
   logs:
     remote: false # the default; true lets the log tools read non-local sources
+  approvals: true # the default: the held writes, each run on the person's Allow
 ```
 
 An unknown action or environment name is an error, so a typo never turns a
-guard off.
+guard off; so is an `approvals` that isn't `true` or `false`. See
+[Onboarding writes, held for the person](#onboarding-writes-held-for-the-person).
 
 ### Tools
 
@@ -1883,6 +2010,9 @@ Read tools (always registered):
 | `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                                                                                                                                          |
+| `onboard_status`    | `/api/onboard/status`                      | What's set up and the one next step: `checks` (`ok`, `warn`, `todo`) and `next` (`step`, `command`); see [Onboarding reads](#onboarding-reads)                                                                                                                                 |
+| `repos_detect`      | `/api/onboard/repos`                       | The git repos in `path` (one or two levels down), how each runs, and suggested `workspaces`; never writes or follows a symlink; refused on a scoped server                                                                                                                     |
+| `manifest_draft`    | `/api/onboard/manifest`                    | The side-car `repo add` would write for `path`, validated (`draft`, `validation`), nothing written; `ask` and `choices` when it can start in several ways (call again with `run`)                                                                                              |
 
 **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`
@@ -2045,7 +2175,7 @@ An agent is a **persona** (who) in a **workspace** (where), run by a
 server scoped to its workspace.
 
 ```
-<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--id <id>]
+<cli> agents start -w <ws> --persona <p> [--runtime <r>] [--model <m>] [--name <name>] [--id <id>]
 <cli> agents list -w <ws> [--json]
 <cli> agents stop <id> [-w <ws>]
 <cli> agents resume <id> [-w <ws>]
@@ -2065,6 +2195,9 @@ server scoped to its workspace.
   agent there, running or stopped, starts another: `planner-2`,
   `planner-3`. A stopped agent is continued by Resume or Start fresh,
   never by a new start. `--id` is exact: a running id is refused.
+  `--name "API spike"` makes the id its slug, `api-spike`, titled as
+  typed; a running agent there with that id or title is refused, and a
+  stopped one makes it `api-spike-2`.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
   persona, runtime, model, workspace, cwd, session and times, and what it was
   started with from the Start dialog: `version` (the model's, "latest" or
@@ -2100,8 +2233,11 @@ server scoped to its workspace.
 #### Bring in a conversation
 
 A conversation you started in a terminal outside Den (Claude Code, in the
-workspace's folder, a folder inside it, or a folder of one of its repos,
-a repo added by path outside it too) can become a Den agent. Agents ›
+workspace's own folder or one inside it, or a folder of one of its repos,
+a repo added by path outside it too) can become a Den agent. When
+workspaces share one repos root, only each one's repos' folders count,
+and the root itself only exactly; another workspace's conversation is
+refused by id. Agents ›
 **Bring in** lists them, newest first, with the persona list; `agents
 import -w <ws>` lists them too.
 

package/package.json

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

package/src/shared/actor-token.ts

@@ -199,6 +199,18 @@ export function revokedAgentIds(stateDir: string): Set<string> {
   return out;
 }
 
+/**
+ * Whether agent `agentId` holds a token that isn't revoked: stopping it
+ * deletes its tokens, `web logout --all` marks them revoked (ON-3: a held
+ * write of an agent that is gone never runs).
+ */
+export function agentTokenLive(stateDir: string, agentId: string): boolean {
+  const actor = `agent:${agentId}`;
+  return Object.values(load(stateDir).tokens).some(
+    (r) => r.actor === actor && !r.revokedAt,
+  );
+}
+
 /** What a presented token was minted as, live or not; null when unknown. */
 export function lookupActorToken(
   stateDir: string,

package/src/shared/agents/conversations.ts

@@ -159,13 +159,25 @@ function forms(dir: string): string[] {
  * newest first, at most MAX_CONVERSATIONS. Never throws: a history it
  * can't read is no conversations.
  */
+/**
+ * Where a workspace's conversations ran (AG-17.1): in or under one of
+ * `under`, or exactly in one of `exact` (a shared repos root: its other
+ * subfolders are other workspaces' or no repo's).
+ */
+export interface ConversationScope {
+  under: string[];
+  exact?: string[];
+}
+
 export function claudeConversations(
-  folder: string,
+  scope: string | ConversationScope,
   env: NodeJS.ProcessEnv = process.env,
 ): RuntimeConversation[] {
+  const sc = typeof scope === "string" ? { under: [scope] } : scope;
   const root = claudeProjectsDir(env);
-  const dirs = forms(folder);
-  const slugs = dirs.map(claudeSlug);
+  const dirs = sc.under.flatMap(forms);
+  const exact = (sc.exact ?? []).flatMap(forms);
+  const slugs = [...dirs, ...exact].map(claudeSlug);
   let projects: string[];
   try {
     projects = fs.readdirSync(root);
@@ -208,7 +220,16 @@ export function claudeConversations(
       continue;
     }
     const cwd = s.cwd;
-    if (!cwd || !dirs.some((d) => within(cwd, d))) continue;
+    // Filtered before the cap, so others' conversations never crowd out
+    // this workspace's.
+    if (
+      !cwd ||
+      !(
+        dirs.some((d) => within(cwd, d)) ||
+        exact.some((d) => path.resolve(cwd) === d)
+      )
+    )
+      continue;
     seen.add(f.id);
     out.push({
       id: f.id,
@@ -220,6 +241,14 @@ export function claudeConversations(
   return out;
 }
 
+/** Whether a conversation that ran in `cwd` is in `scope` (AG-17.1). */
+export function inScope(cwd: string, scope: ConversationScope): boolean {
+  return (
+    scope.under.flatMap(forms).some((d) => within(cwd, d)) ||
+    (scope.exact ?? []).flatMap(forms).some((d) => path.resolve(cwd) === d)
+  );
+}
+
 /** Whether a conversation last written at `lastAt` is still open elsewhere. */
 export function openElsewhere(lastAt: string, now = Date.now()): boolean {
   const t = Date.parse(lastAt);

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

@@ -70,7 +70,7 @@ import { catalogFind } from "./catalog-runtime.js";
 import { locateRuntime, type RuntimeFind } from "./runtime-search.js";
 import { claudeProjectsDir } from "../usage/paths.js";
 import { cleanName, transcriptTitle } from "./transcript-follow.js";
-import { claudeConversations } from "./conversations.js";
+import { claudeConversations, transcriptSummary } from "./conversations.js";
 
 /**
  * `/rename "x"` keeps the quotes in customTitle: one matching pair around
@@ -490,13 +490,23 @@ export const denClaude: Runtime = {
     return transcriptFile(token, env) !== null;
   },
   // AG-17.1: its transcripts for the folder (conversations.ts).
-  listSessions(cwd, env = process.env) {
+  listSessions(scope, env = process.env) {
     try {
-      return claudeConversations(cwd, env);
+      return claudeConversations(scope, env);
     } catch {
       return [];
     }
   },
+  // AG-17.1: the folder a conversation ran in (only the ends of its file),
+  // so a foreign one is refused by name.
+  conversationCwd(token, env = process.env) {
+    try {
+      const file = transcriptFile(token, env);
+      return file ? transcriptSummary(file).cwd : null;
+    } catch {
+      return null;
+    }
+  },
   // AG-4b, unofficial (catalog sessionName): `/rename` appends a
   // {"type":"custom-title","customTitle":…} record to the transcript; the
   // latest one, read on from the last ask (never the whole file), less one

package/src/shared/agents/records.ts

@@ -166,6 +166,24 @@ export interface AgentUsage {
 /** An agent id: the same rules as a workspace or session name. */
 export const AGENT_ID_RE = WORKSPACE_NAME_RE;
 
+/**
+ * AG-10.10b: the agent id a Name gives, so the name works in the CLI too:
+ * lowercase, spaces to "-", only id characters, at most 64. Null when
+ * nothing of it is left ("!!!"). The page's nameSlug is the same rule.
+ */
+export function nameSlug(name: string): string | null {
+  const s = name
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, "-")
+    .replace(/[^a-z0-9._-]/g, "")
+    .replace(/-{2,}/g, "-")
+    .replace(/^[^a-z0-9]+/, "")
+    .slice(0, 64)
+    .replace(/[-._]+$/, "");
+  return s && AGENT_ID_RE.test(s) ? s : null;
+}
+
 export function agentsDir(stateDir: string): string {
   return path.join(stateDir, "agents");
 }

package/src/shared/agents/runtime.ts

@@ -201,7 +201,12 @@ export interface Runtime {
    * transcript). Each id is one `resume` continues. None: this runtime
    * can't bring one in yet. Must never throw.
    */
-  listSessions?(cwd: string, env?: NodeJS.ProcessEnv): RuntimeConversation[];
+  listSessions?(
+    scope: string | { under: string[]; exact?: string[] },
+    env?: NodeJS.ProcessEnv,
+  ): RuntimeConversation[];
+  /** AG-17.1: the folder conversation `token` ran in, or null. Never throws. */
+  conversationCwd?(token: string, env?: NodeJS.ProcessEnv): string | null;
   /**
    * What the runtime prints when it exits at once (0.4.8): `noConversation`
    * when a resume finds nothing to continue, `idInUse` when a new