@monster-orange/den 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,104 @@ 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

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,
@@ -449,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
@@ -477,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:
 
@@ -509,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
@@ -592,22 +686,22 @@ guard off.
 
 Read tools (always registered):
 
-| 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                                                                                                 |
+| 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.5",
+  "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/environment-manager/default-workspace.ts

@@ -117,6 +117,53 @@ export function defaultWorkspaceHasServices(): boolean {
   );
 }
 
+function sameEntry(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) return false;
+  const ka = Object.keys(a).sort();
+  const kb = Object.keys(b).sort();
+  return (
+    ka.length === kb.length &&
+    ka.every(
+      (k, i) =>
+        k === kb[i] &&
+        sameEntry(
+          (a as Record<string, unknown>)[k],
+          (b as Record<string, unknown>)[k],
+        ),
+    )
+  );
+}
+
+/**
+ * Whether seeding now would change nothing: every workspace the blueprint
+ * seeds holds exactly what seeding writes (same repos, all managed on the
+ * blueprint's branch, same autostart defaults), records the blueprint as
+ * applied, and (multi blueprint) is active. A workspace the user changed
+ * since (a repo switched to a local checkout, one added or removed) is not
+ * "already seeded": seeding would reset it.
+ */
+export function blueprintAlreadySeeded(
+  file: WorkspacesFile = readWorkspacesFile(),
+): boolean {
+  const bps = blueprintWorkspaces();
+  if (bps.length === 0) return false;
+  const multi = isMultiBlueprint();
+  return bps.every((bp) => {
+    const name = multi ? bp.name : "default";
+    const ws = file.workspaces[name];
+    if (!ws) return false;
+    if (multi && !(file.active ?? []).includes(name)) return false;
+    const applied = ws.seeded_repos ?? [];
+    if (
+      applied.length !== bp.repos.length ||
+      bp.repos.some((r, i) => applied[i] !== r)
+    )
+      return false;
+    return sameEntry(ws.services ?? {}, blueprintServices(bp));
+  });
+}
+
 /**
  * Seed (or reset) the `default` workspace from the blueprint — every repo as a
  * bare, first-class managed entry on `branch` — and ensure the catalog has

package/src/shared/environment-manager/health.ts

@@ -12,7 +12,10 @@ import { readEdgeConfig } from "../edge/config.js";
 import {
   composeHealth,
   composeHealthTarget,
+  containerHealth,
   type ComposeHealthTarget,
+  type ComposeVerdict,
+  type ContainerHealthTarget,
 } from "../stacks/compose-health.js";
 import * as fs from "fs";
 import * as os from "os";
@@ -38,7 +41,11 @@ import {
   listWorkspaceServices,
   readManifestAnyBranch,
 } from "./workspaces.js";
-import type { ResolvedService, ServiceCatalog } from "../types/index.js";
+import type {
+  ResolvedService,
+  ServiceCatalog,
+  ServiceHealthConfig,
+} from "../types/index.js";
 import type { Environment } from "../types/index.js";
 
 import { product } from "../product.js";
@@ -595,12 +602,39 @@ export async function pingShellCheck(
   compose: ComposeHealthTarget | null,
 ): Promise<PingResult> {
   if (!compose || cmd !== compose.cmd) return pingShell(cmd, extraEnv, cwd);
-  const v = await composeHealth(compose);
+  return verdictPing(await composeHealth(compose));
+}
+
+/**
+ * A compose or container verdict as a ping. One conversion for both, so a
+ * docker that could not be asked reads the same: `ok: null`, pending (and so
+ * down on a repeat) only when the listing ran past its budget.
+ */
+function verdictPing(v: ComposeVerdict): PingResult {
   if (v.ok === true) return { ok: true };
   if (v.ok === false) return { ok: false, error: v.detail };
   return { ok: null, error: v.detail, ...(v.pending ? { pending: true } : {}) };
 }
 
+/**
+ * Run a `type: container` check: answered in-process from the shared docker
+ * listing (the one Den's compose checks use), never a docker call of its own.
+ */
+export async function pingContainerCheck(
+  target: ContainerHealthTarget,
+): Promise<PingResult> {
+  return verdictPing(await containerHealth(target));
+}
+
+/** The container a `type: container` health config names. */
+export function containerTarget(
+  h: Extract<ServiceHealthConfig, { type: "container" }>,
+): ContainerHealthTarget {
+  return h.container_name !== undefined
+    ? { container_name: h.container_name }
+    : { project: h.project, service: h.service };
+}
+
 /** A ping result as a ServiceHealthResult health state. */
 export function healthState(r: PingResult): ServiceHealthResult["health"] {
   return r.ok === true ? "ok" : r.ok === false ? "error" : "pending";
@@ -710,13 +744,15 @@ export async function checkServiceHealth(
   const result = await pingTwiceOnTimeout(() =>
     healthCfg.type === "shell"
       ? pingShellCheck(healthCfg.cmd, {}, resolved.repoPath, compose)
-      : pingHttp(
-          healthCfg.url,
-          env === "local" && plan.placement.runs !== "remote"
-            ? HEALTH_CHECK_TIMEOUT_MS
-            : HOSTED_HEALTH_CHECK_TIMEOUT_MS,
-          plan.expect,
-        ),
+      : healthCfg.type === "container"
+        ? pingContainerCheck(containerTarget(healthCfg))
+        : pingHttp(
+            healthCfg.url,
+            env === "local" && plan.placement.runs !== "remote"
+              ? HEALTH_CHECK_TIMEOUT_MS
+              : HOSTED_HEALTH_CHECK_TIMEOUT_MS,
+            plan.expect,
+          ),
   );
 
   return {

package/src/shared/manifest/placement.ts

@@ -52,7 +52,7 @@ export type IsProduction = (env: string) => boolean;
 const LOCAL = "local";
 
 function isHttp(h: ServiceHealthConfig | undefined): h is { url: string } {
-  return !!h && h.type !== "shell" && typeof h.url === "string";
+  return !!h && "url" in h && typeof h.url === "string";
 }
 
 function hasCommands(

package/src/shared/manifest/schema.ts

@@ -32,7 +32,54 @@ const commandDef = z.union([
 //   { url: "http://..." }                         — implicit HTTP
 //   { type: "http", url: "http://..." }           — explicit HTTP
 //   { type: "shell", cmd: "pg_isready ..." }      — shell
+//   { type: "container", project, service }       — a compose container
+//   { type: "container", container_name }         — a container by name
+const CONTAINER_HEALTH_KEYS = new Set([
+  "type",
+  "project",
+  "service",
+  "container_name",
+  "label",
+]);
+export const CONTAINER_HEALTH_SHAPE =
+  'container checks need "project" and "service" (compose labels), or "container_name"';
+const containerHealth = z
+  .object({
+    type: z.literal("container"),
+    project: z.string().min(1).optional(),
+    service: z.string().min(1).optional(),
+    container_name: z.string().min(1).optional(),
+    label: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((h, ctx) => {
+    const unknown = Object.keys(h).filter((k) => !CONTAINER_HEALTH_KEYS.has(k));
+    if (unknown.length)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `unknown key${unknown.length > 1 ? "s" : ""} ${unknown.map((k) => `"${k}"`).join(", ")} in a container check: ${CONTAINER_HEALTH_SHAPE}`,
+      });
+    const byLabels = h.project !== undefined || h.service !== undefined;
+    const byName = h.container_name !== undefined;
+    if (byLabels && byName)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `a container check matches by "project"/"service" or by "container_name", not both`,
+      });
+    else if (byLabels && (h.project === undefined || h.service === undefined))
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: `a container check by compose labels needs both "project" and "service"`,
+      });
+    else if (!byLabels && !byName)
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: CONTAINER_HEALTH_SHAPE,
+      });
+  });
+
 const healthConfig = z.union([
+  containerHealth,
   // Shell health check — must have cmd
   z.object({
     type: z.literal("shell"),

package/src/shared/manifest/service-links.ts

@@ -47,7 +47,7 @@ export function openUrlFor(
   const declared = httpUrl(svc.urls?.[env]);
   if (declared) return declared;
   const health = svc.health?.[env];
-  if (!health || ("type" in health && health.type === "shell")) return null;
+  if (!health || !("url" in health)) return null;
   return httpOrigin((health as { url?: string }).url);
 }
 

package/src/shared/manifest/validate-manifest.ts

@@ -57,7 +57,7 @@ function suggestionFor(issue: z.ZodIssue): string | undefined {
 
   // health with missing url/cmd
   if (pathStr.includes("health")) {
-    return 'HTTP checks need "url"; shell checks need "type: shell" and "cmd"';
+    return 'HTTP checks need "url"; shell checks need "type: shell" and "cmd"; container checks need "type: container" and "project" + "service", or "container_name"';
   }
 
   return undefined;

package/src/shared/plural.ts

@@ -0,0 +1,13 @@
+/**
+ * Counts in output: "1 repo", "3 repos", never "1 repos" or "repo(s)".
+ */
+
+/** `word` in the form `n` takes: "repo" for 1, "repos" (or `many`) otherwise. */
+export function noun(n: number, word: string, many = `${word}s`): string {
+  return n === 1 ? word : many;
+}
+
+/** `n` and its noun: plural(1, "repo") → "1 repo", plural(2, "repo") → "2 repos". */
+export function plural(n: number, word: string, many?: string): string {
+  return `${n} ${noun(n, word, many)}`;
+}

package/src/shared/service-url.ts

@@ -24,11 +24,8 @@ function healthUrlForConfig(healthConfig?: ServiceHealthConfig): string | null {
     return null;
   }
 
-  if ("type" in healthConfig && healthConfig.type === "shell") {
-    return null;
-  }
-
-  return healthConfig.url;
+  // Shell and container checks have no URL.
+  return "url" in healthConfig ? healthConfig.url : null;
 }
 
 function normalizeServiceBaseUrl(