@monster-orange/den 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -4,6 +4,214 @@ 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.5] - 2026-11-04
+
+### Fixed
+
+- **`<cli> web down` (any SIGTERM) shuts the web server down cleanly
+  under load.** `<cli> web up` ran the server under the `tsx` CLI, a
+  parent process that relays a signal to the server and, if the server has
+  not acknowledged it within about 60ms, SIGKILLs it and exits 143. On a
+  loaded machine the server missed that window, so it was killed without
+  its shutdown. The server now runs as `node --import <tsx loader>`, one
+  process that gets the signal itself, as the launchd service already did.
+- **Compose-stack health no longer starts a CLI per check.** Den's own
+  check for a compose repo was a `<cli> stack health <stack> --service X`
+  process per manifest service, each a full CLI start running its own
+  `docker ps`: 17-19 processes per health cycle for three stacks. On a
+  loaded machine (load 35-55) they ran past their budget, and two such
+  cycles in a row read every stack down. These checks are now answered
+  in the web server and in `<cli> status` from one `docker ps` per cycle,
+  shared by every check in it (17 checks: 17 CLI starts and 17 docker
+  calls per cycle before, 0 and 1 now). The verdict is the one `stack
+  health` gives. A distribution's own shell checks still run as shell
+  commands, at most max(2, cpus/2) at a time; a queued check's budget
+  starts when it starts.
+- **The health row no longer shows healthy repos down on a cold poll.** A
+  check that got no answer within its budget was sent as a finished
+  `ok: false`: a compose stack's check (`<cli> stack health`, a full CLI
+  start per service, 15-20 of them at once) past its 5s budget on a loaded
+  machine, or an HTTP check past its 3s timeout. The row painted it red
+  and the 8s health cache replayed that to the next page load, until the
+  next poll corrected it. Now a check that has not answered is **pending**
+  (`ok: null`, `pending: true`, the reason in `error`), never down. Only a
+  check that completed and failed is `ok: false`. A timeout is down only
+  when it repeats on the next cycle (`timeout (twice in a row)`), so a hung
+  service still shows. `<cli> status` agrees: on a timeout it probes once
+  more, and is down only when both probes time out. Health results have a
+  new `pending` state (`health: "pending"`), which readiness waits on
+  rather than skipping.
+- **"Docker state unknown" is not "not running".** When docker does not
+  answer, the health row and `<cli> status` report a compose stack as
+  unknown (`ok: null`), not down, and so does `/api/stacks`. `<cli> stack
+  health` exits 3 when it could not tell (docker did not answer, the stack
+  config could not be read), 1 only when a stack is not healthy.
+- **A health stream and a poll at once run each check once.** A stream
+  started its own full run next to an in-flight `/api/health` (or another
+  stream), doubling the shell checks' processes. It now joins the run in
+  flight, replaying what has landed and then following it.
+- The web header's dot for a multi-service repo without an entrypoint
+  turned red when none of its checks were up yet, even with none down. It
+  is red now only when a check completed and failed.
+
+- **The default workspace is seeded only on a genuine fresh setup.** Any
+  command that reads workspaces (`status`, `up`, `graph`, `logs`, …) seeded
+  `default` from `defaults.workspace.repos` whenever `default` was empty,
+  so moving every repo into per-project workspaces and deactivating
+  `default` got it refilled with managed entries on the next command, ready
+  to clone duplicates of repos you work on locally. Seeding now requires
+  that no workspace but `default` exists and that `default` was never
+  seeded (no `seeded_repos`). Declining the offer records that too, so it
+  is no longer asked again.
+- **No silent seeding without a TTY.** On a fresh setup a command without
+  a TTY now prints a one-line hint to run `<cli> workspace seed` and
+  changes nothing; on a TTY the offer stays. New: `<cli>
+  workspace seed` seeds explicitly (as `<cli> init` in the root does).
+- **Top-up no longer re-adds repos you moved or removed.** Top-up (adding
+  repos that joined the blueprint after seeding) never runs once you have
+  other workspaces, and skips a repo any workspace holds. Removing a
+  blueprint repo from `default` in the web UI records it, so a `default`
+  from before `seeded_repos` no longer gets it back on its one-time
+  migration.
+
+### Added
+
+- **The "What's new" pop-up shows the newest release only** (from
+  0.3.0-dev.16). A "Show all versions (N earlier)" button in its footer
+  lists every earlier version in the same pop-up, and "Show latest only"
+  collapses it again. It always opens collapsed, at the top: the scroll is
+  reset once the pop-up is shown (a reset made while it was hidden did not
+  stick, so a reopened pop-up kept its old scroll position). It is an
+  accessible modal dialog (`role="dialog"`, `aria-modal`, labelled by its
+  title). Opening moves focus to its heading, so a screen reader starts at
+  the latest notes. Tab stays inside, and closing returns focus to what had
+  it, which is the version pill after the first-visit auto-open. Each
+  version is a heading (h4) for heading navigation, and the icon buttons
+  have spoken names ("Close", "Copy v0.2.5 as Markdown").
+- **The version pill names the running build** (`v0.2.5-dev.2`), not the
+  newest changelog heading, so a prerelease under test says what it is.
+- **Multi-workspace blueprint: `defaults.workspaces`.** `{ <name>: {
+  repos, branch?, autostart_off?, focus? } }` in the org config. A fresh
+  setup creates each workspace with its repos (managed), activates them
+  all and focuses the one with `focus: true` (else the first). Setting
+  both `defaults.workspace` and `defaults.workspaces` is an error, as is a
+  malformed entry. See docs/distributions.md, "Workspace blueprint".
+
+### Migrations
+
+- None required.
+
+## [0.2.4] - 2026-11-04
+
+### Fixed
+
+- **`GET /api/services` no longer blocks the web server.** It looked up
+  each workspace checkout's branch with a synchronous `git rev-parse`, one
+  after another (~40ms each), so with a dozen repos every request held the
+  event loop for 0.5-1.5s and everything else waited behind it: the UI,
+  the MCP server's reads, and `/api/server-info`, which `<cli> mcp connect`
+  probes with a 1.5s timeout. The lookups now run as async child processes
+  in parallel; concurrent requests (one per open tab) share one build, and
+  a settled build is reused for 2s (`?refresh=1` forces a new one; any
+  mutating request clears it). Concurrent `/api/health` polls also share
+  one run instead of each starting its own.
+- **`<cli> mcp connect` / `mcp clients` tell a slow web server from a
+  stopped one.** A server that accepts the connection but does not answer
+  within 1.5s is reported as "not answering within 1.5s", not "not
+  running". When the org config sets `web.service` (the web UI runs as a
+  launchd service), the advice is `<cli> service status` instead of
+  `<cli> web up`.
+- **Web server shutdown no longer leaks an unhandled rejection, or hangs.**
+  On SIGTERM/SIGINT the server reads the running-services registry, whose
+  path resolves the distribution root again; if that walk fails (the dist's
+  den.yml moved or removed while the server ran), the async shutdown
+  rejected unhandled ("unhandled rejection (continuing): Error: cannot
+  locate the distribution root: walked up from
+  <dist>/node_modules/@monster-orange/den/src/ui/server") and, its signal
+  guard already set, the process never exited, so a service manager had to
+  wait out its timeout and kill it. The shutdown now logs the failure and
+  exits.
+- **Deactivating a workspace no longer stops a service that moved to
+  another workspace.** A daemon's owners were the workspaces recorded when
+  it started, so a repo moved from `default` into `ws-b` while its daemon
+  ran was still "owned" only by `default`, and `workspace deactivate
+  default` stopped it. Release now re-derives the owners from the current
+  workspaces.yml membership: a daemon is stopped only when no active
+  workspace still lists its repo, and otherwise its recorded owners become
+  the active workspaces that do.
+- **`<cli> workspace --help` lists every subcommand**: activate,
+  deactivate and focus were missing (and `workspace focus <name>` now
+  exists in the CLI, as it did in the web UI). Deactivate's help and output
+  say that it releases only the services Den tracks: compose stacks of the
+  workspace's repos keep running, and the output names the running ones
+  with `<cli> down <repo>` for each (from one `docker ps`; a generic line
+  when docker can't be asked).
+- **The first `/api/health/stream` (and `/api/health`) cycle no longer
+  blocks the web server for a second.** Resolving the manifest of a repo
+  without its own (a held manifest under `manifests/`) looked up the
+  checkout's origin with a synchronous `git config --get
+  remote.origin.url`, one repo after another (~40-100ms each), so a
+  server's first health run held the event loop for 1-1.5s. The origin is
+  now read from the checkout's git config file (worktrees and
+  subdirectories included), never by spawning git. Parsed manifests are
+  also reused while the file is unchanged: one request read the same
+  manifests several times, and parsing them held the loop ~100-200ms per
+  health run.
+- **`GET /api/workspaces/available-repos` no longer blocks the web
+  server.** It ran `git remote get-url origin` (and, for managed clones,
+  `git rev-parse`) synchronously per checkout; the lookups are now async
+  and in parallel, and concurrent requests share one walk (reused for 2s;
+  `?refresh=1` forces a new one, any mutating request clears it).
+- **`workspace deactivate` names the compose stacks a repo runs itself.**
+  It only knew Den stacks (a manifest's `compose:` section, project
+  `<stack>-<workspace>`), so a distribution whose repos start their own
+  compose projects (`make up`) got no line at all. A running project now
+  counts when Compose started it from inside one of the workspace's
+  checkouts (its `com.docker.compose.project.working_dir` label), as well
+  as when it is a Den stack's project.
+- **`<cli> workspace <sub> --help`** prints that subcommand's help, not the
+  whole `workspace` help.
+- **No synchronous directory walks or spawns on the web server's hot
+  request paths** (`/api/workspaces/available-repos`, the `/api/health`
+  stream). On a loaded machine (load average ~50) the dev.1 fixes still
+  left stalls of 1-5s; a CPU profile showed why:
+  - available-repos recursed into every directory without a manifest file
+    of its own, so in a distribution whose repos use held manifests it
+    walked each repo's whole tree (to depth 4) with `readdirSync` /
+    `existsSync`: seconds per call. It now never descends into a git
+    checkout or `node_modules`, and the walk is `fs.promises`.
+  - The distribution root (and so `product()`) was re-resolved on every
+    call, a den.yml `existsSync` per `*_ROOT` variable each time, hundreds
+    of times per request. It is now resolved once per set of inputs (the
+    env vars and entry script it reads); the engine root likewise.
+  - Manifests, the edge config and the derived graph order are reused
+    across a request and the polls after it (5s; any mutating request
+    clears them), and the graph order is recomputed after a request, never
+    inside one.
+  - HTTPS health checks built a TLS context from ~150 root certificates on
+    every check; one context is built once, at startup.
+  - The startup sweep of stale daemon records ran `docker ps` / `opctl
+    container ls` synchronously; it is async now (concurrent callers share
+    one call), and `/api/service/daemons` waits for it.
+  A new test runs the server with a spy on every synchronous fs and
+  child_process call and fails if either route makes a sync spawn or
+  directory walk, or any sync call outside a short allowlist of single
+  config-file reads.
+- **The web UI service no longer runs at background priority.**
+  `service install` wrote `ProcessType: Background` into the LaunchAgent,
+  so macOS ran the UI server on efficiency cores with throttled I/O: on a
+  busy machine its first requests stalled for 5-11s. It is now
+  `Interactive`, and `service status` shows launchd's spawn type.
+- **`workspace deactivate` never suggests stopping a stack another active
+  workspace still holds.** Such a stack is listed as "in use by another
+  workspace: <project> (still in <ws>)" instead of with a `down <repo>`
+  command, and a repo with a stack still in use gets no `down` suggestion.
+
+### Migrations
+
+- Re-run `<cli> service install` to pick up the new LaunchAgent priority
+  (`<cli> service status` should show `spawn type = interactive`).
+
 ## [0.2.3] - 2026-11-04
 
 ### Added

package/docs/distributions.md

@@ -327,6 +327,54 @@ brand:
 Runtime names (env vars, files, directories) always come from `den.yml`,
 never from the brand.
 
+## Workspace blueprint
+
+The workspaces a new machine starts with. Read from `defaults:` in the org
+config. Every repo is seeded as a managed clone (`mode: managed`) on the
+blueprint's branch; nothing is cloned until a command needs it. Switch a repo
+to a local checkout afterwards with `acme use-local <repo>`.
+
+One workspace, `default`:
+
+```yaml
+defaults:
+  workspace:
+    branch: main # default: main
+    repos: [shop-web, shop, infra-stack]
+    autostart_off: [shop] # seeded with autostart: false
+    entry: shop-web # where the setup script's dependency walk starts
+```
+
+Several named workspaces:
+
+```yaml
+defaults:
+  workspaces:
+    storefront:
+      repos: [shop-web, shop]
+    data:
+      repos: [warehouse, infra-stack]
+      branch: develop
+      focus: true
+```
+
+Each entry takes `repos`, `branch` and `autostart_off`, 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`.
+
+The blueprint applies only to a genuine fresh setup: no workspace except an
+empty `default` that was never seeded. On a TTY the first command that needs
+workspaces offers to seed. Without a TTY it prints a one-line hint and changes
+nothing. `acme workspace seed` (or `acme init` in the distribution root) seeds
+explicitly, and resets the blueprint's workspaces if they already hold repos.
+
+Once seeded, a repo that later joins `defaults.workspace.repos` is added to
+`default`, but only while `default` is your only workspace, and never a repo
+you removed from it or that another workspace holds. With
+`defaults.workspaces` nothing is topped up.
+
 ## The bin shim
 
 `bin/<cli>` is three lines of sh: it names the distribution root and runs
@@ -544,22 +592,22 @@ guard off.
 
 Read tools (always registered):
 
-| Tool                | Web API                                    | What                                                       |
-| ------------------- | ------------------------------------------ | ---------------------------------------------------------- |
-| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell)      |
-| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands |
-| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                        |
-| `graph`             | `/api/graph`                               | The derived dependency graph and startup order             |
-| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                             |
-| `environments`      | `/api/environments`                        | The enabled environment names (never their values)         |
-| `logs_search`       | `/api/logs/search`                         | Search services' full log history                          |
-| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)     |
-| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from            |
-| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                          |
-| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table        |
-| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                     |
-| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health    |
-| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names            |
+| Tool                | Web API                                    | What                                                                                                                                            |
+| ------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status`            | `/api/health`                              | Service health; `url` (HTTP check) or `check` (shell); `ok` true up, false down, null not known (`pending: true` when a check has not answered) |
+| `services`          | `/api/services`                            | Services, their mode (managed or dev-managed) and commands                                                                                      |
+| `applications`      | `/api/applications`                        | Org > Application > Repo > Services                                                                                                             |
+| `graph`             | `/api/graph`                               | The derived dependency graph and startup order                                                                                                  |
+| `workspaces`        | `/api/workspaces`                          | Workspaces, active and focused                                                                                                                  |
+| `environments`      | `/api/environments`                        | The enabled environment names (never their values)                                                                                              |
+| `logs_search`       | `/api/logs/search`                         | Search services' full log history                                                                                                               |
+| `logs_tail`         | `/api/service/taillog`                     | The last lines of a service's log (bounded, no follow)                                                                                          |
+| `tests_available`   | `/api/modules`, `/api/test-sources`        | A pillar's modules and the repos they come from                                                                                                 |
+| `security_latest`   | `/api/security/latest`                     | The newest security scan per mode                                                                                                               |
+| `release_status`    | `/api/release/runs`, `/api/release/status` | Recent CD runs, and an env's deployed-version table                                                                                             |
+| `manifest_validate` | `/api/manifest/validate`                   | Validate a manifest by path or content                                                                                                          |
+| `stacks`            | `/api/stacks`                              | What `stack ls/ps/health` show: project, routes, health                                                                                         |
+| `edge_status`       | `/api/edge`                                | The edge: up or down, its routes and cert names                                                                                                 |
 
 Action tools (only those named in `mcp.actions`): `service_up`,
 `service_down`, `service_restart` (through `/api/service/exec`),

package/package.json

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

package/service/install.sh

@@ -65,7 +65,9 @@ data = {
     "RunAtLoad": True,
     "KeepAlive": True,
     "ThrottleInterval": 10,
-    "ProcessType": "Background",
+    # Interactive, not Background: macOS gives Background agents efficiency
+    # cores and throttled I/O, and the UI stalled for seconds under load.
+    "ProcessType": "Interactive",
     "StandardOutPath": f"{logs}/web.log",
     "StandardErrorPath": f"{logs}/web.log",
 }
@@ -115,7 +117,7 @@ case "${1:-install}" in
   status)
     # 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)'
+      printf '%s\n' "$out" | grep -E '^\s*(state|pid|last exit code|runs|spawn type)'
     else
       echo "$LABEL is not loaded"
     fi

package/src/shared/constants.ts

@@ -48,6 +48,13 @@ export const HOSTED_HEALTH_CHECK_TIMEOUT_MS = 10_000;
 /** Timeout for spawning short-lived CLI subprocesses (open, sudo, git). */
 export const CLI_SPAWN_TIMEOUT_MS = 5_000;
 
+/**
+ * Exit code of `<cli> stack health` when it could not tell (docker did not
+ * answer, the stack config could not be read): the check is unknown, not
+ * down. Any other non-zero exit means the containers are not healthy.
+ */
+export const STACK_HEALTH_UNKNOWN_EXIT = 3;
+
 /** Timeout for `gh api` calls (branch listing, repo search). */
 export const GH_API_TIMEOUT_MS = 15_000;
 

package/src/shared/den-config.ts

@@ -255,24 +255,35 @@ export interface DenConfig {
    * `default-workspace.ts`.
    */
   defaults?: {
-    workspace?: {
-      /** Branch managed clones track (default "main"). */
-      branch?: string;
-      /** Repo-system names to seed, all as managed clones. */
-      repos?: string[];
+    workspace?: WorkspaceBlueprint & {
       /** The entry repo the seed's dependency walk starts from (listed first). */
       entry?: string;
-      /**
-       * Seeded repos that get `autostart: false` stamped on their workspace
-       * entry — the team default for systems a fresh clone should not start
-       * with workspace up (e.g. billing-api's `make up` opens an interactive
-       * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
-       */
-      autostart_off?: string[];
     };
+    /**
+     * Multi-workspace blueprint: `{ <name>: { repos, focus?, branch?,
+     * autostart_off? } }`. On a genuine fresh setup each workspace is created
+     * with its repos (managed), all are activated, and the one marked
+     * `focus: true` (else the first) is focused. Exclusive with `workspace`.
+     */
+    workspaces?: Record<string, WorkspaceBlueprint & { focus?: boolean }>;
   };
 }
 
+/** One workspace's blueprint: the repo entries a fresh setup seeds it with. */
+export interface WorkspaceBlueprint {
+  /** Branch managed clones track (default "main"). */
+  branch?: string;
+  /** Repo-system names to seed, all as managed clones. */
+  repos?: string[];
+  /**
+   * Seeded repos that get `autostart: false` stamped on their workspace
+   * entry — the team default for systems a fresh clone should not start
+   * with workspace up (e.g. billing-api's `make up` opens an interactive
+   * Stripe tab). Personal thereafter: toggle per system in the web ⋮ menu.
+   */
+  autostart_off?: string[];
+}
+
 /**
  * Per-engineer preferences stored in config/local/user.yml (gitignored).
  * Only affects settings that should differ between engineers on the same team.
@@ -618,6 +629,113 @@ export interface WebConfig {
   service?: { label?: string; logs?: string };
 }
 
+/** A validated workspace blueprint with its defaults applied. */
+export interface ResolvedWorkspaceBlueprint {
+  name: string;
+  repos: string[];
+  branch: string;
+  autostartOff: string[];
+  focus: boolean;
+}
+
+/** Which blueprint shape the distribution uses, and its workspaces. */
+export interface WorkspaceBlueprints {
+  shape: "none" | "single" | "multi";
+  workspaces: ResolvedWorkspaceBlueprint[];
+}
+
+const BLUEPRINT_KEYS = ["branch", "repos", "autostart_off"];
+
+function blueprintStrings(where: string, key: string, v: unknown): string[] {
+  if (v === undefined) return [];
+  if (!Array.isArray(v) || v.some((r) => typeof r !== "string" || !r.trim()))
+    throw new Error(`${where}.${key} must be a list of repo names`);
+  return v as string[];
+}
+
+function resolveBlueprint(
+  where: string,
+  name: string,
+  raw: unknown,
+  /** Extra keys allowed; null skips the unknown-key check (legacy shape). */
+  extraKeys: string[] | null,
+): ResolvedWorkspaceBlueprint {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+    throw new Error(`${where} must be a map: { repos: [...] }`);
+  const bp = raw as Record<string, unknown>;
+  const known = [...BLUEPRINT_KEYS, ...(extraKeys ?? [])];
+  for (const key of Object.keys(bp))
+    if (extraKeys && !known.includes(key))
+      throw new Error(
+        `${where}: unknown key "${key}" (known: ${known.join(", ")})`,
+      );
+  const branch = bp.branch ?? "main";
+  if (typeof branch !== "string" || !branch.trim())
+    throw new Error(`${where}.branch must be a branch name`);
+  if (bp.focus !== undefined && typeof bp.focus !== "boolean")
+    throw new Error(`${where}.focus must be true or false`);
+  return {
+    name,
+    repos: blueprintStrings(where, "repos", bp.repos),
+    branch,
+    autostartOff: blueprintStrings(where, "autostart_off", bp.autostart_off),
+    focus: bp.focus === true,
+  };
+}
+
+/**
+ * The distribution's workspace blueprint, validated: `defaults.workspace`
+ * (one workspace, `default`) or `defaults.workspaces` (named workspaces).
+ * Empty when neither is set. Both at once, or a malformed value, throws.
+ */
+export function readWorkspaceBlueprints(
+  config: DenConfig = readDenConfig(),
+): WorkspaceBlueprints {
+  const none: WorkspaceBlueprints = { shape: "none", workspaces: [] };
+  const defaults: unknown = config.defaults;
+  if (defaults === undefined || defaults === null) return none;
+  if (typeof defaults !== "object" || Array.isArray(defaults))
+    throw new Error(`defaults in ${DEN_CONFIG_PATH} must be a map`);
+  const { workspace, workspaces } = defaults as Record<string, unknown>;
+  if (workspace != null && workspaces != null)
+    throw new Error(
+      `${DEN_CONFIG_PATH} sets both defaults.workspace and defaults.workspaces: ` +
+        "use defaults.workspaces alone (name the default workspace `default` in it), " +
+        "or defaults.workspace alone for a single default workspace",
+    );
+  if (workspaces != null) {
+    if (typeof workspaces !== "object" || Array.isArray(workspaces))
+      throw new Error(
+        "defaults.workspaces must be a map: { <name>: { repos: [...], focus?: true } }",
+      );
+    const resolved = Object.entries(workspaces as Record<string, unknown>).map(
+      ([name, raw]) => {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name))
+          throw new Error(
+            `defaults.workspaces: "${name}" is not a valid workspace name (letters, digits, dots, dashes, underscores)`,
+          );
+        return resolveBlueprint(`defaults.workspaces.${name}`, name, raw, [
+          "focus",
+        ]);
+      },
+    );
+    const focused = resolved.filter((b) => b.focus);
+    if (focused.length > 1)
+      throw new Error(
+        `defaults.workspaces: only one workspace may set focus: true (got ${focused.map((b) => b.name).join(", ")})`,
+      );
+    return { shape: "multi", workspaces: resolved };
+  }
+  if (workspace != null)
+    return {
+      shape: "single",
+      workspaces: [
+        resolveBlueprint("defaults.workspace", "default", workspace, null),
+      ],
+    };
+  return none;
+}
+
 /** `web.service` with its defaults applied. */
 export interface ResolvedWebService {
   /** launchd label; also the plist's name in ~/Library/LaunchAgents. */

package/src/shared/edge/config.ts

@@ -31,6 +31,7 @@ import * as yaml from "yaml";
 import { brandSlug, defaultBrand } from "../brand.js";
 import { DEFAULT_PORT } from "../constants.js";
 import { getDistRoot } from "../paths.js";
+import { cachedRead } from "../read-cache.js";
 import { readManifestStacks } from "../stacks/config.js";
 import { getActiveWorkspaces } from "../environment-manager/workspaces.js";
 import { assertDomain } from "./render.js";
@@ -154,6 +155,21 @@ function manifestStackNames(): string[] {
 }
 
 export function readEdgeConfig(root: string = getDistRoot()): EdgeConfig {
+  // The web server reads this on every request (open links, health rows);
+  // reused for the read cache's TTL there, read fresh everywhere else. An
+  // error is cached as such: most instances have no edge block at all.
+  const r = cachedRead(`edge-config:${root}`, () => {
+    try {
+      return { config: computeEdgeConfig(root) };
+    } catch (e) {
+      return { error: (e as Error).message };
+    }
+  });
+  if ("error" in r) throw new Error(r.error);
+  return r.config;
+}
+
+function computeEdgeConfig(root: string): EdgeConfig {
   const { team: t, user: u } = layers(root);
   const team = (t.edge ?? {}) as RawEdge;
   const user = (u.edge ?? {}) as RawEdge;

package/src/shared/engine.ts

@@ -37,6 +37,24 @@ export function engineBin(name: string, engineRoot = getEngineRoot()): string {
   }
 }
 
+/**
+ * A file inside a package Den depends on (e.g. "tsx/dist/loader.mjs"): the
+ * nearest node_modules/<rel> at or above the engine root, or null.
+ */
+export function engineModuleFile(
+  rel: string,
+  engineRoot = getEngineRoot(),
+): string | null {
+  let dir = path.resolve(engineRoot);
+  for (;;) {
+    const candidate = path.join(dir, "node_modules", rel);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
 /** The tsx binary that runs Den's TypeScript sources. */
 export function tsxBin(): string {
   return engineBin("tsx");