@monster-orange/den 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -4,6 +4,231 @@ 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.2.8] - 2026-11-05
+
+### Added
+
+- **A scoped MCP server for cooperating agents** (0.2.8-dev.0, AG-2a-core).
+  `<cli> mcp --workspace <ws> --actor agent:<id>` pins one workspace: a tool
+  that takes a workspace gets `<ws>`, and a call naming another is refused
+  before it reaches the web server and recorded in the activity trail.
+  Lists are filtered to `<ws>`: `workspaces` shows it alone, the log tools
+  and `manifest_validate` take only its services and repos, `workspace_sync`
+  syncs it, and the test tools need it to be the focused workspace. Every
+  web API call is stamped with the actor (`x-den-mcp-agent`,
+  `x-den-mcp-workspace`), so each exec, run and sync in the activity trail
+  and the server log names `agent:<id>` and its workspace. Both flags or
+  neither; a bad value is a usage error (exit 2). `--list` and `--call` take
+  them too. Without them the server is unchanged. **Limit:** it binds
+  cooperating agents only. The scope lives in the MCP process, and the web
+  server's HTTP API does not check it yet (WS-3a, 0.4); `mcp connect` still
+  registers the unscoped server.
+- **`<cli> setup --plan -w <ws>` and `--all-active`** (0.2.8-dev.0). `-w` is
+  repeatable and plans those workspaces, active or not; `--all-active` plans
+  every active one; on a fresh machine `-w` narrows the blueprint's plan. A
+  closing hint names the repos only workspaces outside the plan hold. `-w`
+  and `--all-active` go with `--plan` only.
+- **Orgs are Den's own; sources are bindings** (0.2.8-dev.1, ORG-1d). An
+  org is any key of `orgs:`. `orgs.<id>.sources: [{host, owner|group}]`
+  claims git-host owners for it (an org can span two GitHub owners), and
+  `orgs.<id>.repos: [...]` lists repos outright (one owner can be split
+  across orgs). Catalog entries take `remote: <git url>` for any host;
+  `gh: owner/repo` stays the GitHub shorthand. A repo's org is the org
+  listing it, else the one whose source claims its owner, else its GitHub
+  owner; inference, `/api/orgs` and `org list` use it, and a claimed owner
+  is not listed as its own org. A repo clones from its source (GitHub with
+  `gh` as credential helper), or with no source from its `remote:` through
+  plain git and the user's own credential helper (SEC-0); `setup --plan`
+  shows that URL. Discovery (`register`) and the Release page skip an org
+  with no GitHub source. A bad value names its key; a repo or owner claimed
+  by two orgs is an error naming both. See docs/distributions.md, Orgs.
+- **`<cli> register <path> -w <ws>`** (0.2.8-dev.0) writes that workspace,
+  active or not, and leaves focus alone. It used to fail with "-w/--workspace
+  is not valid with register".
+
+### Changed
+
+- **`setup --plan` and `up --plan` show a dev-managed repo's real branch**
+  (0.2.8-dev.0): the one its checkout has out (read from `.git/HEAD`, no git
+  process), or `(branch unknown)`, where they printed `main` for every
+  checkout.
+- **`up --plan` exits 1 when nothing resolves** (0.2.8-dev.0): a name no
+  workspace has, or a workspace with nothing to start. It exited 0.
+- **`register` with no terminal exits 2** (0.2.8-dev.0) with one usage line
+  that names `-w`: `register needs a terminal (stdin is not a TTY); without
+  one: <cli> register <path> [--name <repo>] [--gh <owner/repo>] [-w
+  <workspace>]`. It went on to prompt with nothing to answer.
+
+### Fixed
+
+- **A config that fails validation stops every command** (0.2.8-dev.2).
+  A repo or owner claimed by two orgs (or any other bad ORG-1d value) is
+  checked before any command that touches orgs, the catalog, clones or
+  releases runs, and it exits 1 naming both keys. `sync` over existing
+  clones exited 0 and pulled, because it reads only workspaces.yml and the
+  catalog; `register <path> -w <ws>` wrote workspaces.yml and the catalog,
+  `workspace create` wrote workspaces.yml, and `workspace use` /
+  `add-service` exited 0. Now each stops before any git call or write. `web`, `mcp`, `validate`, `create`,
+  `config`, `local-dev` and `view-results` still run.
+- **The web API answers a config that fails validation as JSON**
+  (0.2.8-dev.2). Every API route that reads the config answers 422
+  `{ ok: false, error: "<the message naming the keys>", code:
+  "config_invalid" }`, where `/api/orgs`, `/api/services` and others
+  answered a text/plain 500 "internal server error" and some routes turned
+  it into a 400 or an empty list. The error names config keys, never
+  values. `/api/server-info`, `/api/server-log`, `/api/changelog` and
+  `/api/web/restart` still answer, and pages still load.
+- **A scoped MCP `manifest_validate` refused on another workspace's path
+  shows in that repo's activity** (0.2.8-dev.2). The refusal is recorded
+  under the catalog repo whose checkout holds the path (in any workspace),
+  as `logs_tail` refusals are since 0.2.8-dev.1. The entry is addressed by
+  the repo, not the path; its detail is the refusal message, which quotes
+  the path.
+- **A scoped MCP refusal of a non-lifecycle tool shows on its service**
+  (0.2.8-dev.1). A refused `logs_tail`, `logs_search` or other non-lifecycle tool
+  was stored with an empty detail and no service, so the service panel's
+  activity (`GET /api/activity?address=<repo>/<svc>`) never showed it. The
+  entry's detail is now the refusal, and it carries `addresses`: the repo
+  or `repo/service` the call named, or every target of a `logs_search`
+  (one entry, listed under each).
+- **`up --plan -w <ws>` with nothing to start is a usage error**
+  (0.2.8-dev.1): one line, exit 2, naming `up -a -w <ws>` (the whole
+  workspace) and `up <repo> -w <ws>`. It printed "No services specified and
+  no invocation target resolvable".
+- **Test workers inherit no credentials** (0.2.8-dev.0). `tests/setup.ts`
+  strips credential-shaped variables (by name, family or token shape) from
+  the environment before any suite runs, so a failing assertion on a
+  spawn env can no longer print a developer's tokens.
+
+### Migrations
+
+- None. A script that ran `up --plan` and ignored its exit code may now see
+  1 when the plan is empty (2 for `up --plan -w <ws>` with no repo or
+  `-a`).
+- ORG-1d (`orgs.<id>.sources`, `orgs.<id>.repos`, catalog `remote:`) is
+  optional: no change is needed, and a config without those keys behaves
+  exactly as on 0.2.7. A den.yml that uses them needs Den 0.2.8 or later.
+- A client of the web API that reads a config error should check for
+  status 422 and `code: "config_invalid"` (0.2.8-dev.2); it was a
+  text/plain 500.
+
+## [0.2.7] - 2026-11-05
+
+### Added
+
+- **A workspace belongs to an org** (0.2.7-dev.2, ORG-1a). Its org is
+  `org:` on the workspace in workspaces.yml, else `org:` on the blueprint
+  workspace (`defaults.workspaces.<n>.org`, the one new blueprint key), else
+  the one catalog owner of its repos (case-insensitive; `gh: ""` ignored),
+  else `github_org`, the default org. It is computed on read, never written
+  to workspaces.yml. A config with no `org:` resolves to `github_org` as
+  before, unless all of a workspace's repos have one other owner in the
+  catalog.
+- **`<cli> org list`** (0.2.7-dev.2, ORG-1a): each org's label, its
+  workspaces on this machine, which is the default, and the org warnings.
+  `<cli> workspace list` gains an Org column; `--org <id>` filters it.
+- **Org warnings, never errors** (0.2.7-dev.2, ORG-1a, C1): a workspace
+  whose repos span several owners, an `org:` naming an owner Den does not
+  know, a repo in another owner than its workspace's org, a workspaces.yml
+  `org:` that overrides the blueprint's. Shown by `org list` and
+  `workspace list`.
+- **`<cli> setup --plan`** (0.2.7-dev.2, ORG-1a): each repo's org and clone
+  URL, and whether it is cloned, then stop. On a fresh machine it plans the
+  blueprint's workspaces; once seeded, the focused workspace. `<cli> up
+  --plan` prints the same lines for its repos. Nothing is cloned, seeded or
+  written.
+- **`GET /api/orgs` entries gain `default` and `workspaces`**, and
+  `/api/<cli>/config` gains `default_org` (0.2.7-dev.2, ORG-1a). Every
+  existing field, entry and order is unchanged; `?repos=1` still maps each
+  repo to its owner string.
+- **`<cli> register --org <id>`** (0.2.7-dev.2, ORG-1a) lists another org's
+  repos for a managed clone.
+
+- **Bare `<cli> validate` checks every manifest** (0.2.7-dev.1, from a
+  consumer). In the distribution root, with no argument: each workspace repo
+  once per checkout (own or held, plus any override, then the merge), the
+  held manifest when there is no checkout, and held manifests no workspace
+  uses. One line per repo, details on failure, exit 1 if any fails, nothing
+  cloned. `--held` checks `manifests/` alone, independent of the machine. A
+  path argument works as before.
+
+### Changed
+
+- **A repo is released from its own org** (0.2.7-dev.2, REL-1). With no
+  `release.org`, a repo with no `gh:` in `release.repos` released from
+  `github_org`, so a client org's repo targeted the wrong owner. Its owner
+  is now an explicit `release.org` (unchanged: it still wins for every
+  repo), else the repo's non-empty catalog owner, else `github_org`.
+- **`register` lists the focused workspace's org** (0.2.7-dev.2, ORG-1a),
+  not `github_org` alone, and no longer falls back to the owner of Den's own
+  git remote (SEC-0): with no org it says how to set one.
+
+### Fixed
+
+- **A second root's server leaves the first root's services alone**
+  (0.2.7-dev.3, dev.4). Every root of a product shares one daemons file.
+  A server's two startup sweeps (the stale-daemon prune and the health
+  reaper) dropped any record whose address did not resolve in its own
+  workspaces, so starting a scratch root's server silently forgot another
+  root's running dev server; an interactive Ctrl-C stopped every service in
+  the file, and deactivating a workspace released any record with the same
+  workspace name. Records are now stamped with the root that started them
+  and a server lists, stops, releases and sweeps only its own (other roots'
+  records stay in the file untouched). An older unstamped record is never
+  dropped just for not resolving; it still goes when its containers are
+  verifiably gone or two health checks fail. The reaper now logs what it
+  removes.
+- **A service the edge has no route for is no longer healthy** (0.2.7-dev.2).
+  A health URL served through the edge answered the edge's own
+  `404 page not found` when the service had no route, and Den counted any
+  404 as up. That exact 404 is now down with "no route (edge 404)", over
+  HTTP and HTTPS; a 404 from the service itself is still up.
+- **A client workspace no longer clones from the default org** (0.2.7-dev.2,
+  ORG-1a). Seeding, `up` and the web sync gave a repo with no clone URL
+  `<github_org>/<repo>`; it is now `<org>/<repo>` with its workspace's org.
+- **`<cli> setup` clones a catalog entry with `gh: ""`** from its
+  workspace's org (0.2.7-dev.2), as `up` does, instead of failing on an
+  empty slug.
+- **A seed without a terminal no longer resets a workspace that has
+  entries** (SEED-0). `<cli> init` and `<cli> workspace seed` from a script
+  or `make` replaced every entry of the default (or blueprint) workspaces with
+  managed clones, your own dev-managed checkouts included, without asking.
+  Without a TTY they now refuse (exit 1, nothing written) and name
+  `--reset`; on a TTY they still ask, default No. `init --reset` and
+  `workspace seed --reset` reset as before.
+- **A failed seed leaves the workspaces as they were** (0.2.7-dev.1, from a
+  consumer). Seeding wrote workspaces.yml, then filled the catalog, which
+  fails with no `github_org`: the workspace was reset and nothing could be
+  cloned. The catalog comes first now, and the org is needed only for a repo
+  with no clone URL in the catalog.
+- **A seed refusal names the command that was run** (`init --reset` or
+  `workspace seed --reset`).
+- **A `DEN_ROOT` with no den.yml is a one-line error** (exit 2), not a stack
+  trace from deep in module loading.
+- **Piped output carries no ANSI from tables** (`status`, `services`, test
+  results). cli-table3 coloured borders and head cells itself, ignoring
+  NO_COLOR and a pipe.
+- **`<cli> mcp --call` validates its arguments** against the tool's schema,
+  strictly: an unknown or misspelt key, or a bad value, exits 2 with the
+  problem and the keys the tool takes, and calls nothing.
+- **The web UI service survives a removed nvm version.** Install prefers a
+  stable node of the same major version over a version manager's (or uses
+  `DEN_SERVICE_NODE`), and warns when it must keep one. `service status`
+  exits 1, naming it, when the installed node no longer exists.
+
+- **`<cli> init` in the distribution root seeds even through a symlinked
+  path** (`/var` → `/private/var`, a symlinked home). It compared paths
+  without resolving links and ran the manifest scaffolder instead.
+
+### Migrations
+
+- A script that relied on a non-interactive seed resetting a changed
+  workspace must pass `--reset`.
+- Optional (ORG-1a): to put a blueprint workspace in an org other than the
+  one its catalog owners give, add `org: <id>` to it under
+  `defaults.workspaces`. Pin Den 0.2.7 or later first: an older Den rejects
+  the key. Nothing else needs changing.
+
 ## [0.2.6] - 2026-11-04
 
 ### Fixed

package/bin/den

@@ -49,6 +49,15 @@ if [ "${1:-}" = "mcp" ] && ! case "${2:-}" in connect|disconnect|clients|config)
   built="dist/src/ui/cli/mcp-main.js"
 fi
 
+# A DEN_ROOT that names no distribution is a usage error, not a crash: say
+# so here, before any module resolves paths from it at import time.
+# (`create` needs no distribution.)
+if [ -n "${DEN_ROOT:-}" ] && [ "$entry" != "src/ui/cli/create-main.ts" ] && [ ! -f "$DEN_ROOT/den.yml" ]; then
+  echo "den: DEN_ROOT is set to \"$DEN_ROOT\" but that directory has no den.yml." >&2
+  echo "     Point it at your distribution's checkout, or unset it." >&2
+  exit 2
+fi
+
 # Escape hatch: force the compiled build (e.g. to test the prod artifact).
 if [ "${DEN_USE_DIST:-}" = "1" ] && [ -f "$DEN_ENGINE_ROOT/$built" ]; then
   exec node "$DEN_ENGINE_ROOT/$built" "$@"

package/docs/distributions.md

@@ -104,6 +104,23 @@ naming the file each error is in, then checks the merged result:
   ERROR   services.api.commands.local.down  unknown key "down": not in the base manifest
 ```
 
+Run with no argument in the distribution root, `<cli> validate` checks every
+manifest the distribution uses, and never clones:
+
+- each repo of every workspace, once per checkout path, with the
+  workspaces that use it and where its base comes from (`own`, `held`,
+  `+ override`);
+- a repo with no checkout on disk falls back to its held manifest, marked
+  `held only, no checkout`. With no held manifest either it is a warning, not
+  a failure;
+- each held manifest in `manifests/` that no workspace uses.
+
+It prints one line per repo, details only for a layer with errors or
+warnings, and exits 1 if any fails. `<cli> validate --held` checks only
+`manifests/`, as if nothing were checked out, so the result does not depend on
+the machine (use it in a CI or upgrade gate). An override whose base is the
+repo's own manifest is noted there, not checked.
+
 The web UI's Services cards show the layers each manifest was built from
 (`manifest: repo + override`), and `/api/services` returns them per service as
 `manifestLayers`, e.g. `["held", "override"]`. `DEN_MANIFESTS_DIR` points the
@@ -435,8 +452,8 @@ defaults:
       focus: true
 ```
 
-Each entry takes `repos`, `branch` and `autostart_off`, the same fields as
-`defaults.workspace`, plus `focus`. Seeding creates every named workspace
+Each entry takes `repos`, `branch`, `autostart_off` and `org`, the same
+fields as `defaults.workspace`, plus `focus`. Seeding creates every named workspace
 with its repos, activates them all, and focuses the one with `focus: true`
 (else the first). Set `defaults.workspace` or `defaults.workspaces`, not both:
 both at once is an error, as is more than one `focus: true`.
@@ -452,6 +469,141 @@ Once seeded, a repo that later joins `defaults.workspace.repos` is added to
 you removed from it or that another workspace holds. With
 `defaults.workspaces` nothing is topped up.
 
+To see what a setup would clone before it clones anything, run
+`acme setup --plan`: each repo with its org and clone URL, and whether it
+is cloned yet. On a fresh machine it plans the blueprint (every workspace
+`acme workspace seed` would create); once seeded, the focused workspace.
+`-w <workspace>` (repeatable) plans those workspaces instead, active or not,
+and `--all-active` every active one; on a fresh machine `-w` narrows the
+blueprint's plan. Repos that only workspaces outside the plan hold are named
+in a closing hint. A dev-managed repo shows the branch its checkout has out
+(read from its `.git/HEAD`), not a configured one. `acme up --plan` lists
+the same lines for the repos it would start, and exits 1 when nothing
+resolves (a name no workspace has, an empty workspace). Both are read-only:
+nothing is cloned, seeded or written.
+
+## Orgs
+
+A distribution can hold work for more than one org: each workspace belongs
+to one. An org's id is a key of `orgs:` or a GitHub owner, and today an org
+is the GitHub owner of the same name. `github_org` is the default org. A
+distribution that never mentions orgs has one org, the default, and every
+workspace is in it.
+
+```yaml
+github_org: acme
+orgs:
+  acme: { label: Acme }
+  globex: { label: Globex, color: "#0af" }
+defaults:
+  workspaces:
+    storefront:
+      repos: [shop-web, shop]
+    client:
+      org: globex # optional: the workspace's org
+      repos: [globex-web, globex-api]
+```
+
+A workspace's org is the first of:
+
+1. `org:` on the workspace in `config/local/workspaces.yml` (this machine)
+2. `org:` on the blueprint workspace of the same name (committed)
+3. the one owner of its repos in the catalog (`gh: <owner>/<repo>`; owners
+   compare case-insensitively, and a `gh: ""` counts as unknown)
+4. `github_org`
+
+It is worked out each time it is read and never written back. A repo with
+no clone URL is cloned from `<org>/<repo>` with its workspace's org: seeding
+the blueprint above gives `globex-web` `gh: globex/globex-web`, not
+`acme/...`. `acme register` picks a managed clone from the focused
+workspace's org, or from `--org <id>`.
+
+`acme org list` shows each org's label, its workspaces and which is the
+default. `acme workspace list` has an Org column, and `--org <id>` lists one
+org's workspaces. A workspace whose repos belong to several owners, an
+`org:` naming an owner Den does not know, or a repo in another owner than
+its workspace's org is a warning in both lists, never an error.
+`GET /api/orgs` adds `default` and `workspaces` to each entry, and
+`/api/<cli>/config` adds `default_org`.
+
+`org:` in the blueprint needs Den 0.2.7 or later: an older Den rejects the
+unknown key. Pin 0.2.7 before you commit it.
+
+### Sources and repos (0.2.8)
+
+An org is Den's own: its id is any key of `orgs:`, and it needs no git
+host. Two optional keys bind it to where its repos live:
+
+```yaml
+github_org: acme
+orgs:
+  acme-group: # one org, two GitHub owners
+    label: Acme Group
+    sources:
+      - { host: github, owner: acme }
+      - { host: github, owner: acme-labs }
+  globex-billing: # one owner split across two orgs
+    repos: [globex-invoices]
+  globex:
+    sources: [{ host: github, owner: globex }]
+  initech: # no git host at all
+    sources: []
+    repos: [widget]
+```
+
+- `orgs.<id>.sources` is a list of `{host, owner}` (or `{host, group}`). A
+  source claims that owner's repos for the org. `host: github` is built
+  in; any other host id (`gitlab`, …) claims repos whose `remote:` is on
+  `<host>.com` or a `<host>.` hostname, and clones them from that remote.
+- `orgs.<id>.repos` lists repos that belong to the org whatever their
+  owner.
+- An entry with neither key is what it was before 0.2.8: the GitHub owner
+  of its own name.
+
+The catalog (`config/local/service-catalog.yml`) takes a `remote:` for any
+host, beside `gh: owner/repo`, which stays as the GitHub shorthand:
+
+```yaml
+widget: { remote: git@git.initech.example:tools/widget.git }
+```
+
+A repo's org is the org whose `repos` lists it, else the org with a source
+that claims its owner, else its GitHub owner as before. That org is what
+`/api/orgs?repos=1` maps the repo to and what infers a workspace's org (step
+3 above). A claimed owner is not listed as an org of its own, and a
+`github_org` that names one makes the claiming org the default. Service rows
+(`/api/services`, `/api/health`) keep `org` as the repo's GitHub owner.
+
+A repo clones from its source: a GitHub source gives
+`https://github.com/<owner>/<repo>.git` with your `gh` as credential helper.
+A repo with no source that claims it clones and pulls from its `remote:`
+through plain git, with your own git credential helper; Den never hands it
+`gh` or any credential of its own. A remote must be `https://`, `ssh://`,
+`git://`, `file://`, `user@host:path` or an absolute path. `setup --plan`
+shows it as the clone URL, with any user info masked.
+
+An org with no GitHub source has no repo discovery (`register` lists
+nothing for it) and its repos are left off the Release page.
+
+These keys are checked when den.yml is read, and a bad value is an error
+that names its key (`orgs.initech.sources[0].owner must be …`). A repo
+listed by two orgs, or an owner claimed by two orgs' sources (or by a
+source and an org with no `sources` of that name), is an error naming both
+keys. Such an error stops every command that touches orgs, the catalog,
+clones or releases (exit 1, before any git call or write), and every web
+API route that reads the config answers it as 422 `{ "ok": false, "error":
+"<message>", "code": "config_invalid" }`. Without the new keys nothing
+changes: `/api/orgs` is byte for byte what 0.2.7 answered. They need Den
+0.2.8 or later.
+
+## Releases
+
+The Release page dispatches each repo's CD workflow on GitHub. A repo's
+owner there is its own `gh: owner/repo` in `release.repos`, else
+`release.org` when it is set, else the repo's owner in the catalog, else
+`github_org`. Leave `release.org` unset when the repos belong to different
+orgs: each then releases from its own.
+
 ## The bin shim
 
 `bin/<cli>` is three lines of sh: it names the distribution root and runs
@@ -580,10 +732,17 @@ node_modules/@monster-orange/den/service/install.sh print       # the plist only
 | `DEN_ROOT`          | required in a distribution               |
 | `DEN_SERVICE_LABEL` | `local.<distribution dir name>.web`      |
 | `DEN_SERVICE_LOGS`  | `~/Library/Logs/<distribution dir name>` |
-
-The service runs the engine's server with the `node` on your `PATH` at install
-time, from the distribution root; re-run `install` after changing node versions
-or upgrading Den. Keep the label stable: it is how launchd knows the service.
+| `DEN_SERVICE_NODE`  | see below                                |
+
+The service runs the engine's server, from the distribution root, with the
+`node` on your `PATH` at install time. A version manager's node (nvm, fnm,
+volta, asdf, mise) lives under a versioned path that disappears when that
+version is removed, so install prefers `/opt/homebrew/bin/node` or
+`/usr/local/bin/node` when one has the same major version, and otherwise
+keeps the version manager's and warns. `DEN_SERVICE_NODE` names the node
+outright. `service status` exits 1 when the installed node no longer exists.
+Re-run `install` after changing node versions or upgrading Den. Keep the
+label stable: it is how launchd knows the service.
 
 ## MCP server
 
@@ -650,6 +809,46 @@ everyone's checkout is in the same place.
 `--port <n>` (on `mcp` or `mcp connect`) points it at a web server on another
 port.
 
+### Scoped to one workspace
+
+```sh
+./bin/acme mcp --workspace smb --actor agent:planner
+```
+
+`--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>); "<other>" is another
+workspace`) before anything reaches the web server. A refused call is
+  recorded in the activity trail, read tools included.
+- **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).
+- **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
+agent:<id> <client> <version> (workspace <ws>, mcp pid <pid>, session
+<id>)` for every exec, run and sync.
+- `<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.
+
+**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
+calls the API itself (curl, a browser) is not held to its workspace. Enforcing
+the scope in the HTTP server is WS-3a, planned for 0.4. `mcp connect` still
+registers the unscoped server; to hand one agent a scoped server, add it to
+that agent's config yourself, for example in a project's `.mcp.json`:
+`"args": ["mcp", "--workspace", "smb", "--actor", "agent:planner"]`.
+
 ### One call from a shell
 
 ```sh

package/package.json

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

package/service/install.sh

@@ -15,6 +15,7 @@
 #
 #   DEN_SERVICE_LABEL  launchd label (default local.<dist dir name>.web)
 #   DEN_SERVICE_LOGS   log directory (default ~/Library/Logs/<dist dir name>)
+#   DEN_SERVICE_NODE   the node the agent runs (default: see pick_node)
 #   DEN_SERVICE_READY_CHECK=external  install does not print "running": the
 #                      caller (`<cli> service install`) checks the server
 #                      answers first.
@@ -47,8 +48,36 @@ find_tsx() {
   done
 }
 
+# A version manager's node (nvm, fnm, volta, asdf, mise) lives under a
+# versioned path that disappears when that version is removed, and the agent
+# then fails to start with no clear reason. Prefer a stable install of the
+# same major version; otherwise keep it and say so.
+STABLE_NODES="${DEN_SERVICE_STABLE_NODES:-/opt/homebrew/bin/node /usr/local/bin/node}"
+node_major() { "$1" -p "process.versions.node.split('.')[0]" 2>/dev/null; }
+pick_node() {
+  if [ -n "${DEN_SERVICE_NODE:-}" ]; then
+    [ -x "$DEN_SERVICE_NODE" ] || { echo "✗ DEN_SERVICE_NODE ($DEN_SERVICE_NODE) is not executable" >&2; exit 1; }
+    echo "$DEN_SERVICE_NODE"; return
+  fi
+  local node; node="$(command -v node)" || { echo "✗ node is not on PATH" >&2; exit 1; }
+  case "$node" in
+    */.nvm/*|*/fnm/*|*/.fnm/*|*/.volta/*|*/.asdf/*|*/mise/*) ;;
+    *) echo "$node"; return ;;
+  esac
+  local want c; want="$(node_major "$node")"
+  for c in $STABLE_NODES; do
+    if [ -x "$c" ] && [ "$(node_major "$c")" = "$want" ]; then echo "$c"; return; fi
+  done
+  # Warn when installing; `print` writes the plist and nothing else.
+  if [ "${1:-}" = install ]; then
+    echo "⚠ the service will run $node, a version manager's node: it stops starting" >&2
+    echo "  when that version is removed. Re-run install after switching, or set DEN_SERVICE_NODE." >&2
+  fi
+  echo "$node"
+}
+
 write_plist() { # $1 = output file
-  NODE="$(command -v node)" || { echo "✗ node is not on PATH" >&2; exit 1; }
+  NODE="$(pick_node "$MODE")"
   TSX="$(find_tsx)" || { echo "✗ tsx not installed: run npm ci in $DIST" >&2; exit 1; }
   DOCKER_DIR="$(dirname "$(command -v docker || echo /usr/local/bin/docker)")"
   SVC_PATH="$(dirname "$NODE"):$DOCKER_DIR:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
@@ -79,7 +108,8 @@ else:
 PY
 }
 
-case "${1:-install}" in
+MODE="${1:-install}"
+case "$MODE" in
   install)
     mkdir -p "$LOGS" "$(dirname "$PLIST")"
     write_plist "$PLIST.new"
@@ -115,6 +145,15 @@ case "${1:-install}" in
     write_plist -
     ;;
   status)
+    # The node the agent was installed with may be gone (a removed nvm
+    # version): launchd then restarts it forever with no useful message.
+    if [ -f "$PLIST" ] && command -v plutil >/dev/null 2>&1; then
+      svc_node="$(plutil -extract ProgramArguments.0 raw -o - "$PLIST" 2>/dev/null || true)"
+      if [ -n "$svc_node" ] && [ ! -x "$svc_node" ]; then
+        echo "✗ $LABEL runs $svc_node, which no longer exists: re-run service install" >&2
+        exit 1
+      fi
+    fi
     # launchctl's own "Could not find service" is noise when it isn't loaded.
     if out="$(launchctl print "$DOMAIN/$LABEL" 2>/dev/null)"; then
       printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'

package/src/shared/agent-actor.ts

@@ -12,8 +12,20 @@ export const AUDIT_HEADERS = {
   clientVersion: "x-den-mcp-client-version",
   pid: "x-den-mcp-pid",
   session: "x-den-mcp-session",
+  /** A scoped server's actor id (`agent:<id>`, AG-2a-core). */
+  agent: "x-den-mcp-agent",
+  /** The workspace a scoped server is pinned to (AG-2a-core). */
+  workspace: "x-den-mcp-workspace",
 } as const;
 
+/**
+ * `agent:<id>`: what `<cli> mcp --actor` takes. The id is letters, digits,
+ * dots, dashes and underscores, 1-64 long, starting with a letter or digit.
+ */
+export const AGENT_ACTOR_RE = /^agent:[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A workspace name, as the config accepts it (1-64 long here). */
+export const WORKSPACE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
 export interface AgentInfo {
   /** The MCP client's self-reported name (clientInfo.name). */
   client: string;
@@ -23,6 +35,10 @@ export interface AgentInfo {
   mcpPid: number | null;
   /** The MCP server's session id (one per `<cli> mcp` process). */
   session: string;
+  /** A scoped server's actor (`agent:<id>`); absent when unscoped. */
+  agent?: string;
+  /** The workspace a scoped server is pinned to; absent when unscoped. */
+  workspace?: string;
 }
 
 export interface AgentActor extends AgentInfo {
@@ -49,6 +65,13 @@ export function agentAuditHeaders(info: AgentInfo): Record<string, string> {
     [AUDIT_HEADERS.clientVersion]: clean(info.clientVersion) || "unknown",
     [AUDIT_HEADERS.pid]: info.mcpPid === null ? "" : String(info.mcpPid),
     [AUDIT_HEADERS.session]: clean(info.session).replace(/[^A-Za-z0-9-]/g, ""),
+    // Only a scoped server sends these: an unscoped one's headers are as before.
+    ...(info.agent && AGENT_ACTOR_RE.test(info.agent)
+      ? { [AUDIT_HEADERS.agent]: info.agent }
+      : {}),
+    ...(info.workspace && WORKSPACE_NAME_RE.test(info.workspace)
+      ? { [AUDIT_HEADERS.workspace]: info.workspace }
+      : {}),
   };
 }
 
@@ -59,19 +82,31 @@ export function actorFromHeaders(
   const h = headers as Record<string, string | string[] | undefined>;
   if (clean(h[AUDIT_HEADERS.actor]) !== "agent") return null;
   const pid = clean(h[AUDIT_HEADERS.pid], 10);
+  // Kept only when well-formed: a malformed value is dropped, never cleaned
+  // into something that looks like another agent's id.
+  const agent = clean(h[AUDIT_HEADERS.agent], 80);
+  const workspace = clean(h[AUDIT_HEADERS.workspace], 80);
   return {
     kind: "agent",
     client: clean(h[AUDIT_HEADERS.client]) || "unknown",
     clientVersion: clean(h[AUDIT_HEADERS.clientVersion], 32) || "unknown",
     mcpPid: /^\d+$/.test(pid) ? Number(pid) : null,
     session: clean(h[AUDIT_HEADERS.session]).replace(/[^A-Za-z0-9-]/g, ""),
+    ...(AGENT_ACTOR_RE.test(agent) ? { agent } : {}),
+    ...(WORKSPACE_NAME_RE.test(workspace) ? { workspace } : {}),
   };
 }
 
-/** "agent <client> <version> (mcp pid <pid>, session <id>)". */
+/**
+ * "agent <client> <version> (mcp pid <pid>, session <id>)"; a scoped
+ * server's actor leads: "agent:<id> <client> <version> (workspace <ws>,
+ * mcp pid <pid>, session <id>)".
+ */
 export function actorLabel(actor: AgentActor): string {
+  const who = actor.agent ?? "agent";
+  const ws = actor.workspace ? `workspace ${actor.workspace}, ` : "";
   return (
-    `agent ${actor.client} ${actor.clientVersion} ` +
-    `(mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
+    `${who} ${actor.client} ${actor.clientVersion} ` +
+    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
   );
 }