@monster-orange/den 0.2.4 → 0.2.6

package/src/ui/cli/mcp-connect.ts

@@ -25,6 +25,13 @@ import { product } from "../../shared/product.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import { DEFAULT_PORT } from "../../shared/constants.js";
+import {
+  classifyServerInfo,
+  foreignServerMessage,
+  ownServer,
+  pickAnotherPortHint,
+  type OwnServer,
+} from "./server-identity.js";
 import { readDenConfig, readMcpConfig } from "../../shared/den-config.js";
 
 export const MCP_CONNECT_SUBCOMMANDS = [
@@ -205,6 +212,8 @@ export const WEB_PROBE_TIMEOUT_MS = 1500;
 /** What a probe of the web server's /api/server-info found. */
 export type WebProbe =
   | { kind: "up"; version?: string }
+  /** Another distribution's server (see server-identity.ts). */
+  | { kind: "foreign"; who: string }
   /** Something accepted the connection but sent no answer in time. */
   | { kind: "timeout" }
   /** Nothing answered: connection refused, or not the web server. */
@@ -214,13 +223,15 @@ export async function probeWebServer(
   url: string,
   timeoutMs: number = WEB_PROBE_TIMEOUT_MS,
   fetchImpl: typeof fetch = fetch,
+  own: OwnServer = ownServer(),
 ): Promise<WebProbe> {
   try {
     const r = await fetchImpl(`${url}/api/server-info`, {
       signal: AbortSignal.timeout(timeoutMs),
     });
-    const info = (await r.json()) as { version?: string };
-    return { kind: "up", version: info.version };
+    const id = classifyServerInfo(await r.json(), own);
+    if (id.kind === "foreign") return { kind: "foreign", who: id.who };
+    return { kind: "up", version: id.kind === "ours" ? id.version : undefined };
   } catch (e) {
     return (e as Error).name === "TimeoutError"
       ? { kind: "timeout" }
@@ -252,6 +263,11 @@ export function webServerMessage(
       chalk.green(`web server up at ${url}`) +
       (probe.version ? chalk.gray(` (Den ${probe.version})`) : "")
     );
+  if (probe.kind === "foreign")
+    return chalk.yellow(
+      `${foreignServerMessage(Number(new URL(url).port), probe.who)}: ` +
+        `agents would read another distribution; ${pickAnotherPortHint(opts.cli)}`,
+    );
   const svc = `\`${opts.cli} service status\``;
   if (probe.kind === "timeout") {
     const secs = (opts.timeoutMs ?? WEB_PROBE_TIMEOUT_MS) / 1000;
@@ -271,7 +287,7 @@ export function webServerMessage(
   );
 }
 
-async function webServerLine(port?: number): Promise<string> {
+function webUrl(port?: number): string {
   let p = port;
   if (p === undefined) {
     try {
@@ -280,8 +296,12 @@ async function webServerLine(port?: number): Promise<string> {
       p = DEFAULT_PORT;
     }
   }
-  const url = `http://localhost:${p}`;
-  return webServerMessage(await probeWebServer(url), url, {
+  return `http://localhost:${p}`;
+}
+
+async function webServerLine(port?: number, probe?: WebProbe): Promise<string> {
+  const url = webUrl(port);
+  return webServerMessage(probe ?? (await probeWebServer(url)), url, {
     cli: product().cli,
     asService: webRunsAsService(),
   });
@@ -382,6 +402,17 @@ export async function runMcpConnect(argv: string[]): Promise<number> {
     return 1;
   }
 
+  // Never point agents at another distribution's server.
+  if (!remove) {
+    const probe = await probeWebServer(webUrl(flags.port));
+    if (probe.kind === "foreign") {
+      console.error(
+        `  ${chalk.red("✗")} ${await webServerLine(flags.port, probe)}`,
+      );
+      return 1;
+    }
+  }
+
   let failed = 0;
   for (const c of targets) {
     if (!c.scopes.includes(scope)) {

package/src/ui/cli/server-identity.ts

@@ -0,0 +1,233 @@
+/**
+ * Whether the web server answering on a port is THIS distribution's.
+ *
+ * Several distributions can run a Den web server on one machine (each with
+ * its own root), so something answering on the configured port is not
+ * proof it is ours: `<cli> web up` once printed "already running" for
+ * another distribution's server, and `web down` could have signalled it.
+ * /api/server-info names the distribution root it serves and the product
+ * (since 0.2.6); every command that acts on "our" server asks this module
+ * first and refuses to act on a foreign one.
+ *
+ * A server from before 0.2.6 has no `root`. It does report its pid, and it
+ * runs with its distribution root as its working directory (`web up` and
+ * the launchd service both start it there), so that decides instead.
+ */
+import { spawnSync } from "child_process";
+import * as fs from "fs";
+import * as http from "http";
+import * as path from "path";
+import { CLI_SPAWN_TIMEOUT_MS } from "../../shared/constants.js";
+import { getDistRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+
+/** The distribution a command acts for. */
+export interface OwnServer {
+  root: string;
+  product: string;
+}
+
+/** What answers on a port, from this distribution's point of view. */
+export type ServerIdentity =
+  /** Nothing listens there. */
+  | { kind: "none" }
+  /** Something accepted the connection but sent no answer in time. */
+  | { kind: "unresponsive" }
+  /**
+   * `pid`: the server's own pid (server-info reports it). Identity is what
+   * makes it ours, so a stop signals this pid even when its command line
+   * names no entry point we recognise (an older Den installed elsewhere, a
+   * hand-started server).
+   */
+  | { kind: "ours"; version?: string; pid?: number }
+  /** Someone else's server. `who` reads "acme-ops at /srv/acme-ops". */
+  | { kind: "foreign"; who: string };
+
+/** How long one probe of /api/server-info may take. */
+export const SERVER_INFO_TIMEOUT_MS = 1_500;
+
+/** This distribution: its root and product name. */
+export function ownServer(): OwnServer {
+  return { root: getDistRoot(), product: product().name };
+}
+
+function canonical(p: string): string {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return path.resolve(p);
+  }
+}
+
+export function samePath(a: string, b: string): boolean {
+  return canonical(a) === canonical(b);
+}
+
+/** A process's working directory (lsof), or null when it can't be read. */
+export function processCwd(pid: number): string | null {
+  const r = spawnSync("lsof", ["-a", "-p", String(pid), "-d", "cwd", "-Fn"], {
+    encoding: "utf-8",
+    timeout: CLI_SPAWN_TIMEOUT_MS,
+  });
+  if (r.status !== 0 || typeof r.stdout !== "string") return null;
+  const line = r.stdout.split(/\r?\n/).find((l) => l.startsWith("n"));
+  return line ? line.slice(1) : null;
+}
+
+/**
+ * Classify a parsed /api/server-info body. `cwdOf` reads a pid's working
+ * directory, for servers from before `root` was reported.
+ */
+export function classifyServerInfo(
+  body: unknown,
+  own: OwnServer,
+  cwdOf: (pid: number) => string | null = processCwd,
+): ServerIdentity {
+  if (body === null || typeof body !== "object" || Array.isArray(body))
+    return { kind: "foreign", who: "a non-Den server" };
+  const info = body as Record<string, unknown>;
+  const version = typeof info.version === "string" ? info.version : undefined;
+  const prod = typeof info.product === "string" ? info.product : undefined;
+  const pid =
+    typeof info.pid === "number" && Number.isInteger(info.pid) && info.pid > 0
+      ? info.pid
+      : undefined;
+  const ours = (): ServerIdentity => ({
+    kind: "ours",
+    ...(version !== undefined ? { version } : {}),
+    ...(pid !== undefined ? { pid } : {}),
+  });
+
+  if (typeof info.root === "string" && info.root) {
+    if (
+      samePath(info.root, own.root) &&
+      (prod === undefined || prod === own.product)
+    )
+      return ours();
+    return {
+      kind: "foreign",
+      who: `${prod ?? "another server"} at ${info.root}`,
+    };
+  }
+
+  if (pid !== undefined) {
+    const cwd = cwdOf(pid);
+    if (cwd && samePath(cwd, own.root)) return ours();
+  }
+  if (version === undefined && info.pid === undefined)
+    return { kind: "foreign", who: "a non-Den server" };
+  return {
+    kind: "foreign",
+    who: `another server${version ? ` (Den ${version})` : ""}`,
+  };
+}
+
+/** Classify a raw /api/server-info answer (status and body text). */
+export function classifyServerInfoResponse(
+  statusCode: number,
+  text: string,
+  own: OwnServer,
+  cwdOf?: (pid: number) => string | null,
+): ServerIdentity {
+  // A server still starting answers 200 with an empty body: not up yet.
+  if (statusCode >= 200 && statusCode < 300 && text.trim() === "")
+    return { kind: "unresponsive" };
+  if (statusCode < 200 || statusCode >= 300)
+    return { kind: "foreign", who: "a non-Den server" };
+  let body: unknown;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return { kind: "foreign", who: "a non-Den server" };
+  }
+  return classifyServerInfo(body, own, cwdOf);
+}
+
+/**
+ * GET /api/server-info on `port` and say whose server answered. `host`: the
+ * name the caller itself connects to (the MCP server's `localhost`).
+ */
+export function identifyServer(
+  port: number,
+  own: OwnServer = ownServer(),
+  timeoutMs: number = SERVER_INFO_TIMEOUT_MS,
+  host: string = "127.0.0.1",
+): Promise<ServerIdentity> {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v: ServerIdentity): void => {
+      if (settled) return;
+      settled = true;
+      resolve(v);
+    };
+    const req = http.get(
+      {
+        host,
+        port,
+        path: "/api/server-info",
+        timeout: timeoutMs,
+        agent: false,
+      },
+      (res) => {
+        let text = "";
+        res.setEncoding("utf-8");
+        res.on("data", (chunk: string) => {
+          text += chunk;
+          if (text.length > 1024 * 1024) {
+            req.destroy();
+            finish({ kind: "foreign", who: "a non-Den server" });
+          }
+        });
+        res.on("end", () =>
+          finish(classifyServerInfoResponse(res.statusCode ?? 0, text, own)),
+        );
+        res.on("error", () => finish({ kind: "unresponsive" }));
+      },
+    );
+    req.on("timeout", () => {
+      req.destroy();
+      finish({ kind: "unresponsive" });
+    });
+    req.on("error", (e: NodeJS.ErrnoException) =>
+      finish(
+        e.code === "ECONNREFUSED" ? { kind: "none" } : { kind: "unresponsive" },
+      ),
+    );
+  });
+}
+
+/** "port 7001 is in use by acme-ops at /srv/acme-ops". */
+export function foreignServerMessage(port: number, who: string): string {
+  return `port ${port} is in use by ${who}`;
+}
+
+/** How to get out of the way: another port, for once or for good. */
+export function pickAnotherPortHint(cli: string = product().cli): string {
+  return (
+    `pick another port: \`${cli} web up --port <n>\` for once, or set ` +
+    `web.port in config/local/user.yml (yours) or ${product().configFile} (the team's)`
+  );
+}
+
+/** The error a command raises instead of acting on a foreign server. */
+export class ForeignServerError extends Error {
+  constructor(
+    readonly port: number,
+    readonly who: string,
+  ) {
+    super(
+      `${foreignServerMessage(port, who)}\n  Hint: ${pickAnotherPortHint()}`,
+    );
+    this.name = "ForeignServerError";
+  }
+}
+
+/** Throw ForeignServerError when `port` is served by another distribution. */
+export async function refuseForeignServer(
+  port: number,
+  own: OwnServer = ownServer(),
+): Promise<ServerIdentity> {
+  const id = await identifyServer(port, own);
+  if (id.kind === "foreign") throw new ForeignServerError(port, id.who);
+  return id;
+}

package/src/ui/cli/service-command.ts

@@ -9,6 +9,11 @@
  * `install` (which also restarts a running service) says the service is
  * running only once the web server answers /api/server-info with JSON: a
  * fresh server takes a few seconds to start, and answers empty until then.
+ *
+ * `install --plan` is read-only: it prints the plist install would write
+ * (install.sh print), the label, the paths and whose server answers on the
+ * port, and writes and loads nothing; exit 1 when that server is foreign.
+ * `status` also names a foreign server on the port.
  */
 import { spawnSync } from "child_process";
 import * as os from "os";
@@ -20,6 +25,17 @@ import {
 } from "../../shared/den-config.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import { getDistRoot, getEngineRoot } from "../../shared/paths.js";
+import { product } from "../../shared/product.js";
+import {
+  classifyServerInfo,
+  ForeignServerError,
+  foreignServerMessage,
+  identifyServer,
+  ownServer,
+  pickAnotherPortHint,
+  type OwnServer,
+  type ServerIdentity,
+} from "./server-identity.js";
 
 /** Runs a command with extra env vars; returns its exit code. */
 export type ServiceRunner = (
@@ -30,6 +46,14 @@ export type ServiceRunner = (
 
 const SUBCOMMANDS = ["install", "status", "print", "uninstall"] as const;
 
+/** The flags each subcommand takes; any other is refused before acting. */
+const SUBCOMMAND_FLAGS: Record<(typeof SUBCOMMANDS)[number], string[]> = {
+  install: ["--plan"],
+  status: [],
+  print: [],
+  uninstall: [],
+};
+
 const defaultRunner: ServiceRunner = (cmd, args, env) =>
   spawnSync(cmd, args, { stdio: "inherit", env: { ...process.env, ...env } })
     .status ?? 1;
@@ -39,12 +63,15 @@ export const READY_TIMEOUT_MS = 30_000;
 
 /**
  * Poll `url` until it answers 2xx with a JSON object, or `timeoutMs` passes.
- * Each attempt is bounded too, so a hung connection cannot outlast it.
+ * Each attempt is bounded too, so a hung connection cannot outlast it. A
+ * server that is not `own`'s (another distribution's, on the same port) is
+ * never "running": that throws ForeignServerError at once.
  */
 export async function waitForServerInfo(
   url: string,
   timeoutMs: number = READY_TIMEOUT_MS,
   intervalMs = 500,
+  own: OwnServer = ownServer(),
 ): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   for (;;) {
@@ -56,9 +83,15 @@ export async function waitForServerInfo(
       });
       if (res.ok) {
         const body: unknown = JSON.parse(await res.text());
-        if (body !== null && typeof body === "object") return true;
+        if (body !== null && typeof body === "object") {
+          const id = classifyServerInfo(body, own);
+          if (id.kind === "foreign")
+            throw new ForeignServerError(Number(new URL(url).port), id.who);
+          return true;
+        }
       }
-    } catch {
+    } catch (e) {
+      if (e instanceof ForeignServerError) throw e;
       /* not up yet: refused, empty or partial body */
     }
     await new Promise((r) => setTimeout(r, intervalMs));
@@ -74,9 +107,32 @@ export interface ServiceDeps {
   platform?: NodeJS.Platform;
   /** The web UI port (default: config web.port). */
   webPort?: number;
-  /** Readiness poller (default: waitForServerInfo). */
-  waitReady?: (url: string, timeoutMs: number) => Promise<boolean>;
+  /**
+   * Readiness poller (default: waitForServerInfo). Throws
+   * ForeignServerError when another distribution's server answers.
+   */
+  waitReady?: (
+    url: string,
+    timeoutMs: number,
+    own: OwnServer,
+  ) => Promise<boolean>;
   log?: (line: string) => void;
+  /** Whose server answers on a port (default: identifyServer). */
+  identify?: (port: number, own: OwnServer) => Promise<ServerIdentity>;
+}
+
+/** One line on whose server answers on `port`. */
+export function identityLine(port: number, id: ServerIdentity): string {
+  switch (id.kind) {
+    case "none":
+      return `port ${port}: free (nothing listening)`;
+    case "unresponsive":
+      return `port ${port}: something accepted the connection but did not answer`;
+    case "ours":
+      return `port ${port}: this distribution's server${id.version ? ` (Den ${id.version})` : ""}${id.pid ? `, pid ${id.pid}` : ""}`;
+    case "foreign":
+      return `${foreignServerMessage(port, id.who)}; not this distribution's server`;
+  }
 }
 
 /** Run `service <sub>`; returns the exit code. */
@@ -84,13 +140,30 @@ export async function cmdService(
   args: string[],
   deps: ServiceDeps = {},
 ): Promise<number> {
-  const sub = args[0];
+  const sub = args[0] as (typeof SUBCOMMANDS)[number] | undefined;
   if (!(SUBCOMMANDS as readonly string[]).includes(sub ?? ""))
     throw new Error(
       `${sub ? `Unknown service command "${sub}". ` : ""}Use: ${SUBCOMMANDS.join(" | ")}`,
     );
-  // print only writes the plist; the rest talk to launchd.
-  if (sub !== "print" && (deps.platform ?? process.platform) !== "darwin")
+  // A typo'd --plan must not install for real.
+  const extra = args
+    .slice(1)
+    .filter((a) => !SUBCOMMAND_FLAGS[sub!].includes(a));
+  if (extra.length)
+    throw new Error(
+      `service ${sub}: unknown argument${extra.length > 1 ? "s" : ""} ${extra.join(" ")}` +
+        (SUBCOMMAND_FLAGS[sub!].length
+          ? ` (takes ${SUBCOMMAND_FLAGS[sub!].join(", ")})`
+          : ""),
+    );
+  const plan = sub === "install" && args.includes("--plan");
+  // print (and install --plan) only write the plist to stdout; the rest
+  // talk to launchd.
+  if (
+    sub !== "print" &&
+    !plan &&
+    (deps.platform ?? process.platform) !== "darwin"
+  )
     throw new Error(
       "the web UI service is a launchd LaunchAgent: macOS only (print works anywhere)",
     );
@@ -105,19 +178,70 @@ export async function cmdService(
     "service",
     "install.sh",
   );
-  const code = (deps.run ?? defaultRunner)("bash", [script, sub!], {
+  const env = {
     DEN_ROOT: distRoot,
     DEN_SERVICE_LABEL: label,
     DEN_SERVICE_LOGS: logs,
+  };
+  const run = deps.run ?? defaultRunner;
+  const log = deps.log ?? ((l: string) => console.log(l));
+  const port = deps.webPort ?? readWebPort(distRoot);
+  const own: OwnServer = { root: distRoot, product: product().name };
+  const identify =
+    deps.identify ?? ((p: number, o: OwnServer) => identifyServer(p, o));
+
+  if (plan) {
+    const home = deps.home ?? os.homedir();
+    log(`service install --plan (read-only: nothing is written or loaded)`);
+    log(`  label:   ${label}`);
+    log(
+      `  plist:   ${path.join(home, "Library", "LaunchAgents", `${label}.plist`)}`,
+    );
+    log(`  logs:    ${path.join(logs, "web.log")}`);
+    log(`  root:    ${distRoot}`);
+    log(`  engine:  ${path.dirname(path.dirname(script))}`);
+    log(`  url:     http://localhost:${port}`);
+    const id = await identify(port, own);
+    log(`  server:  ${identityLine(port, id)}`);
+    log(`  plist it would write:`);
+    // install.sh print writes the plist to stdout only.
+    const code = run("bash", [script, "print"], env);
+    if (code !== 0) return code;
+    if (id.kind === "foreign") {
+      log(`✗ install would refuse this port: ${pickAnotherPortHint()}`);
+      return 1;
+    }
+    return 0;
+  }
+
+  const code = run("bash", [script, sub!], {
+    ...env,
     // The script then leaves saying "running" to us (after the poll below).
     ...(sub === "install" ? { DEN_SERVICE_READY_CHECK: "external" } : {}),
   });
+  if (sub === "status") {
+    const id = await identify(port, own);
+    if (id.kind === "foreign") log(`✗ ${identityLine(port, id)}`);
+    return code;
+  }
   if (sub !== "install" || code !== 0) return code;
 
-  const log = deps.log ?? ((l: string) => console.log(l));
-  const port = deps.webPort ?? readWebPort(distRoot);
   const url = `http://localhost:${port}/api/server-info`;
-  if (await (deps.waitReady ?? waitForServerInfo)(url, READY_TIMEOUT_MS)) {
+  const waitReady =
+    deps.waitReady ??
+    ((u: string, t: number, o: OwnServer) => waitForServerInfo(u, t, 500, o));
+  let ready: boolean;
+  try {
+    ready = await waitReady(url, READY_TIMEOUT_MS, own);
+  } catch (e) {
+    if (!(e instanceof ForeignServerError)) throw e;
+    log(
+      `✗ ${label} installed, but ${foreignServerMessage(e.port, e.who)}, ` +
+        `so it cannot serve there: ${pickAnotherPortHint()}`,
+    );
+    return 1;
+  }
+  if (ready) {
     log(
       `✓ ${label} running at http://localhost:${port} (logs: ${path.join(logs, "web.log")})`,
     );

package/src/ui/cli/spinner.ts

@@ -0,0 +1,48 @@
+/**
+ * The CLI's progress spinners (ora).
+ *
+ * Spinners are progress, not diagnostics: on a terminal they animate on
+ * stderr as usual; piped (CI, scripts) their lines go to stdout so stderr
+ * carries only real warnings and errors.
+ *
+ * They animate only on a terminal with a known, non-zero width. ora
+ * divides each line's width by the column count to know how many lines to
+ * clear before the next frame: on a pty that reports 0 columns (one nobody
+ * sized, as agent shells and some CI runners give) that is Infinity and the
+ * spinner clears lines forever. Without a usable terminal a spinner prints
+ * plain lines instead: its text once on start, and the final line.
+ */
+import oraSpinner, { type Ora } from "ora";
+
+/** A stream as a spinner sees it: a TTY, maybe, with a width, maybe. */
+export interface SpinnerStream extends NodeJS.WritableStream {
+  isTTY?: boolean;
+  columns?: number;
+}
+
+/** Whether a spinner can draw frames on `stream`. */
+export function canAnimate(stream: SpinnerStream): boolean {
+  return (
+    stream.isTTY === true &&
+    typeof stream.columns === "number" &&
+    Number.isFinite(stream.columns) &&
+    stream.columns > 0
+  );
+}
+
+function defaultStream(): SpinnerStream {
+  return process.stderr.isTTY ? process.stderr : process.stdout;
+}
+
+/** A spinner showing `text`, on stderr (a terminal) or stdout (piped). */
+export function spinner(
+  text: string,
+  stream: SpinnerStream = defaultStream(),
+): Ora {
+  return oraSpinner({
+    text,
+    stream: stream as NodeJS.WritableStream,
+    // Unset, ora decides (never under CI or TERM=dumb); false: plain lines.
+    ...(canAnimate(stream) ? {} : { isEnabled: false }),
+  });
+}

package/src/ui/cli/stack-command.ts

@@ -22,6 +22,7 @@ import {
 } from "../../shared/stacks/runtime.js";
 import { loadStackContext, stackStatuses } from "../../shared/stacks/status.js";
 import type { StackConfig } from "../../shared/stacks/types.js";
+import { STACK_HEALTH_UNKNOWN_EXIT } from "../../shared/constants.js";
 
 function serviceFlag(args: string[]): { service?: string; rest: string[] } {
   const rest: string[] = [];
@@ -56,9 +57,48 @@ export async function resolveStacksSecretEnv(
   return out;
 }
 
+/**
+ * `stack health <name…>`: exit 0 when every stack is healthy, 1 when one is
+ * not, and STACK_HEALTH_UNKNOWN_EXIT when none failed but one could not be
+ * told (docker did not answer, the config could not be read). The web
+ * server's health row reads that as unknown, never as down.
+ */
+function stackHealthCommand(args: string[], service?: string): void {
+  let failed = false;
+  let unknown = false;
+  try {
+    const ctx = loadStackContext();
+    const names = args.filter((a) => !a.startsWith("-"));
+    if (!names.length)
+      throw new Error(
+        `Usage: stack health <name…>  (known: ${Object.keys(ctx.stacks).join(", ")})`,
+      );
+    for (const n of names) {
+      const s = ctx.stacks[n];
+      const h = s
+        ? stackHealth(ctx, s, service)
+        : { ok: false, detail: `unknown stack "${n}"` };
+      if (h.ok === false) failed = true;
+      if (h.ok === null) unknown = true;
+      const mark =
+        h.ok === true
+          ? chalk.green("✓")
+          : h.ok === false
+            ? chalk.red("✗")
+            : chalk.gray("?");
+      console.log(`${mark} ${n}  ${h.detail}`);
+    }
+  } catch (e) {
+    console.error(chalk.gray(`? ${(e as Error).message}`));
+    unknown = true;
+  }
+  process.exitCode = failed ? 1 : unknown ? STACK_HEALTH_UNKNOWN_EXIT : 0;
+}
+
 export async function cmdStack(argv: string[]): Promise<void> {
   const { service, rest } = serviceFlag(argv);
   const [sub = "ls", ...args] = rest;
+  if (sub === "health") return stackHealthCommand(args, service);
   // The global -w/--workspace is parsed (and checked) before we run and
   // arrives as DEN_WORKSPACE_OVERRIDE; loadStackContext reads it.
   const ctx = loadStackContext();
@@ -129,18 +169,6 @@ export async function cmdStack(argv: string[]): Promise<void> {
       }
       return;
     }
-    case "health": {
-      let ok = true;
-      for (const n of pick()) {
-        const h = stackHealth(ctx, stacks[n], service);
-        ok &&= h.ok;
-        console.log(
-          `${h.ok ? chalk.green("✓") : chalk.red("✗")} ${n}  ${h.detail}`,
-        );
-      }
-      process.exitCode = ok ? 0 : 1;
-      return;
-    }
     case "down":
       for (const n of startOrder(pick(), stacks)
         .reverse()