@monster-orange/den 0.2.8 → 0.4.0

package/src/ui/cli/index.ts

@@ -11,6 +11,7 @@ import {
   runningWorkspaceStacks,
 } from "../../shared/stacks/status.js";
 import { isNamedTarget } from "./named-target.js";
+import { isNotice, printNotice } from "./notice.js";
 import chalk from "chalk";
 import { noun, plural } from "../../shared/plural.js";
 // Spinners: progress on stderr (a terminal) or stdout (piped); plain lines
@@ -58,6 +59,13 @@ import {
   DEN_SERVICES_DIR,
   DEN_WORKSPACES_DIR,
 } from "../../shared/environment-manager/workspaces.js";
+import {
+  ownersSuffix,
+  parseScope,
+  scopeLine,
+  scopeView,
+  takeScopeFlag,
+} from "../../shared/environment-manager/scope.js";
 import {
   deleteWorkspaceDirectory,
   checkBehindCount,
@@ -70,9 +78,11 @@ import {
   markSetupSucceeded,
   fetchAndFastForward,
 } from "../../shared/environment-manager/workspace-manager.js";
+import { stackNamespaceRows } from "../../shared/stacks/namespace.js";
 import {
   runServiceCommand,
   claimHealthyService,
+  daemonsOutsideWorkspaces,
   getWorkspaceServices,
   ensureDaemonRegistryLoaded,
   hasRunningOpctlContainers,
@@ -104,14 +114,18 @@ import { waitForReady } from "../../shared/environment-manager/readiness.js";
 import {
   canonicalServiceAddress,
   previewServiceCommand,
+  previewUpSettle,
   previewServiceSecretEnv,
   prepareServiceSecretEnv,
   resolveService,
+  type DownOutcome,
   type ServiceCommandPreview,
 } from "../../shared/environment-manager/service-runner.js";
 import { getGitHubCoords } from "../../shared/smoke/git-remote.js";
+import { isConfigError } from "../../shared/config-error.js";
 import {
   assertDenConfigValid,
+  waiveInvalidOrgs,
   getReposRoot,
   mergeUserConfig,
   readDenConfig,
@@ -126,6 +140,11 @@ import {
   deriveStartTargets,
 } from "../../shared/environment-manager/derivation/derived-up.js";
 import type { DerivedGraph } from "../../shared/environment-manager/derivation/types.js";
+import {
+  repoOfAddress,
+  resolveUpTargets,
+  type UpTargets,
+} from "../../shared/environment-manager/up-targets.js";
 import { loadAliasResolver } from "../../shared/environment-manager/derivation/load-alias.js";
 import {
   cmdApps,
@@ -173,8 +192,13 @@ import {
 import { cleanupStaleTabs } from "../../shared/cli-tabs.js";
 import { cmdConfig } from "./config-command.js";
 import { cmdEdge } from "./edge-command.js";
+import { cmdDoctor } from "./doctor-command.js";
+import { cmdSessions, SESSIONS_HELP } from "./sessions-command.js";
+import { AGENTS_HELP, cmdAgents } from "./agents-command.js";
 import { cmdService } from "./service-command.js";
 import { cmdStack } from "./stack-command.js";
+import { cmdTheme } from "./theme-command.js";
+import { cmdPlugin } from "./plugin-command.js";
 import {
   cmdOrg,
   orgFlag,
@@ -209,6 +233,9 @@ import {
   formatHealthDot,
   formatHealthLabel,
   formatHealthReason,
+  formatRollupLabel,
+  healthReasonText,
+  rollupReasonText,
 } from "./health-display.js";
 import { DEN_BANNER_LINES, DEN_DIVIDER } from "../../shared/banner.js";
 
@@ -300,9 +327,12 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     ],
   },
   status: {
-    usage: "status [-A <app>]",
+    usage: "status [-A <app>] [--scope <all|workspace>] [--verbose]",
     lines: [
-      "Show service health for the active workspace (or one application).",
+      "Show service health for what is in view: every active workspace by",
+      "default (the web UI's scope), or --scope <workspace> for one. A",
+      "service several workspaces share is listed once, with its owners.",
+      "--verbose (or --all) shows one row per service instead of per repo.",
     ],
   },
   logs: {
@@ -319,7 +349,7 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
     lines: ["List all registered services in the catalog."],
   },
   register: {
-    usage: "register [path] [--org <id>] [-w <workspace>]",
+    usage: "register [path] [-w <workspace>] [--org <id>]",
     lines: [
       "With a path: add that checkout (dev-managed) under its manifest name.",
       "Without one: pick the repo interactively. A managed clone is picked",
@@ -327,6 +357,15 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
       "-w writes that workspace (active or not) and leaves focus alone.",
     ],
   },
+  relocate: {
+    usage: "relocate <repo> <path> [--dry-run] [--force] [-w <workspace>]",
+    lines: [
+      "Point every workspace's dev-managed entries for <repo> at <path>.",
+      "Refuses a path that is missing, holds a different repo, or has",
+      "neither a manifest nor a remote naming this one (unless --force).",
+      "-w limits it to that workspace; focus never changes.",
+    ],
+  },
   setup: {
     usage:
       "setup [service...] [--force|-f] [--plan [-w <workspace>]... [--all-active]]",
@@ -417,7 +456,37 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   edge: {
     usage: "edge [up|down|status|trust|untrust|routes]",
     lines: [
-      "This org's HTTPS edge: own CA + cert, routes at <name>.<edge.domain>.",
+      "This org's edge: routes at <name>.<edge.domain>, TLS as edge.tls says",
+      "(none | mkcert | files). trust/untrust exist only under mkcert.",
+    ],
+  },
+  doctor: {
+    usage: "doctor [--probe]",
+    lines: [
+      "Each strategy kind (secrets, tls): the one selected, whether it was implicit,",
+      "and whether it can work here (a PATH check; nothing is run or prompted).",
+      "--probe: start a short probe session (through the session host) for a",
+      "plain session and each available runtime's agent env; key names only.",
+      "Exit 1 when a runtime's scrubEnv name or a credential-shaped variable",
+      "reaches one. Without the PTY module it says unavailable, not failed.",
+    ],
+  },
+  plugin: {
+    usage:
+      "plugin [list] | validate [dir] | add <repo>[/<subpath>]@<ref> [--track] [--yes] | update <id> @<ref> | remove <id>",
+    lines: [
+      "Plugins (den.plugin/v1) in plugins/<id>/: local (the distribution's own, no lock entry)",
+      "or added (vendored at an exact ref, pinned in plugins.lock.json). list checks each",
+      "against the lock; validate checks every manifest. add refuses file:// sources.",
+    ],
+  },
+  theme: {
+    usage:
+      "theme [list] | validate [dir] | new <id> | add <repo>[/<subpath>]@<ref> | remove <id>",
+    lines: [
+      "Web UI themes (den.theme/v1). add fetches one at an exact ref, validates it",
+      "(schema, contrast in both modes, files) and vendors it into plugins/<id>/",
+      "with a plugins.lock.json entry; commit both. list checks them against the lock.",
     ],
   },
   mcp: {
@@ -438,13 +507,15 @@ const COMMAND_HELP: Record<string, { usage: string; lines: string[] }> = {
   "local-dev": {
     usage: "local-dev [on|off]",
     lines: [
-      "Toggle the local-dev experience (web Local Dev section + service mgmt).",
+      "Toggle the local-dev experience (web Workspaces page + service mgmt).",
     ],
   },
   menu: {
     usage: "menu",
     lines: ["Open the interactive menu (pillar/module/env picker)."],
   },
+  sessions: SESSIONS_HELP,
+  agents: AGENTS_HELP,
 };
 
 function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
@@ -466,6 +537,7 @@ function resolveCliBaseApiUrl(explicitBaseApiUrl?: string): string | undefined {
 const TELEMETRY_COMMANDS = new Set<string>([
   "run",
   "view-results",
+  "down",
   "menu",
   "web",
   "up",
@@ -476,6 +548,7 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "services",
   "graph",
   "register",
+  "relocate",
   "use-local",
   `use-managed`,
   "setup",
@@ -488,19 +561,26 @@ const TELEMETRY_COMMANDS = new Set<string>([
   "local-dev",
   "config",
   "edge",
+  "doctor",
   "stack",
   "apps",
   "applications",
   "mcp",
+  "sessions",
+  "agents",
   "service",
+  "theme",
+  "plugin",
 ]);
 
 /**
  * Commands that run with a config that fails validation: the web and MCP
  * servers (each route or tool reports it), and those that read neither orgs,
  * the catalog nor clones (manifest validate, create, the per-engineer
- * config and local-dev toggles, saved results). Every other registered
- * command checks the config first.
+ * config and local-dev toggles, saved results), and `down` (0.3.0-dev.40:
+ * stopping is never stranded by a config that fails; it stops from the
+ * daemon records and compose projects, reading no org data). Every other
+ * registered command checks the config first.
  */
 const CONFIG_FREE_COMMANDS = new Set<string>([
   "web",
@@ -510,6 +590,11 @@ const CONFIG_FREE_COMMANDS = new Set<string>([
   "config",
   "local-dev",
   "view-results",
+  "down",
+  // The session host and its clients read no org data, and stopping or
+  // listing a session is never stranded by a config that fails (AG-3a).
+  "sessions",
+  "agents",
 ]);
 
 function configCheckedCommand(command: string): boolean {
@@ -743,6 +828,22 @@ class DenCLI {
       // anything: some (sync over existing clones, register, workspace
       // create) never read `orgs:` and used to carry on (ORG-1d).
       if (command && configCheckedCommand(command)) assertDenConfigValid();
+      // `down` is never stranded by an invalid config (0.3.0-dev.40): it
+      // says so and stops from the daemon records and compose projects,
+      // reading the config without its org data.
+      if (command === "down") {
+        try {
+          assertDenConfigValid();
+        } catch (e) {
+          if (!isConfigError(e)) throw e;
+          console.log(
+            chalk.yellow(
+              `\n  ⚠ ${e.message}\n  Stopping anyway, without the config's org data. Fix it, then \`${product().cli} validate\`.`,
+            ),
+          );
+          waiveInvalidOrgs();
+        }
+      }
 
       switch (command) {
         case "run":
@@ -798,6 +899,10 @@ class DenCLI {
           await this.cmdRegister(args.slice(1));
           break;
 
+        case "relocate":
+          await this.cmdRelocate(args.slice(1));
+          break;
+
         case "use-local":
           await this.cmdUseMode(args.slice(1), "dev-managed");
           break;
@@ -872,6 +977,10 @@ class DenCLI {
           await cmdEdge(args.slice(1));
           break;
 
+        case "doctor":
+          process.exitCode = await cmdDoctor(args.slice(1));
+          break;
+
         case "service":
           process.exitCode = await cmdService(args.slice(1));
           break;
@@ -880,12 +989,28 @@ class DenCLI {
           await cmdStack(args.slice(1));
           break;
 
+        case "theme":
+          process.exitCode = await cmdTheme(args.slice(1));
+          break;
+
+        case "plugin":
+          process.exitCode = await cmdPlugin(args.slice(1));
+          break;
+
         case "apps":
         case "applications":
           await this.ensureWorkspaceSeeded();
           cmdApps(args.slice(1));
           break;
 
+        case "sessions":
+          process.exitCode = await cmdSessions(args.slice(1));
+          break;
+
+        case "agents":
+          process.exitCode = await cmdAgents(args.slice(1));
+          break;
+
         case "mcp": {
           // Setup subcommands: register the server with agents.
           const { MCP_CONNECT_SUBCOMMANDS, runMcpConnect } =
@@ -1597,7 +1722,15 @@ class DenCLI {
       // The same lookup a real run makes, so the dry run says what it does.
       const previews = ordered.map((a): ServiceCommandPreview => {
         const remote = remoteRefusal(a);
-        if (!remote) return previewServiceCommand(a, command, workspace);
+        if (!remote) {
+          const p = previewServiceCommand(a, command, workspace);
+          // What up does first about a pre-dev.37 record or a held port.
+          return (
+            (command === "up" && p.kind === "run"
+              ? previewUpSettle(a, workspace)
+              : null) ?? p
+          );
+        }
         // As the loop below: a named remote target fails, any other is
         // said and skipped.
         return isNamedTarget(a, opts?.named ?? [])
@@ -1620,7 +1753,7 @@ class DenCLI {
         ),
       );
       for (const p of previews) {
-        if (p.kind === "via-repo" || p.kind === "nothing")
+        if (p.kind !== "error" && p.note)
           console.log(chalk.gray(`  ${p.note}`));
         if (p.kind === "error") console.log(chalk.red(`  ✗ ${p.note}`));
       }
@@ -1698,12 +1831,27 @@ class DenCLI {
         const resolved = resolveService(address, workspace);
         if (resolved) {
           const health = await checkServiceHealth(resolved, "local");
-          if (health.health === "ok") {
+          // `conflict`: a shared stack namespace runs another checkout's
+          // project; the real up below refuses it, naming both.
+          const claim =
+            health.health === "ok" && workspace
+              ? claimHealthyService(resolved, workspace, printNotice)
+              : "untracked";
+          // Healthy, but another process answers on its port: said (above),
+          // never claimed, and nothing is started on top of it.
+          if (health.health === "ok" && claim === "busy") {
+            console.log(
+              chalk.red(
+                `  ✗ ${chalk.bold(address)} not started: its port is in use by a process ${product().cli} won't adopt`,
+              ),
+            );
+            // A dependency only warns; the service you named failed.
+            if (isNamedTarget(address, opts?.named ?? [])) process.exitCode = 1;
+            continue;
+          }
+          if (health.health === "ok" && claim !== "conflict") {
             // Skipping must not lose the refcount — this workspace is an owner
             // of what's running, whether den tracked it or not.
-            const claim = workspace
-              ? claimHealthyService(resolved, workspace)
-              : "untracked";
             const suffix =
               claim === "adopted"
                 ? " (adopted its running containers)"
@@ -1804,6 +1952,8 @@ class DenCLI {
         let result: ReturnType<typeof runServiceCommand> | null = null;
         let detachable = false;
         let interactive = false;
+        // A down that found nothing to stop is said as such, never as ✔.
+        let downOutcome: DownOutcome | null = null;
 
         const settleFromClose = (exitCode: number): void => {
           if (settled) return;
@@ -1820,6 +1970,17 @@ class DenCLI {
                 ),
               );
             }
+          } else if (exitCode === 0 && downOutcome === "nothing-recorded") {
+            spinner.info(
+              `${command} ${chalk.bold(address)} ${chalk.gray("(nothing to stop)")}`,
+            );
+          } else if (exitCode === 0 && downOutcome === "unstoppable") {
+            spinner.warn(
+              `${command} ${chalk.bold(address)} ${chalk.yellow("(could not stop it)")}`,
+            );
+            for (const l of lastLines) {
+              console.log(chalk.gray(`      ${l}`));
+            }
           } else if (exitCode === 0) {
             spinner.succeed(`${command} ${chalk.bold(address)}`);
           } else {
@@ -1873,8 +2034,21 @@ class DenCLI {
           runtime,
           workspace,
           force: command === "down" ? force : false,
+          // Down fails when it cannot stop a service the user named; one
+          // reached as part of a workspace-wide down warns instead.
+          explicit: isNamedTarget(address, opts?.named ?? []),
+          onDownOutcome: (outcome) => {
+            downOutcome = outcome;
+          },
           secretEnv: secrets.secretEnv,
           onLine: (line) => {
+            // What Den decided about a record or a port is said, not
+            // only flashed in the spinner (0.3.0-dev.39).
+            if (isNotice(line)) {
+              spinner.clear();
+              printNotice(line);
+              if (spinner.isEnabled) spinner.render();
+            }
             spinner.text = `${command} ${chalk.bold(address)}: ${chalk.gray(line.slice(0, 80))}`;
             const trimmed = line.trim();
             if (trimmed) {
@@ -2130,11 +2304,15 @@ class DenCLI {
       this.renderUpClonePlan(rawOrder);
       return;
     }
+    // A repo with no up of its own starts its services, one with no up at
+    // all is skipped: the decision `up -a` makes (resolveUpTargets).
+    const targets = new Set(include ? [seed] : []);
     if (dryRun) {
+      const up = this.upTargets(order, targets, graph);
       await this.runServicesCommand(
-        order,
+        up.order,
         "up",
-        { order },
+        { order: up.order },
         { named, dryRun: true },
       );
       return;
@@ -2158,12 +2336,18 @@ class DenCLI {
       );
       return;
     }
+    const up = this.upTargets(order, targets, graph);
+    if (up.order.length === 0) {
+      console.log(chalk.yellow("  Nothing to start.\n"));
+      return;
+    }
     await this.runServicesCommand(
-      order,
+      up.order,
       "up",
       {
-        order,
-        waitDepsFor: (address) => hardDepsOf(graph, address),
+        order: up.order,
+        waitDepsFor: (address) =>
+          up.depsAs(hardDepsOf(graph, repoOfAddress(address))),
         failFast: true,
         skipHealthyAll: true,
       },
@@ -2171,6 +2355,37 @@ class DenCLI {
     );
   }
 
+  /**
+   * The start order `up` runs (`up <repo>` and `up -a` alike): a repo with
+   * no up of its own replaced by its services' ups, one with no up at all
+   * skipped (resolveUpTargets), said as it decides.
+   */
+  private upTargets(
+    order: string[],
+    targets: ReadonlySet<string>,
+    graph: DerivedGraph,
+  ): UpTargets {
+    const up = resolveUpTargets(order, this.focusedWs(), { targets, graph });
+    this.sayUpTargets(up);
+    return up;
+  }
+
+  /** What resolveUpTargets decided, in `up`'s words. */
+  private sayUpTargets(up: UpTargets): void {
+    for (const [repo, addrs] of up.expanded)
+      console.log(
+        chalk.gray(
+          `  ${repo} has no up of its own: starting ${addrs.join(", ")}`,
+        ),
+      );
+    if (up.skippedNoUp.length > 0)
+      console.log(
+        chalk.gray(
+          `  Skipping (no local up command): ${up.skippedNoUp.join(", ")}\n`,
+        ),
+      );
+  }
+
   /**
    * Stop the seed repo and the dependencies it was started with — the same
    * closure `den up <seed>` brings up, torn down in reverse (seed first,
@@ -2388,19 +2603,18 @@ class DenCLI {
     // is skipped, not fatal. `-a` starts independent peers — one unrunnable
     // repo must not strand the rest (runServiceCommand exits 1 on a missing
     // command, and a fail-fast would turn that into a full abort). Now that
-    // clones exist, the manifest lookup is meaningful.
-    const order: string[] = [];
-    const skippedNoUp: string[] = [];
-    for (const repo of candidates) {
-      const resolved = resolveService(repo);
-      const upDef = resolved
-        ? localCommandsFor(resolved, this.focusedWs())["up"]
-        : undefined;
-      (upDef ? order : skippedNoUp).push(repo);
-    }
+    // clones exist, the manifest lookup is meaningful. A repo with no up of
+    // its own but per-service ups starts those services: the same decision
+    // `up <repo>` makes for a dependency (upTargets).
+    const up = resolveUpTargets(candidates, this.focusedWs(), {
+      targets: new Set(candidates),
+      graph,
+    });
+    const order = up.order;
+    const systems = candidates.filter((r) => !up.skippedNoUp.includes(r));
     console.log(
       chalk.cyan(
-        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(order.length))} ${noun(order.length, "system")}`,
+        `\n  ${only ? "Application" : "Workspace-wide"} up — ${chalk.bold(String(systems.length))} ${noun(systems.length, "system")}`,
       ),
     );
     console.log(chalk.gray(`  Order: ${order.join(" → ")}\n`));
@@ -2412,13 +2626,7 @@ class DenCLI {
         ),
       );
     }
-    if (skippedNoUp.length > 0) {
-      console.log(
-        chalk.gray(
-          `  Skipping (no local up command): ${skippedNoUp.join(", ")}\n`,
-        ),
-      );
-    }
+    this.sayUpTargets(up);
     if (order.length === 0) {
       console.log(chalk.yellow("  Nothing to start.\n"));
       return;
@@ -2428,13 +2636,17 @@ class DenCLI {
     // healthy-skip. Unlike runDerivedUp there is NO failFast on the start
     // loop: `-a`'s systems are independent peers — one failure must not
     // strand the rest (the web master button continues too).
-    const repoSet = new Set(order);
+    const repoSet = new Set(systems);
     await this.runServicesCommand(order, "up", {
       order,
       // Hard deps outside the workspace can't be waited on — filter to the set
       // we are actually starting.
       waitDepsFor: (address) =>
-        hardDepsOf(graph, address).filter((dep) => repoSet.has(dep)),
+        up.depsAs(
+          hardDepsOf(graph, repoOfAddress(address)).filter((dep) =>
+            repoSet.has(dep),
+          ),
+        ),
       skipHealthyAll: true,
     });
   }
@@ -2470,6 +2682,14 @@ class DenCLI {
       return;
     }
     await this.runServicesCommand(order, "down", { order }, { force });
+    // Records no workspace reaches: -a stops every workspace's services,
+    // not these. Said, and left alone (0.3.0-dev.39, a consumer's finding).
+    if (!only)
+      for (const d of daemonsOutsideWorkspaces())
+        printNotice(
+          `Warning: ${d.address} is recorded as running (${d.repoPath}) but is in no active workspace: ` +
+            `down -a left it alone. Stop it yourself if it still runs.`,
+        );
   }
 
   private printUpHelp(): void {
@@ -2993,15 +3213,49 @@ class DenCLI {
 
   private async cmdServiceStatus(argv: string[] = []): Promise<void> {
     await this.ensureWorkspaceSeeded();
-    const { app, rest: args } = takeAppFlag(argv);
+    const { app, rest: appRest } = takeAppFlag(argv);
+    // The view scope (as the web UI's): every active workspace by default,
+    // or `--scope <workspace>` for one. A view only: focus is unchanged.
+    const scoped = takeScopeFlag(appRest);
+    const args = scoped.rest;
+    const scopeArg =
+      scoped.scope === null
+        ? null
+        : parseScope(scoped.scope, getActiveWorkspaces());
+    if (scoped.error || (scopeArg && !scopeArg.ok)) {
+      console.log(
+        chalk.red(
+          `\n  ${scoped.error ?? (scopeArg && !scopeArg.ok ? scopeArg.error : "")}\n`,
+        ),
+      );
+      process.exit(1);
+    }
+    // `-w <workspace>` still means that workspace only (active or not).
+    const named = process.env.DEN_WORKSPACE_OVERRIDE
+      ? getActiveWorkspace()
+      : null;
+    const view =
+      named && !scopeArg
+        ? {
+            scope: named.name,
+            fellBack: false,
+            workspaces: [named],
+            focus: named.name,
+          }
+        : scopeView(scopeArg?.ok ? scopeArg.value : undefined);
     const only = app ? focusedAppRepos(app) : null;
     const verbose = args.includes("--verbose") || args.includes("--all");
     const spinner = ora("Checking service health...").start();
-    const raw = (await checkCatalogHealth()).filter(
-      (h) => !only || only.has(h.repoName),
-    );
-    // Roll multi-service repos up to their entrypoint so shared-infra sidecars
-    // (which read healthy off infra-stack) don't make a down app look up.
+    const raw = (
+      await checkCatalogHealth(
+        undefined,
+        "local",
+        view.workspaces.filter((w) => w.config),
+      )
+    ).filter((h) => !only || only.has(h.repoName));
+    // One row per repo, rolled up from every checked service by the rule the
+    // web UI's header and graph use: entry down → down, another checked
+    // service down → degraded; unchecked services never count.
     const rolled = verbose ? raw : rollupRepoHealth(raw);
     // Order top-down like the graph: entry repo first (shop-web) … foundation
     // last (infra-stack), subsystems grouped under their repo.
@@ -3019,10 +3273,7 @@ class DenCLI {
       return;
     }
 
-    const ws = getActiveWorkspace();
-    console.log(
-      chalk.cyan(`\n  Workspace: ${chalk.bold(ws?.name ?? "none")}\n`),
-    );
+    console.log(chalk.cyan(`\n  ${scopeLine(view)}\n`));
 
     const table = newTable({
       head: ["Service", "Mode", "Branch", "Health", "Reason"],
@@ -3030,8 +3281,20 @@ class DenCLI {
     });
 
     for (const r of results) {
-      const healthStr = formatHealthLabel(r.health);
-      const reasonStr = formatHealthReason(r);
+      const healthStr = r.rollup
+        ? formatRollupLabel(r.rollup)
+        : formatHealthLabel(r.health);
+      const rolledWhy = r.rollup ? rollupReasonText(r.rollup) : "";
+      const reasonStr =
+        r.rollup && r.rollup.state !== "unknown"
+          ? chalk.gray(
+              [r.rollup.state === "down" ? healthReasonText(r) : "", rolledWhy]
+                .filter(Boolean)
+                .join("; ")
+                .slice(0, 60),
+            )
+          : formatHealthReason(r) ||
+            (rolledWhy ? chalk.gray(rolledWhy.slice(0, 60)) : "");
       const placed = placementSuffix({
         runs: r.runs ?? "none",
         target: r.target ?? null,
@@ -3039,6 +3302,7 @@ class DenCLI {
 
       table.push([
         this.labelWithAutostart(r.address, noAutostart) +
+          chalk.gray(ownersSuffix(r.workspaces)) +
           (placed ? chalk.cyan(`  ${placed}`) : ""),
         r.mode === "dev-managed"
           ? chalk.blue("dev-managed")
@@ -3060,7 +3324,7 @@ class DenCLI {
     if (!verbose && raw.length !== results.length) {
       console.log(
         chalk.gray(
-          `  ▪ multi-service repos show entrypoint health — \`${product().cli} status --verbose\` for all subsystems`,
+          `  ▪ one row per repo, rolled up from its checked services — \`${product().cli} status --verbose\` for each`,
         ),
       );
     }
@@ -3231,13 +3495,14 @@ class DenCLI {
   private async cmdRegister(args: string[]): Promise<void> {
     if (args.includes("-h") || args.includes("--help")) {
       console.log(
-        `\n  ${product().cli} register [path] [--name <repo>] [--gh <owner/repo>] [-w <workspace>]\n\n` +
+        `\n  ${product().cli} register [path] [--name <repo>] [--gh <owner/repo>] [-w <workspace>] [--org <id>]\n\n` +
           "  With a path: add that checkout to the catalog and the focused\n" +
           "  workspace as your own (dev-managed) copy, without prompts. The name\n" +
           "  defaults to the manifest's name, then the folder name; the GitHub\n" +
           "  slug to the git remote. -w writes that workspace (active or not)\n" +
           "  and leaves focus alone.\n" +
-          "  Without a path: choose a local checkout or a managed clone interactively.\n",
+          "  Without a path: choose a local checkout or a managed clone interactively;\n" +
+          "  a managed clone comes from the workspace's org, or --org <id>.\n",
       );
       return;
     }
@@ -3245,7 +3510,9 @@ class DenCLI {
       (a, i) =>
         !a.startsWith("-") && !/^--(name|gh|org)$/.test(args[i - 1] ?? ""),
     );
-    // Without a path, register prompts: with no terminal, say how to name one.
+    // Without a path, register prompts: with no terminal (stdin closed or
+    // piped, where readline would throw ERR_USE_AFTER_CLOSE mid-prompt), say
+    // how to name one. Usage error: exit 2.
     if (!repoPathArg && !process.stdin.isTTY) {
       process.stderr.write(
         `register needs a terminal (stdin is not a TTY); without one: ` +
@@ -3282,7 +3549,157 @@ class DenCLI {
     }
   }
 
-  /** Non-interactive `register <path>`: a dev-managed entry in the focused workspace. */
+  /**
+   * `relocate <repo> <path>`: a checkout moved on disk. Rewrites the path of
+   * every dev-managed entry for <repo> (bare and `<repo>/<svc>` addresses) in
+   * every workspace, or only the `-w` one. Managed entries are Den's own
+   * clones and are left alone. Focus and the active set never change.
+   */
+  private async cmdRelocate(args: string[]): Promise<void> {
+    const usage = `${product().cli} relocate <repo> <path> [--dry-run] [--force] [-w <workspace>]`;
+    if (args.includes("-h") || args.includes("--help")) {
+      console.log(
+        `\n  ${usage}\n\n` +
+          "  A checkout moved: point every workspace's dev-managed entries for\n" +
+          "  <repo> at <path>. Refuses a missing path, one whose manifest\n" +
+          "  name or GitHub remote names a different repo, and one where\n" +
+          "  neither names this repo (--force accepts that last). --dry-run shows\n" +
+          "  the changes without writing. -w limits it to that workspace.\n" +
+          "  Focus and the active set never change.\n",
+      );
+      return;
+    }
+    const dryRun = args.includes("--dry-run") || args.includes("-n");
+    const force = args.includes("--force");
+    const unknown = args.find(
+      (a) => a.startsWith("-") && !["--dry-run", "-n", "--force"].includes(a),
+    );
+    const positional = args.filter((a) => !a.startsWith("-"));
+    if (unknown || positional.length !== 2) {
+      console.error(
+        chalk.red(
+          `\n  ❌ ${unknown ? `Unknown flag: ${unknown}` : "Need a repo and a path"}.\n     Usage: ${usage}\n`,
+        ),
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const [repoName, rawPath] = positional;
+    const { existsSync, statSync } = await import("fs");
+    const newPath = nodePath.resolve(rawPath);
+    const fail = (msg: string) => {
+      console.error(chalk.red(`\n  ❌ ${msg}\n`));
+      process.exitCode = 1;
+    };
+    const file = readWorkspacesFile();
+    const only = process.env.DEN_WORKSPACE_OVERRIDE;
+    const names = only ? [only] : Object.keys(file.workspaces);
+    const belongs = (key: string) =>
+      key === repoName || key.startsWith(`${repoName}/`);
+    if (
+      !names.some((ws) =>
+        Object.keys(file.workspaces[ws]?.services ?? {}).some(belongs),
+      )
+    ) {
+      fail(
+        `"${repoName}" is not in ${only ? `workspace "${only}"` : "any workspace"}.`,
+      );
+      return;
+    }
+    if (!existsSync(newPath) || !statSync(newPath).isDirectory()) {
+      fail(`Path does not exist: ${newPath}`);
+      return;
+    }
+
+    // The new path must hold this repo: its manifest name and GitHub remote,
+    // when present, must agree with the repo and its catalog entry.
+    const manifest = readManifest(newPath);
+    const leaf = repoName.split("/").pop() ?? repoName;
+    if (
+      manifest?.name &&
+      manifest.name !== repoName &&
+      manifest.name !== leaf
+    ) {
+      fail(
+        `${newPath} holds "${manifest.name}", not "${repoName}" (its manifest name).`,
+      );
+      return;
+    }
+    const catalogGh = readCatalog()[repoName]?.gh?.trim();
+    const coords = getGitHubCoords(newPath);
+    const remote = coords ? `${coords.owner}/${coords.repo}` : undefined;
+    if (
+      catalogGh &&
+      remote &&
+      catalogGh.toLowerCase() !== remote.toLowerCase()
+    ) {
+      fail(
+        `${newPath} is a checkout of ${remote}; the catalog has "${repoName}" as ${catalogGh}.`,
+      );
+      return;
+    }
+    // Not contradicting is not enough: an empty or unrelated folder has no
+    // manifest and no remote. Something must say this is the repo.
+    const identified =
+      manifest?.name === repoName ||
+      manifest?.name === leaf ||
+      (!!catalogGh &&
+        !!remote &&
+        catalogGh.toLowerCase() === remote.toLowerCase()) ||
+      (!catalogGh && coords?.repo.toLowerCase() === leaf.toLowerCase());
+    if (!identified && !force) {
+      fail(
+        `Nothing at ${newPath} says it is "${repoName}": no manifest named ` +
+          `"${leaf}" and no GitHub remote ${catalogGh || `…/${leaf}`}.\n` +
+          `     If it is, say so: ${product().cli} relocate ${repoName} ${rawPath} --force${dryRun ? " --dry-run" : ""}${only ? ` -w ${only}` : ""}`,
+      );
+      return;
+    }
+
+    const changes: { ws: string; addr: string; from: string }[] = [];
+    const managed: { ws: string; addr: string }[] = [];
+    for (const ws of names) {
+      const entries = file.workspaces[ws]?.services ?? {};
+      for (const [addr, entry] of Object.entries(entries)) {
+        if (!belongs(addr)) continue;
+        if (entry.mode !== "dev-managed") {
+          managed.push({ ws, addr });
+          continue;
+        }
+        if (entry.path && nodePath.resolve(entry.path) === newPath) continue;
+        changes.push({ ws, addr, from: entry.path ?? "(default)" });
+        if (!dryRun) entry.path = newPath;
+      }
+    }
+
+    if (changes.length > 0 && !dryRun) writeWorkspacesFile(file);
+
+    const verb = dryRun ? "Would point" : "Pointed";
+    if (changes.length === 0) {
+      console.log(
+        chalk.gray(
+          `\n  Nothing to change: "${repoName}" is already at ${newPath}.`,
+        ),
+      );
+    } else {
+      console.log(chalk.green(`\n  ✓ ${verb} at ${newPath}:\n`));
+      for (const c of changes) {
+        console.log(
+          `    ${chalk.bold(c.addr)}  ${chalk.gray(`${c.ws}   was ${c.from}`)}`,
+        );
+      }
+    }
+    for (const m of managed) {
+      console.log(
+        chalk.gray(
+          `    ${m.addr}  ${m.ws}   managed (Den's clone): left alone`,
+        ),
+      );
+    }
+    console.log();
+  }
+
+  /** Non-interactive `register <path>`: a dev-managed entry in the focused (or -w) workspace. */
   private async registerPath(
     ws: {
       name: string;
@@ -3751,14 +4168,32 @@ class DenCLI {
         const only = orgFlag(args.slice(1));
         const { resolved, warnings } = orgListRows();
         const orgOfWs = new Map(resolved.map((w) => [w.workspace, w.org]));
-        const table = newTable({
-          head: ["Workspace", "Org", "Active", "Focus", "Services", "Type"],
-          style: { head: ["cyan"] },
-        });
         const shown = Object.entries(file.workspaces).filter(
           ([name]) => !only || sameOrg(orgOfWs.get(name) ?? null, only),
         );
+        // A Stacks column only when a shown workspace's stack namespace is
+        // not its default suffix (or is invalid): the list is otherwise as before.
+        const nsRows = new Map(
+          stackNamespaceRows(shown.map(([n]) => n)).map((r) => [
+            r.workspace,
+            r,
+          ]),
+        );
+        const nsCol = [...nsRows.values()].some((r) => r.differs || r.error);
+        const table = newTable({
+          head: [
+            "Workspace",
+            "Org",
+            "Active",
+            "Focus",
+            "Services",
+            "Type",
+            ...(nsCol ? ["Stacks"] : []),
+          ],
+          style: { head: ["cyan"] },
+        });
         for (const [name, cfg] of shown) {
+          const ns = nsRows.get(name);
           table.push([
             chalk.bold(name),
             orgOfWs.get(name) ?? chalk.gray("none"),
@@ -3766,9 +4201,23 @@ class DenCLI {
             name === focus ? chalk.cyan("●") : "",
             Object.keys(cfg.services).join(", ") || chalk.gray("none"),
             cfg.directory ? chalk.magenta("feature") : chalk.blue("default"),
+            ...(nsCol
+              ? [
+                  ns?.error
+                    ? chalk.red("invalid")
+                    : ns?.differs
+                      ? `${ns.stack_namespace} ${chalk.gray(`(${ns.source})`)}`
+                      : chalk.gray(ns?.default ?? ""),
+                ]
+              : []),
           ]);
         }
         console.log(table.toString());
+        printOrgWarnings(
+          [...nsRows.values()].flatMap((r) =>
+            r.error ? [`workspace ${r.workspace}: ${r.error}`] : r.warnings,
+          ),
+        );
         if (only && shown.length === 0)
           console.log(chalk.yellow(`  No workspace in org ${only}.`));
         const names = new Set(shown.map(([n]) => n));
@@ -4075,6 +4524,58 @@ class DenCLI {
   // ── den validate ────────────────────────────────────────────────────────
 
   private async cmdValidate(args: string[]): Promise<void> {
+    // The org config first (0.3.0-dev.40, a consumer's 0.2.8 nit: a
+    // ConfigError went unreported): each problem with its file and key
+    // path, a non-zero exit, and the manifests are still checked, reading
+    // the config without its org data.
+    try {
+      assertDenConfigValid();
+    } catch (e) {
+      if (!isConfigError(e)) throw e;
+      console.error(chalk.red(`\n  ✗ ${product().configFile} is invalid:`));
+      const issues = e.issues.length
+        ? e.issues
+        : [{ file: product().configFile, key: "", message: e.message }];
+      for (const i of issues)
+        console.error(
+          chalk.red(`  ✗ ${i.file}  ${chalk.bold(i.key)}  ${i.message}`),
+        );
+      process.exitCode = 1;
+      waiveInvalidOrgs();
+    }
+    // The distribution's secrets config, once: a 1password backend with no
+    // refs leaves the vault-backed features off (no built-in vault/item).
+    try {
+      const { secretsConfigWarnings } =
+        await import("../../shared/secrets/index.js");
+      for (const w of secretsConfigWarnings())
+        console.warn(chalk.yellow(`\n  ⚠  ${w.replace(/\n/g, "\n     ")}`));
+    } catch {
+      /* an unreadable config is reported elsewhere */
+    }
+    // The edge's TLS strategy, when there is an edge: its config, the
+    // implicit-mkcert warning (once), and detect() (mkcert on PATH).
+    {
+      const { hasEdgeBlock, readEdgeConfig } =
+        await import("../../shared/edge/config.js");
+      const { edgeTlsWarnings, tlsStrategyFor, warnImplicitTlsOnce } =
+        await import("../../shared/edge/tls.js");
+      let edge: ReturnType<typeof readEdgeConfig> | null = null;
+      try {
+        if (hasEdgeBlock()) edge = readEdgeConfig();
+      } catch (e) {
+        console.error(chalk.red(`\n  ✗  edge: ${(e as Error).message}`));
+        process.exitCode = 1;
+      }
+      if (edge) {
+        const warn = (w: string) => console.warn(chalk.yellow(`\n  ⚠  ${w}`));
+        warnImplicitTlsOnce(edge, warn);
+        for (const w of edgeTlsWarnings(edge))
+          if (edge.tlsFrom !== "implicit") warn(w);
+        const d = tlsStrategyFor(edge).detect();
+        if (!d.available) warn(`edge.tls ${edge.tls.strategy}: ${d.reason}`);
+      }
+    }
     const positional = args.filter((a) => !a.startsWith("-"));
     const held = args.includes("--held");
     // Bare `validate` in the distribution root (which has no manifest of its
@@ -4279,7 +4780,7 @@ class DenCLI {
       "  restart [service...] Restart services (-A <app> for a whole application)",
     );
     console.log(
-      "  status               Show service health for active workspace (-A <app>)",
+      "  status               Show service health for the view scope (-A <app>, --scope <ws>)",
     );
     console.log(
       "  apps                 Org > Application > Repo > Services (--json)",
@@ -4300,6 +4801,9 @@ class DenCLI {
     console.log(
       "  register [path]      Register a repo in the service catalog",
     );
+    console.log(
+      "  relocate <repo> <path>  Point a moved checkout's workspace entries at its new path",
+    );
     console.log();
     console.log(
       "  setup [service...]   Run make setup for services (--plan: orgs + clone URLs, no changes)",
@@ -4317,6 +4821,22 @@ class DenCLI {
     console.log(
       "  service install      Run the web UI as a launchd service (status, print, uninstall)",
     );
+    console.log(
+      "  theme add <repo>@<ref> Install a web UI theme (list, validate, remove)",
+    );
+    console.log(
+      "  plugin list          Local and added plugins, checked (validate, add, update, remove)",
+    );
+    console.log(
+      "  sessions start -w <ws> --name <n> -- <argv…>  A terminal that outlives the web server",
+    );
+    console.log(
+      "  sessions list|attach|kill   List, attach to (ctrl-] detaches) or stop sessions",
+    );
+    console.log("  agents list -w <ws>  The workspace's agents");
+    console.log(
+      "  agents start -w <ws> --persona <p>  Run a persona in the workspace (stop, resume, personas)",
+    );
     console.log();
     console.log(
       "  workspace list           List workspaces (active set + focus)",