@monster-orange/den 0.2.3 → 0.2.5

package/src/ui/cli/index.ts

@@ -5,6 +5,11 @@
  * Main entry point for the interactive CLI
  */
 
+import { composeStacksNotice } from "./workspace-notes.js";
+import {
+  runningComposeProjects,
+  runningWorkspaceStacks,
+} from "../../shared/stacks/status.js";
 import { isNamedTarget } from "./named-target.js";
 import chalk from "chalk";
 import oraSpinner from "ora";
@@ -46,7 +51,9 @@ import {
   isWorkspaceActive,
   activateWorkspace,
   deactivateWorkspace,
+  getActiveWorkspaces,
   setActiveWorkspace,
+  setFocusedWorkspace,
   createWorkspace,
   deleteWorkspaceConfig,
   parseAddress,
@@ -78,9 +85,11 @@ import {
   resolveServiceRuntime,
 } from "../../shared/environment-manager/service-runner.js";
 import {
-  defaultWorkspaceRepos,
+  blueprintWorkspaces,
   defaultWorkspaceNeedsSeeding,
   defaultWorkspaceHasServices,
+  isMultiBlueprint,
+  seedBlueprintWorkspaces,
   seedDefaultWorkspace,
   topUpDefaultWorkspace,
   markDefaultWorkspaceDeclined,
@@ -195,6 +204,66 @@ const DEN_HELP_DESCRIPTION = `  ${product().title} - local-first test, service,
  * Concise `<command> -h` help for commands without a dedicated help renderer.
  * Flag-heavy commands (up, graph, use-local, use-managed) have richer handlers.
  */
+/** `workspace` subcommands, for `workspace --help` and `workspace <sub> --help`. */
+const WORKSPACE_SUBCOMMANDS: {
+  name: string;
+  usage: string;
+  lines: string[];
+}[] = [
+  {
+    name: "list",
+    usage: "list",
+    lines: ["every workspace, the active set and the focus"],
+  },
+  {
+    name: "activate",
+    usage: "activate <n>",
+    lines: ["add a workspace to the active set"],
+  },
+  {
+    name: "deactivate",
+    usage: "deactivate <n>",
+    lines: [
+      "remove it from the active set and stop the services",
+      "only it owns. Only services {cli} tracks: compose",
+      "stacks keep running; stop them with `{cli} down <repo>`",
+    ],
+  },
+  {
+    name: "focus",
+    usage: "focus <n>",
+    lines: ["make an active workspace the default for commands"],
+  },
+  {
+    name: "use",
+    usage: "use <n>",
+    lines: ["activate and focus a workspace"],
+  },
+  {
+    name: "create",
+    usage: "create [n]",
+    lines: ["create an empty workspace"],
+  },
+  {
+    name: "delete",
+    usage: "delete <n>",
+    lines: ["delete a workspace (and its directory)"],
+  },
+  {
+    name: "code",
+    usage: "code [n]",
+    lines: ["open it in your editor (VS Code: a .code-workspace)"],
+  },
+  {
+    name: "seed",
+    usage: "seed",
+    lines: [
+      "fill workspaces from the distribution's blueprint",
+      "(defaults.workspace / defaults.workspaces), all managed",
+    ],
+  },
+];
+
 const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   down: {
     usage: "down [repo] [flags]",
@@ -252,8 +321,16 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     lines: ["Check managed repos for upstream updates and offer to pull."],
   },
   workspace: {
-    usage: "workspace <list|use|create|delete|code> [name]",
-    lines: ["Manage workspaces (named sets of services + their modes)."],
+    usage: `workspace <${WORKSPACE_SUBCOMMANDS.map((c) => c.name).join("|")}> [name]`,
+    lines: [
+      "Manage workspaces (named sets of services + their modes).",
+      "",
+      ...WORKSPACE_SUBCOMMANDS.flatMap((c) =>
+        c.lines.map(
+          (line, i) => `  ${(i === 0 ? c.usage : "").padEnd(16)}  ${line}`,
+        ),
+      ),
+    ],
   },
   run: {
     usage: "run [options]",
@@ -583,7 +660,7 @@ class DenCLI {
       !["-h", "--help", "-v", "--version"].includes(command) &&
       (ownArgs.includes("-h") || ownArgs.includes("--help"))
     ) {
-      this.printCommandHelp(command);
+      this.printCommandHelp(command, ownArgs[1]);
       return;
     }
 
@@ -2375,7 +2452,19 @@ class DenCLI {
   }
 
   /** Help for `<command> -h`: dedicated renderer for flag-heavy commands, else the table. */
-  private printCommandHelp(command: string): void {
+  private printCommandHelp(command: string, sub?: string): void {
+    // `workspace <sub> --help`: that subcommand only.
+    const wsSub =
+      command === "workspace"
+        ? WORKSPACE_SUBCOMMANDS.find((c) => c.name === sub)
+        : undefined;
+    if (wsSub) {
+      console.log(`\n  ${product().cli} workspace ${wsSub.usage}\n`);
+      for (const line of wsSub.lines)
+        console.log(`  ${line.replaceAll("{cli}", product().cli)}`);
+      console.log();
+      return;
+    }
     switch (command) {
       case "up":
         return this.printUpHelp();
@@ -2398,41 +2487,48 @@ class DenCLI {
       return;
     }
     console.log(`\n  ${product().cli} ${entry.usage}\n`);
-    for (const line of entry.lines) console.log(`  ${line}`);
+    for (const line of entry.lines)
+      console.log(`  ${line.replaceAll("{cli}", product().cli)}`.trimEnd());
     console.log();
   }
 
   /**
-   * Seed (or reset) the default workspace from the committed blueprint
-   * (config/den.yml `defaults.workspace`), all repos managed. Prints
-   * clear guidance and, on a TTY, asks first. `reason: "auto"` is the one-time
-   * offer on a fresh clone; `reason: "init"` is the explicit `den init`.
-   * Returns true if the workspace was seeded.
+   * Seed (or reset) the blueprint's workspaces from the committed config:
+   * `defaults.workspace` fills `default`; `defaults.workspaces` creates each
+   * named workspace, activates them all and focuses the marked one. All
+   * repos managed. Prints clear guidance and, on a TTY, asks first.
+   * `reason: "auto"` is the one-time offer on a genuine fresh setup (TTY
+   * only: see ensureWorkspaceSeeded); `reason: "init"` is the explicit
+   * `<cli> workspace seed` / `<cli> init` in the root. Returns true if seeded.
    */
   private async seedDefaultWorkspaceFlow(
     reason: "auto" | "init",
   ): Promise<boolean> {
-    const repos = defaultWorkspaceRepos();
-    if (repos.length === 0) {
+    const bps = blueprintWorkspaces();
+    if (bps.length === 0) {
       if (reason === "init") {
         console.log(
           chalk.yellow(
-            `\n  No defaults.workspace.repos in ${product().configFile} — nothing to seed.\n`,
+            `\n  No defaults.workspace.repos or defaults.workspaces in ${product().configFile} — nothing to seed.\n`,
           ),
         );
       }
       return false;
     }
+    const multi = isMultiBlueprint();
     const willReset = defaultWorkspaceHasServices();
     const interactive = !!(process.stdin.isTTY && process.stdout.isTTY);
 
-    console.log(
-      chalk.cyan(`\n  Default workspace — ${repos.length} repos, all managed:`),
-    );
-    console.log(chalk.gray(`    ${repos.join(", ")}`));
+    for (const bp of bps) {
+      const label = multi ? `Workspace ${bp.name}` : "Default workspace";
+      console.log(
+        chalk.cyan(`\n  ${label} — ${bp.repos.length} repos, all managed:`),
+      );
+      console.log(chalk.gray(`    ${bp.repos.join(", ")}`));
+    }
     console.log(
       chalk.gray(
-        `  ${product().title} clones + tracks them on main under ${product().servicesDir}/. Switch any`,
+        `  ${product().title} clones + tracks them on their branch under ${product().servicesDir}/. Switch any`,
       ),
     );
     console.log(
@@ -2442,16 +2538,17 @@ class DenCLI {
     );
 
     if (interactive) {
+      const what = multi ? "these workspaces" : "the default workspace";
       const question = willReset
-        ? "  Reset the default workspace to this shipped set?"
-        : "  Seed the default workspace now?";
+        ? `  Reset ${what} to this shipped set?`
+        : `  Seed ${what} now?`;
       const ok = await cliPrompts.confirm(question, !willReset);
       if (!ok) {
         if (reason === "auto") {
           markDefaultWorkspaceDeclined(); // don't ask again
           console.log(
             chalk.gray(
-              `  Skipped — run \`${product().cli} init\` to set it up later.\n`,
+              `  Skipped — run \`${product().cli} workspace seed\` to set it up later.\n`,
             ),
           );
         } else {
@@ -2461,6 +2558,17 @@ class DenCLI {
       }
     }
 
+    if (multi) {
+      const seeded = seedBlueprintWorkspaces();
+      const focus = readWorkspacesFile().focus;
+      console.log(
+        chalk.green(
+          `  ✓ ${seeded.length} workspaces ready (${seeded.map((w) => w.name).join(", ")}), all active; focus: ${focus}. ` +
+            `Run \`${product().cli} up <repo>\` to bring up its closure.\n`,
+        ),
+      );
+      return true;
+    }
     const seeded = seedDefaultWorkspace();
     console.log(
       chalk.green(
@@ -2472,13 +2580,22 @@ class DenCLI {
   }
 
   /**
-   * One-time offer to seed the default workspace on a fresh clone; afterwards
-   * keep it converged on the blueprint (repos added to defaults later — e.g.
-   * tasks-api — join the existing workspace managed).
+   * On a genuine fresh setup (nothing but an empty, never-seeded `default`),
+   * offer to seed from the blueprint: on a TTY, ask; otherwise print a
+   * one-line hint and change nothing. Afterwards keep a lone `default`
+   * converged on the blueprint (repos added to defaults later join it
+   * managed); never once the user has other workspaces.
    */
   private async ensureWorkspaceSeeded(): Promise<void> {
     if (defaultWorkspaceNeedsSeeding()) {
-      await this.seedDefaultWorkspaceFlow("auto");
+      if (process.stdin.isTTY && process.stdout.isTTY) {
+        await this.seedDefaultWorkspaceFlow("auto");
+      } else {
+        const hint = isMultiBlueprint()
+          ? "no workspaces yet: run `{cli} workspace seed` to create them from the blueprint"
+          : "default workspace is empty: run `{cli} workspace seed` to fill it from the blueprint";
+        console.error(chalk.gray(`  ${hint.replace("{cli}", product().cli)}`));
+      }
       return;
     }
     const added = topUpDefaultWorkspace();
@@ -3501,9 +3618,36 @@ class DenCLI {
             }
           }
         }
+        // Deactivate releases tracked daemons only; say what it left up.
+        // One docker ps for this workspace and every other active one.
+        let up: ReturnType<typeof runningComposeProjects> | undefined;
+        const running = () =>
+          up === undefined ? (up = runningComposeProjects()) : up;
+        const stacks = runningWorkspaceStacks(name, running);
+        const heldBy = new Map<string, string[]>();
+        if (stacks?.length)
+          for (const other of getActiveWorkspaces())
+            for (const s of runningWorkspaceStacks(other, running) ?? [])
+              heldBy.set(s.project, [...(heldBy.get(s.project) ?? []), other]);
+        const stacksNote = composeStacksNotice(product().cli, stacks, heldBy);
+        if (stacksNote) console.log(chalk.yellow(`    ${stacksNote}`));
         console.log("");
         break;
       }
+      case "focus": {
+        const name = args[1];
+        if (!name) {
+          console.log(
+            chalk.red(`Usage: ${product().cli} workspace focus <name>`),
+          );
+          return;
+        }
+        setFocusedWorkspace(name);
+        console.log(
+          chalk.green(`\n  ✓ Focused workspace: ${chalk.bold(name)}\n`),
+        );
+        break;
+      }
       case "use": {
         const name = args[1];
         if (!name) {
@@ -3520,6 +3664,10 @@ class DenCLI {
         );
         break;
       }
+      case "seed": {
+        await this.seedDefaultWorkspaceFlow("init");
+        break;
+      }
       case "create": {
         const name =
           args[1] ??
@@ -3611,7 +3759,7 @@ class DenCLI {
       default:
         console.log(
           chalk.gray(
-            `Usage: ${product().cli} workspace <list|activate|deactivate|use|create|delete|code> [name]`,
+            `Usage: ${product().cli} workspace <${WORKSPACE_SUBCOMMANDS.map((c) => c.name).join("|")}> [name]`,
           ),
         );
     }
@@ -3871,7 +4019,6 @@ class DenCLI {
       "  service install      Run the web UI as a launchd service (status, print, uninstall)",
     );
     console.log();
-    console.log("  workspace list       List workspaces");
     console.log(
       "  workspace list           List workspaces (active set + focus)",
     );
@@ -3879,11 +4026,14 @@ class DenCLI {
     console.log(
       "  workspace deactivate <n> Remove workspace from the active set",
     );
+    console.log(
+      "  workspace focus <n>      Focus an active workspace (the default)",
+    );
     console.log("  workspace use <n>        Activate and focus a workspace");
-    console.log("  workspace create [n] Create a new workspace");
-    console.log("  workspace delete <n> Delete a workspace");
+    console.log("  workspace create [n]     Create a new workspace");
+    console.log("  workspace delete <n>     Delete a workspace");
     console.log(
-      "  workspace code [n]   Open workspace in VS Code (generates .code-workspace)",
+      "  workspace code [n]       Open workspace in VS Code (generates .code-workspace)",
     );
     console.log("\nTest commands:");
     console.log(

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

@@ -25,7 +25,7 @@ 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 { readMcpConfig } from "../../shared/den-config.js";
+import { readDenConfig, readMcpConfig } from "../../shared/den-config.js";
 
 export const MCP_CONNECT_SUBCOMMANDS = [
   "connect",
@@ -199,6 +199,78 @@ function status(
     : chalk.gray("not connected");
 }
 
+/** How long `mcp connect` waits for /api/server-info before giving up. */
+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 }
+  /** Something accepted the connection but sent no answer in time. */
+  | { kind: "timeout" }
+  /** Nothing answered: connection refused, or not the web server. */
+  | { kind: "down" };
+
+export async function probeWebServer(
+  url: string,
+  timeoutMs: number = WEB_PROBE_TIMEOUT_MS,
+  fetchImpl: typeof fetch = fetch,
+): 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 };
+  } catch (e) {
+    return (e as Error).name === "TimeoutError"
+      ? { kind: "timeout" }
+      : { kind: "down" };
+  }
+}
+
+/** Whether the org config runs the web UI as a service (`web.service`). */
+function webRunsAsService(): boolean {
+  try {
+    return readDenConfig().web?.service !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The status line for a probe. A server that is up but slow is "not
+ * answering", never "not running"; and when the web UI runs as a service
+ * (`web.service`), the advice is the service's status, not `web up`.
+ */
+export function webServerMessage(
+  probe: WebProbe,
+  url: string,
+  opts: { cli: string; asService: boolean; timeoutMs?: number },
+): string {
+  if (probe.kind === "up")
+    return (
+      chalk.green(`web server up at ${url}`) +
+      (probe.version ? chalk.gray(` (Den ${probe.version})`) : "")
+    );
+  const svc = `\`${opts.cli} service status\``;
+  if (probe.kind === "timeout") {
+    const secs = (opts.timeoutMs ?? WEB_PROBE_TIMEOUT_MS) / 1000;
+    return chalk.yellow(
+      `web server at ${url} is not answering within ${secs}s (busy or stuck): ` +
+        `agents' reads wait on it too; if it stays slow, ` +
+        (opts.asService
+          ? `check ${svc}`
+          : `restart it with \`${opts.cli} web restart\``),
+    );
+  }
+  return chalk.yellow(
+    `web server not running at ${url}: agents get read errors until ` +
+      (opts.asService
+        ? `the service is up (check ${svc})`
+        : `\`${opts.cli} web up\``),
+  );
+}
+
 async function webServerLine(port?: number): Promise<string> {
   let p = port;
   if (p === undefined) {
@@ -209,20 +281,10 @@ async function webServerLine(port?: number): Promise<string> {
     }
   }
   const url = `http://localhost:${p}`;
-  try {
-    const r = await fetch(`${url}/api/server-info`, {
-      signal: AbortSignal.timeout(1500),
-    });
-    const info = (await r.json()) as { version?: string };
-    return (
-      chalk.green(`web server up at ${url}`) +
-      (info.version ? chalk.gray(` (Den ${info.version})`) : "")
-    );
-  } catch {
-    return chalk.yellow(
-      `web server not running at ${url}: agents get read errors until \`${product().cli} web up\``,
-    );
-  }
+  return webServerMessage(await probeWebServer(url), url, {
+    cli: product().cli,
+    asService: webRunsAsService(),
+  });
 }
 
 function usage(): string {

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()

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

@@ -3,6 +3,7 @@ import { execFileSync, spawn, spawnSync } from "child_process";
 import * as fs from "fs";
 import * as http from "http";
 import * as path from "path";
+import { pathToFileURL } from "url";
 import {
   CLI_SPAWN_TIMEOUT_MS,
   DEFAULT_PORT,
@@ -10,7 +11,7 @@ import {
 } from "../../shared/constants.js";
 import { getDistRoot, getEngineRoot, getStateDir } from "../../shared/paths.js";
 import { hasDenUiMarker } from "../../shared/ui-marker.js";
-import { engineBin } from "../../shared/engine.js";
+import { engineBin, engineModuleFile } from "../../shared/engine.js";
 import { readWebPort } from "../../shared/edge/config.js";
 
 import { product } from "../../shared/product.js";
@@ -294,8 +295,19 @@ async function waitForDenWeb(port: number): Promise<boolean> {
   return false;
 }
 
-/** How to run the web server: Den's own files, from the engine root. */
-function resolveServerEntrypoint(engine: string = getEngineRoot()): {
+/**
+ * How to run the web server: Den's own files, from the engine root.
+ *
+ * The TypeScript source runs as `node --import <tsx loader> index.ts`, never
+ * through the `tsx` CLI. The CLI is a parent process that relays signals to
+ * the server and, if the server has not acknowledged a SIGTERM within about
+ * 60ms (two 30ms windows), SIGKILLs it and exits 143. Under load the server
+ * misses that window, so `<cli> web down` killed it without its shutdown.
+ * With the loader there is one process, and the signal reaches the
+ * server's own handler. (The launchd service, service/install.sh, already
+ * runs this way.)
+ */
+export function resolveServerEntrypoint(engine: string = getEngineRoot()): {
   cmd: string;
   args: string[];
 } {
@@ -313,17 +325,23 @@ function resolveServerEntrypoint(engine: string = getEngineRoot()): {
   // take effect. The server resolves PUBLIC_DIR relative to its own module, so
   // running from src/ serves src/ui/server/public directly. Fall back to the
   // compiled build only when devDependencies (tsx) aren't installed.
-  const tsxBin = engineBin(process.platform === "win32" ? "tsx.cmd" : "tsx");
+  const loader = engineModuleFile("tsx/dist/loader.mjs", engine);
   const srcServer = path.join(engine, "src/ui/server/index.ts");
-  if (fs.existsSync(tsxBin) && fs.existsSync(srcServer)) {
-    return { cmd: tsxBin, args: [srcServer] };
+  if (loader && fs.existsSync(srcServer)) {
+    return {
+      cmd: process.execPath,
+      args: ["--import", pathToFileURL(loader).href, srcServer],
+    };
   }
 
   if (fs.existsSync(builtServer)) {
     return { cmd: process.execPath, args: [builtServer] };
   }
 
-  return { cmd: tsxBin, args: [srcServer] };
+  return {
+    cmd: engineBin(process.platform === "win32" ? "tsx.cmd" : "tsx", engine),
+    args: [srcServer],
+  };
 }
 
 function startDenWebServer(options: WebCommandOptions): StartedServer {

package/src/ui/cli/workspace-notes.ts

@@ -0,0 +1,43 @@
+/**
+ * What `<cli> workspace deactivate` says about what it leaves running: it
+ * releases only the daemons Den tracks, so a compose stack started from one
+ * of the workspace's repos keeps running until `<cli> down <repo>`. A stack
+ * another active workspace still holds is named as in use, never with a
+ * command that would stop it.
+ */
+import type { WorkspaceStack } from "../../shared/stacks/status.js";
+
+/**
+ * The note for `stacks`: the running ones (null when docker could not be
+ * asked, so it is said generically), or nothing when none is running.
+ * `heldBy` maps a Compose project to the other active workspaces that hold
+ * it.
+ */
+export function composeStacksNotice(
+  cli: string,
+  stacks: WorkspaceStack[] | null,
+  heldBy: ReadonlyMap<string, string[]> = new Map(),
+): string | null {
+  if (stacks === null)
+    return `compose stacks keep running: stop them with \`${cli} down <repo>\``;
+  if (stacks.length === 0) return null;
+  const held = stacks.filter((s) => heldBy.get(s.project)?.length);
+  // `down <repo>` stops all of a repo's stacks: never suggest it for a repo
+  // with a stack still in use.
+  const heldRepos = new Set(held.map((s) => s.repo));
+  const free = stacks.filter((s) => !heldRepos.has(s.repo));
+  const inUse = held.map(
+    (s) => `${s.project} (still in ${heldBy.get(s.project)!.join(", ")})`,
+  );
+  const parts: string[] = [];
+  if (free.length) {
+    const repos = [...new Set(free.map((s) => s.repo))];
+    parts.push(
+      `compose stacks keep running (${free.map((s) => s.project).join(", ")}): ` +
+        `stop them with ${repos.map((r) => `\`${cli} down ${r}\``).join(", ")}`,
+    );
+  }
+  if (inUse.length)
+    parts.push(`in use by another workspace: ${inUse.join(", ")}`);
+  return parts.join("; ");
+}

package/src/ui/server/graph-order.ts

@@ -0,0 +1,22 @@
+/**
+ * The dependency graph's top-down repo order (entry repo first, infra last),
+ * which the health row and /api/services rank by.
+ *
+ * Deriving the graph walks every repo's sources (fingerprints, scans), so it
+ * is far too slow to redo on each 5s poll. In the web server it is kept for
+ * 30s and then recomputed after the request that noticed, never inside it
+ * (read-cache.ts); a stale order only means a briefly stale sort.
+ */
+import { deriveGraph } from "../../shared/environment-manager/derivation/derive-graph.js";
+import { orderForDown } from "../../shared/environment-manager/derivation/derived-up.js";
+import { cachedReadStale } from "../../shared/read-cache.js";
+
+const GRAPH_ORDER_MAX_AGE_MS = 30_000;
+
+export function graphOrder(workspace: string | undefined): string[] {
+  return cachedReadStale(
+    `graph-order:${workspace ?? ""}`,
+    GRAPH_ORDER_MAX_AGE_MS,
+    () => orderForDown(deriveGraph({ scope: "all", workspace })),
+  );
+}