@monster-orange/den 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,201 @@ 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.6] - 2026-11-04
+
+### Fixed
+
+- **`<cli> web restart` and `web down` act on our server from an older
+  Den.** A server from before 0.2.6 (no `root` in `/api/server-info`) run
+  from our root is ours, and 0.2.6-dev.0 classified it so, but stopping it
+  then looked for our pids by command line only: the entry point of this
+  engine, or one under the root. An older Den installed elsewhere, or a
+  hand-started server, matched neither, so `web restart` printed "OK ... web
+  is already running" and restarted nothing, and `web down` printed "OK ...
+  web is not running" while the server stayed up and bound. A server the
+  identity check finds ours is now stopped by the pid it reports, when that
+  pid listens on the port: `restart` replaces it and `down` frees the port,
+  with or without a `web.json` for it. web.json's root is compared after
+  resolving symlinks (`/var` and `/private/var` are one root).
+- **The MCP server serves nothing from another distribution's server.**
+  It read from whatever answered on its port. Before a tool reads, it now
+  checks `/api/server-info` as `web up` does; on another distribution's
+  server every tool answers `port <N> is in use by <product> at <root>; not
+  this distribution's server` and returns none of its data. A positive
+  check is trusted for 30s and made again after a connection error, so a
+  server that took over the port is noticed. A server that does not say
+  whose it is within 5s is not read from either.
+- **A mistyped `service` flag no longer installs.** `<cli> service install
+  --anything` ignored the flag and installed; a `service` subcommand now
+  refuses an argument it does not take, before running anything.
+- **`<cli> web up` no longer trusts whatever answers on its port.** With
+  `web.port` set to a port where another distribution's Den server ran
+  (another root, an older Den), `web up` printed "OK ... web is already
+  running" and stopped, and `web down` or `web restart` could SIGTERM that
+  server: with a linked engine its command line looks like ours.
+  `/api/server-info` now also returns `root` (the distribution root the
+  server serves) and `product`. `web up`, `web down` and `web restart`
+  compare both with their own, and on another distribution's server exit 1
+  with `port <N> is in use by <product> at <root>` and a hint to pick
+  another port (`--port`, or `web.port`). A server from before 0.2.6 has
+  no `root`: it is ours when it runs from our root (its working
+  directory), otherwise `port <N> is in use by another server (Den
+  <version>)`; anything else is "a non-Den server". `web down` also no
+  longer signals a process running from another root, even when the
+  server does not answer. `<cli> mcp connect` refuses to point an agent at
+  another distribution's server (and `mcp clients` names it), and `<cli>
+  service install` no longer reports "running" when another
+  distribution's server answers on the port.
+- **A repeat `<cli> workspace seed` says "already seeded".** Seeding a
+  workspace that already holds exactly the blueprint printed "Default
+  workspace ready" as if it had seeded again; it now prints `✓ Default
+  workspace already seeded — N repos (managed): nothing changed.` and
+  writes nothing (multi blueprint: `✓ N workspaces already seeded (a, b)`).
+  A seed over a workspace the user changed says it was "reset to the
+  blueprint".
+- **Counts read "1 repo", not "1 repos".** CLI output that counts repos,
+  workspaces, systems, files, profiles and tools uses one plural helper
+  (`src/shared/plural.ts`), also in place of "repo(s)".
+- **Spinners no longer loop forever on a 0-column terminal.** On a pty that
+  reports 0 columns (one nobody sized, as agent shells give), ora computed
+  an infinite number of lines to clear and never finished. A spinner now
+  animates only on a TTY with a known, non-zero width; otherwise it prints
+  plain lines (its text on start, then the result).
+
+### Added
+
+- **Health type `container`.** `health: { type: container, project: <compose
+  project>, service: <compose service> }` checks a compose container by its
+  `com.docker.compose.project` / `com.docker.compose.service` labels, or
+  `{ type: container, container_name: <name> }` any container by name. It
+  is answered from the one `docker ps` per health cycle the compose checks
+  already share (its format gains `{{.Names}}`, and it no longer filters to
+  compose containers), so N container checks add no docker call, in the
+  web health row and in `<cli> status` (22 checks, 17 compose and 5
+  container: 1 docker call per cycle). A running container with a
+  healthcheck is its health (healthy up, unhealthy down, starting
+  pending), one without is up, and no matching container is down. When
+  docker gives no listing it says what a compose check says, through the
+  same code: a failed `docker ps` is unknown (`ok: null`, the reason in
+  `error`) on every cycle, never down; a listing past its budget is
+  pending (`pending: true`), down only when that repeats. Of several matches the best counts:
+  healthy, then running. `/api/health` rows show it as `check: "container
+  <project>/<service>"`. `<cli> validate` requires `project` + `service` or
+  `container_name` (not both, not one of the pair alone, no other type's
+  keys) and says which. See docs/distributions.md, "Health checks".
+- **`<cli> service install --plan`.** Read-only: prints the label, the
+  plist path, the log file, the roots, whose server answers on `web.port`
+  (ours, free, or `port <N> is in use by <product> at <root>`) and the
+  plist install would write; writes nothing and never calls launchctl.
+  Exits 1 when the port is another distribution's. `<cli> service status`
+  also names another distribution's server on the port.
+
+### Migrations
+
+- None required. Optional: a `type: shell` check that runs `docker ps` to
+  find a container (`test -n "$(docker ps -q --filter
+  label=com.docker.compose.project=X --filter
+  label=com.docker.compose.service=Y)"`) can become `{ type: container,
+  project: X, service: Y }`: no process or docker call of its own, and it
+  reads the container's healthcheck.
+
+## [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

package/docs/distributions.md

@@ -126,6 +126,83 @@ is never mistaken for another repo's service. An alias that names more than
 one service is an error that lists them (`"worker" is ambiguous in workspace
 "default": one/worker, two/worker`); name one of them.
 
+## Health checks
+
+A service declares its health per environment under `health`, in one of
+three types:
+
+```yaml
+services:
+  api:
+    health:
+      local: { url: http://shop-api/healthz } # http (the default type)
+  db:
+    health:
+      local: { type: shell, cmd: pg_isready -h localhost } # exit 0 is up
+  cache:
+    health:
+      local: { type: container, project: shop-main, service: cache }
+```
+
+`label` (optional, any type) is shown in the UI instead of the URL or the
+command. A compose repo with no declared check gets Den's own stack check
+(`<cli> stack health`), answered in-process.
+
+**`type: container`** asks whether a container is up, from the one
+`docker ps` listing a health cycle already makes for the compose checks: it
+adds no docker call however many container checks there are, in the web
+health row and in `<cli> status`. It matches a compose container by its
+`com.docker.compose.project` and `com.docker.compose.service` labels
+(`project` + `service`), or any container by name (`container_name`, for one
+compose does not run). One or the other, never both:
+
+| What the listing shows                    | Verdict                                                 |
+| ----------------------------------------- | ------------------------------------------------------- |
+| running, healthcheck `healthy`            | up                                                      |
+| running, healthcheck `unhealthy`          | down                                                    |
+| running, healthcheck `starting`           | pending                                                 |
+| running, no healthcheck                   | up                                                      |
+| not running (exited, created, restarting) | down                                                    |
+| no matching container                     | down (`<project>/<service>: no container`)              |
+| `docker ps` fails (daemon down)           | unknown (`ok: null`, the reason in `error`), never down |
+| `docker ps` past its 5s budget            | pending (`ok: null`, `pending: true`)                   |
+| more than one match                       | the best one: healthy, then running                     |
+
+When docker gives no listing, a container check says what a compose check
+says, through the same code: docker state unknown is not "not running", so
+a failed `docker ps` is `ok: null` however many cycles it lasts, in the
+health row and in `<cli> status`. Only a listing that runs past its budget
+is `pending`, and like any check with no answer it is down when that
+repeats on the next cycle. A container whose healthcheck is still starting
+stays pending. In
+`/api/health` the row's `check` reads `container <project>/<service>` (or
+`container <name>`).
+
+Before, a container check was a shell check that ran docker itself, one
+process and one docker call per check per cycle:
+
+```yaml
+health:
+  local:
+    type: shell
+    cmd: test -n "$(docker ps -q --filter label=com.docker.compose.project=shop-main --filter label=com.docker.compose.service=cache)"
+```
+
+After:
+
+```yaml
+health:
+  local: { type: container, project: shop-main, service: cache }
+```
+
+which also reads the container's own healthcheck (the shell form only saw
+that a container existed, running or not).
+
+**Validation.** `<cli> validate` rejects a container check with neither
+`project` + `service` nor `container_name`, with only one of `project` and
+`service`, with both forms at once, or with a key of another type (`cmd`,
+`url`), and says which.
+
 ## Placement
 
 Each service says where it runs, per environment: `local` (on this machine,
@@ -327,6 +404,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
@@ -401,6 +526,7 @@ it exits:
 
 ```bash
 ./bin/acme service install     # install (or refresh) and start it
+./bin/acme service install --plan  # what install would do; writes and loads nothing
 ./bin/acme service status      # launchd's view: state, pid, last exit code
 ./bin/acme service print       # the LaunchAgent plist it would install; installs nothing
 ./bin/acme service uninstall   # stop it and remove the LaunchAgent
@@ -429,6 +555,15 @@ answers empty for a few seconds while it starts). If it has not answered
 within 30s, it says `installed but not answering yet: check <logs dir>` and
 exits 1.
 
+`install --plan` is read-only: it prints the label, the plist path
+(`~/Library/LaunchAgents/<label>.plist`), the log file, the distribution and
+engine roots, whose server answers on `web.port` (this distribution's, free,
+or `port <N> is in use by <product> at <root>; not this distribution's
+server`), and the plist install would write. It writes nothing, never calls
+launchctl, and exits 1 when the port is another distribution's. Any other
+argument to a `service` subcommand is an error, so a mistyped `--plan` never
+installs. `status` also names another distribution's server on the port.
+
 `<cli> service` runs the installer script below, which you can also run
 yourself, from the distribution root:
 
@@ -461,6 +596,13 @@ set of guards. It never starts the web server; if it is not running, every
 tool answers with the command that starts it (`./bin/acme web up`). stdout
 carries only the protocol; diagnostics go to stderr.
 
+It reads only from this distribution's server. Before serving a tool it
+checks `/api/server-info` (root and product, or for a server from before
+0.2.6 its working directory), trusts a positive answer for 30s, and checks
+again after a connection error. When another distribution's server answers
+on the port, every tool says `port <N> is in use by <product> at <root>; not
+this distribution's server` and returns none of its data.
+
 The web server keeps running the Den it started with until it is restarted,
 so after an upgrade it can be older than the MCP server. When a tool's route
 answers 404, the MCP server reads the web server's version from
@@ -544,22 +686,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, or `container <project>/<service>`); `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.4",
+  "version": "0.2.6",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/src/pillars/security/discover.ts

@@ -107,7 +107,7 @@ export function autoSecurityTargets(
     if (!runsLocally) continue;
     const hosts: SecurityServiceConfig["hosts"] = {};
     for (const [env, h] of Object.entries(s.config?.health ?? {})) {
-      if (!h || h.type === "shell" || !/^https?:\/\//.test(h.url)) continue;
+      if (!h || !("url" in h) || !/^https?:\/\//.test(h.url)) continue;
       hosts[env as keyof typeof hosts] = [new URL(h.url).origin + "/"];
     }
     if (Object.keys(hosts).length === 0) continue;

package/src/pillars/smoke/setup-global.ts

@@ -11,6 +11,7 @@ import { discoverRepos, resolveRepoPath, resolveService } from "./discover.js";
 import { stageSmokeTree } from "./staging.js";
 import type { Environment } from "../../shared/types/index.js";
 import { getDistRoot } from "../../shared/paths.js";
+import { plural } from "../../shared/plural.js";
 
 // Den-root anchored, NOT process.cwd() — bulk writer of .smoke-run (see setup.ts).
 const PROJECT_ROOT = getDistRoot();
@@ -116,7 +117,7 @@ async function main() {
   );
 
   console.log(
-    `\n  Total: ${total} smoke test file(s) staged across ${repos.length} repo(s)\n`,
+    `\n  Total: ${plural(total, "smoke test file")} staged across ${plural(repos.length, "repo")}\n`,
   );
 }
 

package/src/scripts/configure-aws-profiles.ts

@@ -17,6 +17,7 @@ import type { Environment } from "../shared/types/index.js";
 import { getDistRoot } from "../shared/paths.js";
 
 import { product } from "../shared/product.js";
+import { plural } from "../shared/plural.js";
 // Den-root anchored: WRITES config/local/aws-profiles.json, and the reader
 // (shared/environment/aws-profiles.ts) already anchors at getDistRoot().
 const ROOT = getDistRoot();
@@ -54,7 +55,7 @@ async function main() {
     );
   } else {
     console.log(
-      `  Found ${profiles.length} profile(s): ${profiles.join(", ")}\n`,
+      `  Found ${plural(profiles.length, "profile")}: ${profiles.join(", ")}\n`,
     );
   }
 

package/src/scripts/register-repos.ts

@@ -29,6 +29,7 @@ import {
 } from "../shared/environment-manager/default-workspace.js";
 
 import { product } from "../shared/product.js";
+import { plural } from "../shared/plural.js";
 // Anchored to the den root, NOT process.cwd() — this script WRITES
 // config/local/* and a cwd-derived root once put den files in another repo.
 const ROOT = getDistRoot();
@@ -179,7 +180,7 @@ async function legacyScanAndSelect(): Promise<void> {
         fs.readFileSync(REGISTERED_FILE, "utf-8"),
       ) as string[];
       console.log(
-        `  Current: ${existing.length} repo(s) registered for testing\n`,
+        `  Current: ${plural(existing.length, "repo")} registered for testing\n`,
       );
     } catch {
       /* corrupt file — start fresh */
@@ -223,7 +224,7 @@ async function legacyScanAndSelect(): Promise<void> {
   fs.writeFileSync(REGISTERED_FILE, JSON.stringify(selected, null, 2) + "\n");
 
   console.log(
-    `\n  Registered ${selected.length} repo(s) → config/local/registered-repos.json`,
+    `\n  Registered ${plural(selected.length, "repo")} → config/local/registered-repos.json`,
   );
   console.log("  Run `make register-repos` again at any time to update.\n");
 }
@@ -282,7 +283,7 @@ async function main(): Promise<void> {
     console.log(
       "  Local Dev is enabled but no workspace exists yet. Your first" +
         ` \`${product().cli}\` command\n  seeds the default workspace with every standard` +
-        ` system repo, all managed\n  out of the box (${plan.repos.length} repos):\n`,
+        ` system repo, all managed\n  out of the box (${plural(plan.repos.length, "repo")}):\n`,
     );
     console.log(`    ${plan.repos.join(", ")}\n`);
     console.log(

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;