@monster-orange/den 0.4.2 → 0.4.4

package/src/ui/cli/agent-ops.ts

@@ -7,7 +7,10 @@
  * what happened, or throws an AgentError saying why it didn't.
  *
  *   start   resolves the persona (Den's default pack, then
- *           agents.persona_packs) and the runtime, asks the runtime for argv,
+ *           agents.persona_packs) and the runtime (its CLI from
+ *           agents.runtimes.<id>.bin in user.yml, else the search:
+ *           runtime-search.ts, AG-0.1; unavailable, it is refused with the
+ *           fix), asks the runtime for argv,
  *           env and files (its MCP config: `<cli> mcp --workspace <ws>
  *           --actor agent:<id>`, plus a `--grant` per agents.<id>.grants),
  *           starts `<dist>-<ws>:<id>` in the workspace's dir, and writes the
@@ -38,9 +41,23 @@ import * as fs from "fs";
 import * as path from "path";
 import {
   AGENTS_RESERVED_KEYS,
+  configuredRuntimeBin,
+  configuredRuntimeCatalog,
   readAgentsConfig,
+  setUserRuntimeBin,
+  userConfigPath,
   type ResolvedAgentsConfig,
 } from "../../shared/den-config.js";
+import {
+  setWorkspaceRuntimeBin,
+  workspaceBinKey,
+  workspaceRuntimeBin,
+} from "../../shared/environment-manager/workspaces.js";
+import {
+  BUILTIN_CATALOG,
+  type CatalogEntry,
+} from "../../shared/agents/catalog.js";
+import { checkRuntimeBin } from "../../shared/agents/catalog-runtime.js";
 import { cliEntrypoint } from "../../shared/engine.js";
 import { getDistRoot } from "../../shared/paths.js";
 import { envKey } from "../../shared/product.js";
@@ -65,10 +82,20 @@ import {
   getRuntime,
   LaunchError,
   runtimeIds,
+  syncConfiguredRuntimes,
   type AgentMcp,
   type LaunchInput,
   type Runtime,
 } from "../../shared/agents/runtimes.js";
+import type { RuntimeDetect } from "../../shared/agents/runtime.js";
+import {
+  binSettingKey,
+  ensureInteractivePath,
+  interactivePathAsked,
+  runtimeVersion,
+  type BinSetting,
+  type BinSource,
+} from "../../shared/agents/runtime-search.js";
 import { WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
 import {
   bindActorSession,
@@ -103,6 +130,24 @@ export interface AgentsDeps extends SessionsDeps {
    * exit (default 3000 ms; 0: not at all).
    */
   exitWatchMs?: number;
+  /** `agents.runtimes.<id>.bin` (default: user.yml's; undefined: unset). */
+  runtimeBin?: (id: string) => unknown;
+  /**
+   * Workspace `ws`'s `agents.runtimes.<id>.bin` (default: workspaces.yml's;
+   * undefined: unset). It wins over runtimeBin (AG-0.5).
+   */
+  workspaceRuntimeBin?: (ws: string, id: string) => unknown;
+  /** user.yml's runtime catalog entries, checked (default: user.yml's). */
+  userCatalog?: (taken: readonly string[]) => CatalogEntry[];
+  /** Save a checked path (null clears it): global or the workspace's. */
+  saveRuntimeBin?: (
+    scope: "global" | "workspace",
+    ws: string | undefined,
+    id: string,
+    bin: string | null,
+  ) => void;
+  /** The user.yml a person edits to set it (default: config/local/user.yml). */
+  userConfigFile?: () => string;
 }
 
 export interface AgentsResolved extends Resolved {
@@ -111,6 +156,11 @@ export interface AgentsResolved extends Resolved {
   workspaceDir: (ws: string) => string;
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
+  runtimeBin: (id: string) => unknown;
+  workspaceRuntimeBin: (ws: string, id: string) => unknown;
+  userCatalog: (taken: readonly string[]) => CatalogEntry[];
+  saveRuntimeBin: NonNullable<AgentsDeps["saveRuntimeBin"]>;
+  userConfigFile: () => string;
 }
 
 /** The early-exit watch: at most this long, polling the host. */
@@ -199,6 +249,17 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
       }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
+    runtimeBin: d.runtimeBin ?? ((id) => configuredRuntimeBin(id)),
+    workspaceRuntimeBin:
+      d.workspaceRuntimeBin ?? ((ws, id) => workspaceRuntimeBin(ws, id)),
+    userCatalog: d.userCatalog ?? ((taken) => configuredRuntimeCatalog(taken)),
+    saveRuntimeBin:
+      d.saveRuntimeBin ??
+      ((scope, ws, id, bin) =>
+        scope === "workspace" && ws
+          ? setWorkspaceRuntimeBin(ws, id, bin)
+          : setUserRuntimeBin(id, bin)),
+    userConfigFile: d.userConfigFile ?? userConfigPath,
   };
 }
 
@@ -394,29 +455,225 @@ export function listPersonas(d: AgentsResolved): ListedPersona[] {
 
 export interface RuntimeChoice {
   id: string;
+  /** Its name for people ("Claude Code"). */
+  label?: string;
+  /** Who makes it ("Anthropic"): a catalog runtime (AG-0.5). */
+  vendor?: string;
+  /**
+   * false: it runs as its own CLI, without Den's tools yet ("Den tools:
+   * coming"). Absent for a runtime that isn't from the catalog.
+   */
+  denTools?: boolean;
   available: boolean;
   /** Why it is unavailable. */
   why?: string;
   version?: string;
+  /** The CLI it runs (AG-0.2). */
+  path?: string;
+  /**
+   * Where that path came from: workspace (its workspaces.yml entry),
+   * setting (user.yml), login-shell, PATH, well-known, interactive-shell.
+   */
+  source?: BinSource;
+  /** The directories searched, in order (a runtime with a CLI to find). */
+  searched?: string[];
+  /** The user.yml key that sets its path (a runtime with a CLI to find). */
+  setting?: string;
+  /** The workspace's key for it, when listed for a workspace. */
+  workspaceSetting?: string;
   /** It declares resume. */
   resume: boolean;
   default: boolean;
 }
 
-/** Every registered runtime, and whether it can run here (detect runs nothing). */
-export function listRuntimes(d: AgentsResolved): RuntimeChoice[] {
-  return runtimeIds().map((id) => {
-    const rt = getRuntime(id)!;
-    const det = rt.detect(d.env);
-    return {
-      id,
-      available: det.available,
-      ...(det.available ? {} : { why: det.why ?? "unavailable" }),
-      ...(det.version ? { version: det.version } : {}),
-      resume: Boolean(rt.resume),
-      default: id === DEFAULT_RUNTIME_ID,
-    };
-  });
+/**
+ * The path set for runtime `id` (AG-0.5): the workspace's (when `ws` is
+ * given and it sets one), else user.yml's; null when neither does.
+ */
+export function runtimeSetting(
+  d: AgentsResolved,
+  id: string,
+  ws?: string,
+): BinSetting | null {
+  if (ws) {
+    const v = d.workspaceRuntimeBin(ws, id);
+    if (v !== undefined && v !== null)
+      return { value: v, source: "workspace", key: workspaceBinKey(ws, id) };
+  }
+  const g = d.runtimeBin(id);
+  return g === undefined || g === null ? null : { value: g, source: "setting" };
+}
+
+/**
+ * Whether runtime `rt` can run here (AG-0.1, AG-0.5): a path set for the
+ * workspace, else user.yml's (`agents.runtimes.<id>.bin`), else the
+ * search. Runs nothing.
+ */
+export function detectRuntime(
+  d: AgentsResolved,
+  rt: Runtime,
+  ws?: string,
+): RuntimeDetect {
+  return rt.detect(d.env, { bin: runtimeSetting(d, rt.id, ws) });
+}
+
+/**
+ * The catalog entries the distribution and user.yml add, registered as
+ * runtimes (AG-0.5). A malformed entry is a refusal naming its key.
+ */
+export function syncCatalog(d: AgentsResolved): void {
+  const cfg = agentsConfig(d);
+  let extra: CatalogEntry[];
+  try {
+    extra = [
+      ...cfg.runtimeCatalog,
+      ...d.userCatalog([
+        ...BUILTIN_CATALOG.map((e) => e.id),
+        ...cfg.runtimeCatalog.map((e) => e.id),
+      ]),
+    ];
+  } catch (e) {
+    throw refused((e as Error).message, [], 422);
+  }
+  syncConfiguredRuntimes(extra);
+}
+
+/**
+ * When a catalog runtime is still missing (nothing set, not found on the
+ * login PATH, PATH or its install directories), ask the interactive shell
+ * for its PATH: once per process, then kept (AG-0.5).
+ */
+async function fallbackSearch(
+  d: AgentsResolved,
+  rts: Runtime[],
+  ws?: string,
+): Promise<void> {
+  if (interactivePathAsked()) return;
+  const missing = rts.some(
+    (rt) =>
+      rt.catalog &&
+      !runtimeSetting(d, rt.id, ws) &&
+      !detectRuntime(d, rt, ws).available,
+  );
+  if (missing) await ensureInteractivePath({ env: d.env });
+}
+
+/**
+ * The catalog's installed runtimes first, then the ones not found, then
+ * the rest (generic: no CLI of its own to find).
+ */
+function rank(r: RuntimeChoice): number {
+  if (r.denTools === undefined) return 2;
+  return r.available ? 0 : 1;
+}
+
+/**
+ * Every registered runtime, and whether it can run here (for an agent of
+ * `ws`, when given: its workspace's path wins), with the path it runs and
+ * its version: its version command (`claude --version`), run once under a
+ * timeout and kept, else what its install says. Installed ones first.
+ */
+export async function listRuntimes(
+  d: AgentsResolved,
+  ws?: string,
+): Promise<RuntimeChoice[]> {
+  syncCatalog(d);
+  const ids = runtimeIds();
+  await fallbackSearch(
+    d,
+    ids.map((id) => getRuntime(id)!),
+    ws,
+  );
+  const rows = await Promise.all(
+    ids.map(async (id) => {
+      const rt = getRuntime(id)!;
+      const det = detectRuntime(d, rt, ws);
+      const asked =
+        det.available && det.path && rt.find?.versionArgs
+          ? await runtimeVersion(det.path, rt.find.versionArgs, d.env)
+          : undefined;
+      const version = asked ?? det.version;
+      return {
+        id,
+        ...(rt.label ? { label: rt.label } : {}),
+        ...(rt.vendor ? { vendor: rt.vendor } : {}),
+        ...(rt.catalog ? { denTools: rt.denTools === true } : {}),
+        available: det.available,
+        ...(det.available ? {} : { why: det.why ?? "unavailable" }),
+        ...(version ? { version } : {}),
+        ...(det.path ? { path: det.path } : {}),
+        ...(det.source ? { source: det.source } : {}),
+        ...(rt.find
+          ? {
+              searched: det.searched ?? [],
+              setting: binSettingKey(id),
+              ...(ws ? { workspaceSetting: workspaceBinKey(ws, id) } : {}),
+            }
+          : {}),
+        resume: Boolean(rt.resume),
+        default: id === DEFAULT_RUNTIME_ID,
+      };
+    }),
+  );
+  return rows
+    .map((r, i) => ({ r, i }))
+    .sort((a, b) => rank(a.r) - rank(b.r) || a.i - b.i)
+    .map((x) => x.r);
+}
+
+/**
+ * Set (or, with null, clear) runtime `id`'s path, global or for workspace
+ * `ws` (AG-0.5): its version command runs first, and a path that isn't
+ * that runtime is refused. Returns its row as listed after.
+ */
+export async function setRuntimePath(
+  d: AgentsResolved,
+  req: {
+    id: string;
+    scope: "global" | "workspace";
+    workspace?: string;
+    bin: string | null;
+  },
+): Promise<RuntimeChoice> {
+  syncCatalog(d);
+  const rt = runtimeFor(req.id);
+  if (!rt.catalog)
+    throw usage(`${req.id} has no CLI to find: its path can't be set`);
+  let ws: string | undefined;
+  if (req.scope === "workspace") {
+    ws = checkWorkspaceName("runtime path", req.workspace);
+    if (!d.workspaceExists(ws))
+      throw usage(`workspace "${ws}" does not exist`, 404);
+  }
+  if (req.bin !== null) {
+    const c = await checkRuntimeBin(rt.catalog, req.bin, d.env);
+    if (!c.ok) throw refused(c.why, [], 422);
+    d.saveRuntimeBin(req.scope, ws, rt.id, c.path);
+  } else d.saveRuntimeBin(req.scope, ws, rt.id, null);
+  const rows = await listRuntimes(d, ws);
+  return rows.find((r) => r.id === rt.id)!;
+}
+
+/** Refused unless `rt` can run here; its detect result when it can. */
+async function availableOrRefuse(
+  d: AgentsResolved,
+  rt: Runtime,
+  ws?: string,
+): Promise<RuntimeDetect> {
+  await fallbackSearch(d, [rt], ws);
+  const det = detectRuntime(d, rt, ws);
+  if (!det.available)
+    throw refused(
+      `${rt.id} is unavailable: ${det.why ?? "unknown"}`,
+      rt.find
+        ? [
+            `Install it, or set ${binSettingKey(rt.id)} to its absolute path in ${d.userConfigFile()}.`,
+            `\`${d.cli} agents doctor\` shows where it looked.`,
+          ]
+        : [],
+      503,
+    );
+  return det;
 }
 
 function runtimeFor(id: string): Runtime {
@@ -460,6 +717,21 @@ interface Launch {
   passthrough?: readonly string[];
   /** agents.<id>.grants, recorded with its actor token. */
   grants: readonly string[];
+  /** Added to the session's PATH: a configured CLI's own directory. */
+  binDir?: string;
+}
+
+/**
+ * A CLI's directory when the session's PATH wouldn't have it (a path set
+ * for it, or found by the interactive shell), for its own tools.
+ */
+function binDirOf(det: RuntimeDetect): { binDir?: string } {
+  return (det.source === "setting" ||
+    det.source === "workspace" ||
+    det.source === "interactive-shell") &&
+    det.path
+    ? { binDir: path.dirname(det.path) }
+    : {};
 }
 
 /** The host's cap refusal as an AgentError (its hint says what to do). */
@@ -511,6 +783,7 @@ async function startSession(
             launch.env,
             launch.rec.id,
             minted.token,
+            launch.binDir ? [launch.binDir] : [],
           ),
           cols: (tty && d.stdout.columns) || 80,
           rows: (tty && d.stdout.rows) || 24,
@@ -601,6 +874,7 @@ function launchInput(
   ws: string,
   id: string,
   model: string | undefined,
+  bin?: string,
 ): LaunchInput {
   const grants = cfg.agents[id]?.grants ?? [];
   for (const g of grants)
@@ -623,6 +897,7 @@ function launchInput(
     filesDir: agentFilesDir(d.stateDir(), id),
     stateDir: d.stateDir(),
     env: d.env,
+    ...(bin ? { bin } : {}),
   };
 }
 
@@ -680,10 +955,9 @@ export async function startAgent(
     );
   const id = req.id ?? defaultId(d.stateDir(), persona.id, ws);
   checkId(where, id);
+  syncCatalog(d);
   const rt = runtimeFor(req.runtime ?? persona.runtime ?? DEFAULT_RUNTIME_ID);
-  const det = rt.detect(d.env);
-  if (!det.available)
-    throw refused(`${rt.id} is unavailable: ${det.why ?? "unknown"}`, [], 503);
+  const det = await availableOrRefuse(d, rt, ws);
   const model = req.model ?? persona.model;
 
   const prev = readRecord(d.stateDir(), id);
@@ -692,7 +966,7 @@ export async function startAgent(
       `agent ${id} belongs to workspace ${prev.workspace}; give this one another --id`,
     );
   ptyOrRefuse(d);
-  const input = launchInput(d, cfg, persona, ws, id, model);
+  const input = launchInput(d, cfg, persona, ws, id, model, det.path);
 
   return withClient(d, async (c) => {
     const sessions = await c.list();
@@ -721,6 +995,7 @@ export async function startAgent(
         env: out.env,
         passthrough: rt.envPassthrough,
         grants: cfg.agents[id]?.grants ?? [],
+        ...binDirOf(det),
       },
       old,
       {},
@@ -786,6 +1061,7 @@ export async function resumeAgent(
   ws?: string,
 ): Promise<Resumed> {
   const rec = agentRecord(d, id, ws);
+  syncCatalog(d);
   const rt = runtimeFor(rec.runtime);
   if (!rt.resume)
     throw refused(`runtime ${rt.id} does not declare resume`, [
@@ -795,6 +1071,7 @@ export async function resumeAgent(
   const persona = personas(d, cfg).get(rec.persona);
   if (!persona)
     throw refused(`agent ${rec.id}'s persona "${rec.persona}" is gone`);
+  const det = await availableOrRefuse(d, rt, rec.workspace);
   ptyOrRefuse(d);
   return withClient(d, async (c) => {
     const old = sessionOf(await c.list(), rec);
@@ -809,6 +1086,7 @@ export async function resumeAgent(
       rec.workspace,
       rec.id,
       rec.model,
+      det.path,
     );
     // Resume in the cwd the agent had, wherever the workspace points now.
     const at = {
@@ -833,6 +1111,7 @@ export async function resumeAgent(
         env: out.env,
         passthrough: rt.envPassthrough,
         grants: cfg.agents[rec.id]?.grants ?? [],
+        ...binDirOf(det),
       },
       old,
       fresh ? {} : { resumedAt: new Date().toISOString() },

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

@@ -24,16 +24,27 @@
  *           running: a new session, in the same cwd, continuing the last run;
  *           when that session was never prompted, a fresh start under the
  *           same conversation id (there is nothing to continue).
+ *   doctor  (AG-0.3, AG-0.5) each runtime of the catalog, installed
+ *           first: its status, the CLI it runs and where that came from
+ *           (workspace or user.yml setting, login shell, PATH, install
+ *           directory, interactive shell), its
+ *           version (its version command, once, under a timeout), the
+ *           directories searched (names only, never an env value), and the
+ *           fix when it is missing. Exit 1 when the default runtime is
+ *           unavailable. It resolves the login shell's PATH first, as the
+ *           web server does at start.
  *
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start, counting agents only.
  */
 import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
+import { initLoginPath } from "../../shared/agents/runtime-search.js";
 import { HostError } from "../../shared/sessions/client.js";
 import {
   AgentError,
   listAgents,
   listPersonas as personaList,
+  listRuntimes,
   loadAgentWorkspaces,
   resolveAgentsDeps,
   resumeAgent,
@@ -42,6 +53,7 @@ import {
   type AgentsDeps,
   type AgentsResolved,
   type EarlyExit,
+  type RuntimeChoice,
   type Started,
 } from "./agent-ops.js";
 import {
@@ -63,7 +75,7 @@ export {
 } from "./agent-ops.js";
 
 export const AGENTS_HELP = {
-  usage: "agents <list|start|stop|resume|personas> ...",
+  usage: "agents <list|start|stop|resume|personas|doctor> ...",
   lines: [
     "Agents: a persona and a workspace, run by a runtime in a session that",
     "outlives the web server (see `{cli} sessions`).",
@@ -78,9 +90,20 @@ export const AGENTS_HELP = {
     "    a session never prompted starts fresh under the same conversation id",
     "{cli} agents personas [--json]",
     "    Den's default pack, then agents.persona_packs (a later pack wins by id)",
+    "{cli} agents doctor [-w <ws>] [--json]",
+    "    each runtime, installed first: status, the CLI it runs and where it came",
+    "    from, its version, the directories searched, and the fix; exit 1 when the",
+    "    default is missing. -w: as that workspace's agents find them",
     "",
-    "Runtimes: den-claude (default; needs claude on PATH) and generic (the",
-    "persona's argv template). Attach with `{cli} sessions attach <ws>:<id>`.",
+    "Runtimes: den-claude (default; Claude Code's claude), codex (OpenAI's Codex",
+    "CLI), gemini (Google's Gemini CLI), grok (xAI's Grok Build), and generic (the",
+    "persona's argv template). codex, gemini and grok run as their own CLI in the",
+    "workspace, without Den's tools yet. Attach with `{cli} sessions attach <ws>:<id>`.",
+    "A runtime's CLI is found as your terminal finds it: <ws>.agents.runtimes.<id>.bin",
+    "in config/local/workspaces.yml, then agents.runtimes.<id>.bin in",
+    "config/local/user.yml (absolute paths), then the login shell's PATH, this PATH,",
+    "its install directories (~/.local/bin, /opt/homebrew/bin, /usr/local/bin, npm's",
+    "global bin, the vendor's own), and last the interactive shell's PATH.",
     "An agent's env is PATH, HOME, USER, LOGNAME, SHELL, TERM, COLORTERM, LANG,",
     "LC_*, TZ and TMPDIR, plus what its runtime declares: nothing else of yours.",
   ],
@@ -250,10 +273,108 @@ async function listPersonas(
   return 0;
 }
 
+export interface AgentsDoctorDeps {
+  /** Resolve the login shell's PATH first (default: initLoginPath). */
+  loginPath?: () => Promise<void>;
+}
+
+const SOURCE_WORD: Record<string, string> = {
+  workspace: "the workspace's agents.runtimes setting",
+  setting: "agents.runtimes setting",
+  "login-shell": "login shell PATH",
+  PATH: "PATH",
+  "well-known": "install directory",
+  "interactive-shell": "interactive shell PATH",
+};
+
+/** `agents doctor`'s lines for one runtime (names and paths, never env values). */
+export function doctorLines(
+  r: RuntimeChoice,
+  cli: string,
+  userConfig: string,
+  /** Directory lists already printed (a repeat is counted, not listed). */
+  printed: string[] = [],
+): string[] {
+  const lines = [
+    `${r.id}${r.label ? ` (${r.label}${r.vendor ? `, ${r.vendor}` : ""})` : ""}${r.default ? "  [default]" : ""}${r.denTools === false ? "  [Den tools: coming]" : ""}`,
+    r.available
+      ? "  status    ✓ available"
+      : `  status    ✗ unavailable: ${r.why ?? "unknown"}`,
+  ];
+  if (r.path)
+    lines.push(
+      `  path      ${r.path}${r.source ? ` (${SOURCE_WORD[r.source] ?? r.source})` : ""}`,
+    );
+  if (r.available && r.setting)
+    lines.push(`  version   ${r.version ?? "unknown"}`);
+  if (!r.setting) lines.push("  path      none to find (the persona's argv)");
+  else if (r.searched?.length) {
+    const key = r.searched.join("\0");
+    if (printed.includes(key))
+      lines.push(
+        `  searched  the same ${r.searched.length} ${r.searched.length === 1 ? "directory" : "directories"} as above`,
+      );
+    else {
+      printed.push(key);
+      r.searched.forEach((dir, i) =>
+        lines.push(`  ${i === 0 ? "searched  " : "          "}${dir}`),
+      );
+    }
+  } else if (r.source !== "setting") lines.push("  searched  (no directories)");
+  if (!r.available && r.setting)
+    lines.push(
+      `  fix       install ${r.label ?? r.id}, or set ${r.setting} to its absolute path in ${userConfig}`,
+      `            then run \`${cli} agents doctor\` again`,
+    );
+  return lines;
+}
+
+async function doctor(
+  args: string[],
+  d: AgentsResolved,
+  deps: AgentsDoctorDeps,
+): Promise<number> {
+  const where = "agents doctor";
+  const p = parseArgs(where, args, { "--workspace": true, "--json": false });
+  noExtra(where, p);
+  const ws = workspaceFlag(where, p);
+  if (ws && !d.workspaceExists(ws))
+    throw new UsageError(`${where}: workspace "${ws}" does not exist`);
+  await (deps.loginPath ?? (() => initLoginPath({ env: d.env })))();
+  const rts = await listRuntimes(d, ws);
+  const def = rts.find((r) => r.default);
+  const code = def?.available ? 0 : 1;
+  if (p.flags["--json"]) {
+    d.out(
+      JSON.stringify(
+        {
+          runtimes: rts,
+          ...(ws ? { workspace: ws } : {}),
+          userConfig: d.userConfigFile(),
+        },
+        null,
+        2,
+      ),
+    );
+    return code;
+  }
+  const printed: string[] = [];
+  rts.forEach((r, i) => {
+    if (i) d.out("");
+    for (const l of doctorLines(r, d.cli, d.userConfigFile(), printed))
+      d.out(l);
+  });
+  d.out("");
+  d.out(
+    `\`${d.cli} doctor --probe\` checks the env each runtime's session gets.`,
+  );
+  return code;
+}
+
 /** `<cli> agents ...`; returns the exit code. */
 export async function cmdAgents(
   args: string[],
-  deps: AgentsDeps = {},
+  deps: AgentsDeps & AgentsDoctorDeps = {},
 ): Promise<number> {
   const d = resolveAgentsDeps(deps);
   const sub =
@@ -274,6 +395,10 @@ export async function cmdAgents(
           return await resume(rest, d);
         case "personas":
           return await listPersonas(rest, d);
+        case "doctor":
+          // -w checks the workspace exists, and reads its runtime paths.
+          await loadAgentWorkspaces(deps);
+          return await doctor(rest, d, deps);
         default:
           throw new UsageError(`unknown agents command "${sub}"`);
       }

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

@@ -25,7 +25,11 @@ import {
   routerUrls,
   type IncludedRouter,
 } from "../../shared/edge/included.js";
-import { edgeRoutes, edgeStatus } from "../../shared/edge/status.js";
+import {
+  edgeRoutes,
+  edgeStatus,
+  withHttpsServing,
+} from "../../shared/edge/status.js";
 import { tlsYaml } from "../../shared/edge/tls.js";
 import { rejoinRunningStacks } from "../../shared/stacks/status.js";
 
@@ -102,7 +106,7 @@ export async function cmdEdge(args: string[]): Promise<void> {
       return;
     }
     case "status": {
-      const st = edgeStatus(cfg);
+      const st = await withHttpsServing(edgeStatus(cfg), cfg);
       console.log(chalk.bold(`${readBrand().name} edge — ${st.org}`));
       console.log(`  container  ${st.container}: ${st.state}`);
       console.log(`  ports      ${published}`);
@@ -116,7 +120,16 @@ export async function cmdEdge(args: string[]): Promise<void> {
           // browser trust (BOOT-1), so this machine's trust is moot.
           `  CA         ${caDir(cfg)} — ${!st.ports ? "not needed: fronted" : st.caTrusted === null ? "unknown" : st.caTrusted ? "trusted" : "NOT trusted"}`,
         );
-      if (st.certIssued) console.log(`  cert       ${st.certNames.join(", ")}`);
+      if (st.certIssuedByDen)
+        console.log(`  cert       ${st.certNames.join(", ")}`);
+      else if (st.https.certs === "distribution")
+        console.log(
+          "  cert       the distribution's (tls: files): not minted by Den",
+        );
+      // MCP-2.5: whether HTTPS is actually serving, not only configured.
+      console.log(
+        `  https      ${st.https.serving === null ? "not probed" : st.https.serving ? "serving" : "NOT serving"} — ${st.https.detail}`,
+      );
       return;
     }
     default:

package/src/ui/cli/health-display.ts

@@ -77,11 +77,14 @@ export function formatRollupLabel(r: RepoRollup): string {
 
 /**
  * Why, for a repo row: the down services ("mailpit down"), and how many
- * services aren't checked ("25 not checked"). Unchecked never means down.
+ * services aren't checked ("25 not checked"), and how many answered with a
+ * redirect ("1 redirect": answering, so neither down nor unchecked).
+ * Unchecked never means down.
  */
 export function rollupReasonText(r: RepoRollup): string {
   return [
     r.down.length ? `${r.down.join(", ")} down` : "",
+    r.redirected ? `${r.redirected} redirect` : "",
     r.unchecked ? `${r.unchecked} not checked` : "",
   ]
     .filter(Boolean)