@monster-orange/den 0.4.3 → 0.4.4

package/src/shared/agents/runtime.ts

@@ -13,8 +13,10 @@ import {
   getStrategy,
   registerStrategy,
   strategyIds,
+  unregisterStrategy,
   type StrategyEntry,
 } from "../strategies/registry.js";
+import type { CatalogEntry } from "./catalog.js";
 import type { Persona } from "./personas.js";
 import type { BinSource, RuntimeFind } from "./runtime-search.js";
 
@@ -39,7 +41,8 @@ export interface RuntimeDetect {
 export interface DetectOptions {
   /**
    * `agents.runtimes.<id>.bin` as configured in user.yml (undefined:
-   * read it there; null: none).
+   * read it there; null: none), or a BinSetting (runtime-search.ts) that
+   * says where it was set (the workspace's, or global).
    */
   bin?: unknown;
 }
@@ -107,6 +110,15 @@ export interface Runtime {
   id: string;
   /** Its name for people ("Claude Code"), in the Start agent form. */
   label?: string;
+  /** Who makes it ("Anthropic"): a catalog runtime's vendor (AG-0.5). */
+  vendor?: string;
+  /** Its catalog entry (catalog.ts), when it is one. */
+  catalog?: CatalogEntry;
+  /**
+   * Whether it runs with Den's tools (its MCP config and guards). false:
+   * it runs as its own CLI, tagged "Den tools: coming" (AG-0.5).
+   */
+  denTools?: boolean;
   /**
    * How its CLI is found and its version asked (AG-0.1): the search's
    * binary names and install directories, per runtime, so a catalog can
@@ -143,6 +155,11 @@ export class LaunchError extends Error {
   }
 }
 
+/** Remove a runtime (a configured catalog entry that is gone). */
+export function unregisterRuntime(id: string): void {
+  unregisterStrategy(RUNTIME_KIND, id);
+}
+
 /** Register a runtime as strategy kind `runtime` (doctor lists it). */
 export function registerRuntime(rt: Runtime): void {
   const entry: StrategyEntry<typeof RUNTIME_KIND, Runtime> = {

package/src/shared/agents/runtimes.ts

@@ -1,7 +1,12 @@
 /**
  * Den's built-in runtimes, registered as strategy kind `runtime`: import
- * this module to have them. den-claude first: it is the default.
+ * this module to have them. den-claude first: it is the default. Then the
+ * rest of the runtime catalog (AG-0.5: codex, gemini, grok), then generic.
+ * Entries a distribution or user.yml adds are registered by
+ * syncConfiguredRuntimes, after the built-ins.
  */
+import { BUILTIN_CATALOG, type CatalogEntry } from "./catalog.js";
+import { catalogRuntime } from "./catalog-runtime.js";
 import { denClaude } from "./den-claude.js";
 import { generic } from "./generic.js";
 import {
@@ -9,6 +14,7 @@ import {
   getRuntime,
   registerRuntime,
   runtimeIds,
+  unregisterRuntime,
   type Runtime,
 } from "./runtime.js";
 import { sessionPath, type RuntimeFind } from "./runtime-search.js";
@@ -16,8 +22,24 @@ import { ACTOR_TOKEN_ENV } from "../actor-token.js";
 import { AGENT_ACTOR_ENV, buildSessionEnv } from "../sessions/env.js";
 
 registerRuntime(denClaude);
+for (const e of BUILTIN_CATALOG)
+  if (e.id !== denClaude.id) registerRuntime(catalogRuntime(e));
 registerRuntime(generic);
 
+let configured: string[] = [];
+
+/**
+ * Register the catalog entries a distribution and user.yml add (already
+ * checked: catalog.ts validateCatalog), replacing the last set: an entry
+ * taken out of the config is no runtime any more.
+ */
+export function syncConfiguredRuntimes(entries: readonly CatalogEntry[]): void {
+  const ids = entries.map((e) => e.id);
+  for (const id of configured) if (!ids.includes(id)) unregisterRuntime(id);
+  for (const e of entries) registerRuntime(catalogRuntime(e));
+  configured = ids;
+}
+
 export {
   allScrubEnv,
   DEFAULT_RUNTIME_ID,

package/src/shared/auth/sudo-vault.ts

@@ -125,6 +125,22 @@ export async function sudoVaultStatus(): Promise<SudoVaultStatus> {
   return out(true, await hasSudoInVault());
 }
 
+/**
+ * Where a saved password would be kept, for Settings' "saved in <label>"
+ * (LK-0): read from the config alone, nothing spawned (a page view never
+ * wakes the vault).
+ */
+export function sudoVaultWhere(): { configured: boolean; label: string } {
+  try {
+    const st = secretsStatus(readSecretsConfig(), process.env, {
+      detect: false,
+    });
+    return { configured: !!sudoRef(), label: st.label };
+  } catch {
+    return { configured: false, label: "" };
+  }
+}
+
 /** Name of the active backend, for UI copy ("Save to Doppler"). */
 export function secretsBackendLabel(): string {
   return secretsStatus().label;

package/src/shared/den-config.ts

@@ -18,6 +18,7 @@ import type { SecretsConfig } from "./secrets/index.js";
 import type { OrgConfig } from "./org.js";
 import { validateOrgSources, type WorkOrgsConfig } from "./org-sources.js";
 import { ConfigError, isConfigError } from "./config-error.js";
+import { validateCatalog, type CatalogEntry } from "./agents/catalog.js";
 import type { TestAccountsConfig } from "./auth/test-accounts.js";
 
 import { product } from "./product.js";
@@ -385,7 +386,11 @@ export interface UserConfig {
    * install directories). Per machine, so user.yml only: the distribution's
    * config never sets a path. See shared/agents/runtime-search.ts.
    */
-  agents?: { runtimes?: Record<string, { bin?: unknown } | null> };
+  agents?: {
+    runtimes?: Record<string, { bin?: unknown } | null>;
+    /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
+    runtime_catalog?: unknown;
+  };
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [
@@ -436,6 +441,40 @@ export function configuredRuntimeBin(
   }
 }
 
+/**
+ * user.yml's `agents.runtime_catalog`, checked (agents/catalog.ts), after
+ * the built-in entries and the distribution's (`taken`). Throws naming
+ * the key when malformed.
+ */
+export function configuredRuntimeCatalog(
+  taken: readonly string[],
+  read: () => UserConfig = readUserConfig,
+): CatalogEntry[] {
+  return validateCatalog(
+    read().agents?.runtime_catalog,
+    `agents.runtime_catalog (${path.basename(USER_CONFIG_PATH)})`,
+    taken,
+  );
+}
+
+/**
+ * Set (a path) or clear (null) `agents.runtimes.<id>.bin` in user.yml,
+ * keeping everything else there. The caller checks the path first.
+ */
+export function setUserRuntimeBin(id: string, bin: string | null): void {
+  const cfg = readUserConfig();
+  const agents = { ...(cfg.agents ?? {}) };
+  const runtimes = { ...(agents.runtimes ?? {}) };
+  if (bin === null) delete runtimes[id];
+  else runtimes[id] = { ...(runtimes[id] ?? {}), bin };
+  if (Object.keys(runtimes).length) agents.runtimes = runtimes;
+  else delete agents.runtimes;
+  const next: UserConfig = { ...cfg };
+  if (Object.keys(agents).length) next.agents = agents;
+  else delete next.agents;
+  writeUserConfig(next);
+}
+
 /** Read the per-engineer user config (config/local/user.yml). Returns {} if absent. */
 export function readUserConfig(): UserConfig {
   try {
@@ -790,6 +829,11 @@ export interface AgentsConfig {
    * persona replaces one of the same id.
    */
   persona_packs?: string[];
+  /**
+   * More runtime catalog entries (AG-0.5, agents/catalog.ts): a vendor CLI
+   * Den doesn't ship, with the same fields and checks as a built-in one.
+   */
+  runtime_catalog?: unknown[];
   /**
    * Any other key is an agent id: `agents.<id>.grants` widens that agent's
    * MCP scope to other workspaces (AG spec §5b). Config only: an agent
@@ -801,7 +845,11 @@ export interface AgentsConfig {
 export const DEFAULT_AGENTS_MAX_CONCURRENT = 4;
 
 /** The keys of `agents:` that are not an agent id. */
-export const AGENTS_RESERVED_KEYS = ["max_concurrent", "persona_packs"];
+export const AGENTS_RESERVED_KEYS = [
+  "max_concurrent",
+  "persona_packs",
+  "runtime_catalog",
+];
 
 /** One agent's own block, `agents.<id>`. */
 export interface AgentGrantsConfig {
@@ -816,6 +864,8 @@ export interface ResolvedAgentsConfig {
   personaPacks: string[];
   /** `agents.<id>` blocks, by agent id. */
   agents: Record<string, AgentGrantsConfig>;
+  /** The distribution's runtime catalog entries (AG-0.5), checked. */
+  runtimeCatalog: CatalogEntry[];
 }
 
 /** An agent id or workspace name: what WORKSPACE_NAME_RE accepts. */
@@ -838,6 +888,10 @@ export function readAgentsConfig(
     maxConcurrent: DEFAULT_AGENTS_MAX_CONCURRENT,
     personaPacks: [],
     agents: {},
+    runtimeCatalog: validateCatalog(
+      raw.runtime_catalog,
+      "agents.runtime_catalog",
+    ),
   };
   const max = raw.max_concurrent;
   if (max !== undefined) {
@@ -866,7 +920,7 @@ export function readAgentsConfig(
     const where = `agents.${id}`;
     if (!AGENT_KEY_RE.test(id) || !isMapping(block))
       throw new Error(
-        `${where}: unknown key (agents: takes max_concurrent, persona_packs, ` +
+        `${where}: unknown key (agents: takes max_concurrent, persona_packs, runtime_catalog, ` +
           `or an agent id mapping to { grants: [...] })`,
       );
     for (const k of Object.keys(block))

package/src/shared/edge/status.ts

@@ -5,6 +5,7 @@
  */
 import * as fs from "fs";
 import * as path from "path";
+import * as tls from "tls";
 import { certNames, edgeDomains, edgeNames, routeUrl } from "./render.js";
 import {
   includedRouters,
@@ -28,7 +29,18 @@ export interface EdgeStatus {
   routes: { name: string; url: string; upstream: string }[];
   /** Names on the issued cert, or the planned ones when none is issued yet. */
   certNames: string[];
+  /**
+   * Whether Den minted the edge's cert itself (mkcert: its names stamp is
+   * there). False under `tls: files` (the distribution supplies the cert)
+   * and `tls: none`, whether or not HTTPS serves: see `https`.
+   */
+  certIssuedByDen: boolean;
+  /** @deprecated certIssuedByDen (MCP-2.5); kept for one release. */
   certIssued: boolean;
+  /** MCP-2.5: the TLS strategy in words, and whether HTTPS is serving. */
+  https: EdgeHttps;
+  /** Fields kept for one release under an old name, and what replaces them. */
+  deprecated: { certIssued: string };
   /** Whether the CA is trusted on this machine (null: can't tell, or none). */
   caTrusted: boolean | null;
   /**
@@ -59,6 +71,28 @@ export interface EdgeStatus {
   stackErrors: IncludedRouters["errors"];
 }
 
+export interface EdgeHttps {
+  strategy: EdgeConfig["tls"]["strategy"];
+  /**
+   * Who supplies the cert: "den" (mkcert, minted here), "distribution"
+   * (`tls: files`, or the legacy `issue_cert: false`), or "none" (http only).
+   */
+  certs: "den" | "distribution" | "none";
+  /**
+   * Whether the edge answers a TLS handshake on its https port: true, false,
+   * or null when it was not probed (`edge status` from the CLI, or a proxy
+   * in front owns the port).
+   */
+  serving: boolean | null;
+  /** How `serving` was decided, in words. */
+  detail: string;
+}
+
+export const CERT_ISSUED_DEPRECATION =
+  "certIssued is renamed certIssuedByDen (0.4.4) and goes in the release " +
+  "after: it says whether Den minted the cert itself, so it is false under " +
+  "tls strategy files while HTTPS serves. Read https.serving for that.";
+
 export interface EdgeStatusDeps {
   containerState: (name: string) => string;
   caTrusted: (cfg: EdgeConfig) => boolean | null;
@@ -113,7 +147,23 @@ export function edgeStatus(
     domains: edgeDomains(cfg),
     routes: edgeRoutes(cfg),
     certNames: issued ?? (cfg.tls.strategy === "none" ? [] : certNames(cfg)),
+    certIssuedByDen: issued !== null,
     certIssued: issued !== null,
+    https: {
+      strategy: cfg.tls.strategy,
+      certs:
+        cfg.tls.strategy === "mkcert"
+          ? "den"
+          : cfg.tls.strategy === "files"
+            ? "distribution"
+            : "none",
+      serving: cfg.tls.strategy === "none" ? false : null,
+      detail:
+        cfg.tls.strategy === "none"
+          ? "tls: none: the edge serves http only"
+          : "not probed",
+    },
+    deprecated: { certIssued: CERT_ISSUED_DEPRECATION },
     caTrusted: cfg.tls.strategy === "none" ? null : deps.caTrusted(cfg),
     tls: {
       strategy: cfg.tls.strategy,
@@ -132,3 +182,87 @@ export function edgeStatus(
     stackErrors: stk.errors,
   };
 }
+
+/** One TLS handshake: whether something on host:port speaks TLS. */
+export type TlsHandshake = (o: {
+  host: string;
+  port: number;
+  servername: string;
+  timeoutMs: number;
+}) => Promise<{ ok: boolean; error?: string }>;
+
+/**
+ * Connect, complete a TLS handshake, close. Trust is not checked here (that
+ * is `caTrusted`): only whether HTTPS is being served at all.
+ */
+export const tlsHandshake: TlsHandshake = ({
+  host,
+  port,
+  servername,
+  timeoutMs,
+}) =>
+  new Promise((resolve) => {
+    let settled = false;
+    const done = (v: { ok: boolean; error?: string }) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      resolve(v);
+    };
+    const socket = tls.connect({
+      host,
+      port,
+      servername,
+      rejectUnauthorized: false,
+    });
+    const timer = setTimeout(
+      () => done({ ok: false, error: `no TLS answer in ${timeoutMs}ms` }),
+      timeoutMs,
+    );
+    socket.once("secureConnect", () => done({ ok: true }));
+    socket.once("error", (e: NodeJS.ErrnoException) =>
+      done({ ok: false, error: e.code ?? e.message }),
+    );
+    socket.once("close", () =>
+      done({ ok: false, error: "closed before a TLS handshake" }),
+    );
+  });
+
+/**
+ * `st` with `https.serving` probed (MCP-2.5): a TLS handshake on this
+ * machine's published https port, named as one of the edge's hosts. Not
+ * probed when a proxy in front owns the port (no published ports), and
+ * false without a handshake when the edge container is not running.
+ */
+export async function withHttpsServing(
+  st: EdgeStatus,
+  cfg: EdgeConfig,
+  handshake: TlsHandshake = tlsHandshake,
+): Promise<EdgeStatus> {
+  if (cfg.tls.strategy === "none") return st;
+  const set = (serving: boolean | null, detail: string): EdgeStatus => ({
+    ...st,
+    https: { ...st.https, serving, detail },
+  });
+  if (!st.ports)
+    return set(
+      null,
+      "not probed: a proxy in front of the edge owns its ports (edge.publish: false)",
+    );
+  if (!st.up) return set(false, `the edge container is ${st.state}`);
+  const port = st.ports.https;
+  const servername = `${Object.keys(cfg.routes)[0] ?? "edge"}.${cfg.domain}`;
+  const r = await handshake({
+    host: "127.0.0.1",
+    port,
+    servername,
+    timeoutMs: 1500,
+  });
+  return r.ok
+    ? set(true, `TLS handshake answered on 127.0.0.1:${port} (${servername})`)
+    : set(
+        false,
+        `no TLS on 127.0.0.1:${port} (${servername}): ${r.error ?? "failed"}`,
+      );
+}

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

@@ -63,6 +63,14 @@ export interface PingResult {
   pending?: boolean;
   status?: number;
   error?: string;
+  /**
+   * MCP-2.4: the check answered with a redirect (3xx, `status`): where it
+   * points, as a path for the same origin, else origin + path (the query
+   * and fragment are dropped: they can carry tokens). A redirect is not
+   * down and not up (ok null): the service answered, and the check was
+   * sent elsewhere.
+   */
+  redirect?: string;
 }
 
 export interface ServiceHealthResult {
@@ -255,6 +263,41 @@ function statusOk(status: number, body404?: string): boolean {
   return status < 300 || (status >= 400 && status < 500);
 }
 
+/** A 3xx: the check was sent elsewhere (redirect: "manual"). */
+export function isRedirect(status: number | undefined): boolean {
+  return status !== undefined && status >= 300 && status < 400;
+}
+
+/**
+ * Where a redirect points, for a health row: a path when it stays on the
+ * checked URL's origin, else origin + path. Never the query or fragment
+ * (a login redirect's `?next=` or `state=` can carry a token).
+ */
+export function redirectTarget(
+  location: string | null | undefined,
+  from: string,
+): string {
+  if (!location) return "(no Location header)";
+  try {
+    const to = new URL(location, from);
+    const base = new URL(from);
+    return to.origin === base.origin
+      ? to.pathname
+      : `${to.origin}${to.pathname}`;
+  } catch {
+    return "(unreadable Location header)";
+  }
+}
+
+/** The PingResult for a 3xx: not down, not up, and where it points. */
+function redirectResult(
+  status: number,
+  location: string | null | undefined,
+  from: string,
+): PingResult {
+  return { ok: null, status, redirect: redirectTarget(location, from) };
+}
+
 /** The PingResult for `status`, naming an edge 404 as "no route". */
 function statusResult(status: number, body404?: string): PingResult {
   const ok = statusOk(status, body404);
@@ -309,6 +352,12 @@ async function pingHttps(parsed: URL, timeoutMs: number): Promise<PingResult> {
       },
       (res) => {
         const status = res.statusCode ?? 0;
+        if (isRedirect(status)) {
+          res.resume(); // discard the body
+          const loc = res.headers.location;
+          done(redirectResult(status, loc, parsed.toString()));
+          return;
+        }
         if (status !== 404) {
           res.resume(); // discard the body
           done({ ok: statusOk(status), status });
@@ -374,14 +423,21 @@ async function pingOnce(
     });
     clearTimeout(timer);
     // 2xx = healthy. 4xx = healthy (service is up; auth/route 4xx still proves it's responding).
-    // 3xx = unhealthy: with redirect:"manual", a redirect means "go verify somewhere else"
-    // and we haven't confirmed anything. Guards against hostname-to-AWS-ALB resolution
-    // (e.g. VPN / /etc/hosts) returning 301 on port 80 for services that actually run
-    // on a different port — the previous `< 500` check showed those as green.
+    // 3xx = a redirect (MCP-2.4): ok null, with its status and target. With
+    // redirect:"manual" a redirect means "go verify somewhere else", so it
+    // is never green: that guards against hostname-to-AWS-ALB resolution
+    // (e.g. VPN / /etc/hosts) returning 301 on port 80 for services that
+    // actually run on a different port (the old `< 500` check showed those
+    // green). It is not down either: something answered, and a login
+    // redirect (302 → /login) is how a healthy app answers a bare GET.
     // 5xx = unhealthy (service errored).
     // A 404 may be the edge's own "no route" (see EDGE_NO_ROUTE_BODY): read
     // a little of it. Otherwise discard the body: only the status matters,
     // and unconsumed bodies pin sockets in the long-lived web server.
+    if (isRedirect(res.status)) {
+      void res.body?.cancel().catch(() => {});
+      return redirectResult(res.status, res.headers?.get("location"), url);
+    }
     if (res.status === 404) {
       let body = "";
       try {
@@ -421,12 +477,17 @@ export async function pingHttp(
   // never a localhost fallback (it is not on this machine).
   if (expect !== undefined) {
     const r = await pingOnce(url, timeoutMs);
-    return r.status === undefined
-      ? r
-      : { ok: expectMatches(r.status, expect), status: r.status };
+    if (r.status === undefined) return r;
+    if (expectMatches(r.status, expect)) return { ok: true, status: r.status };
+    // A redirect the manifest does not list as up is still a redirect, not
+    // down (MCP-2.4): a production app answering 302 → /login is serving.
+    if (r.redirect !== undefined) return r;
+    return { ok: false, status: r.status };
   }
   const result = await pingOnce(url, timeoutMs);
-  if (!result.ok) {
+  // A redirect answered: no localhost fallback (that is for a name that
+  // could not be reached at all).
+  if (result.ok === false) {
     // Fall back to localhost for Docker-style hostnames regardless of how the
     // first ping failed. Timeouts on the primary are legitimate candidates for
     // retry: on macOS, VPN/`/etc/hosts` can resolve a Docker hostname to an
@@ -689,8 +750,17 @@ export function containerTarget(
     : { project: h.project, service: h.service };
 }
 
+/** A health row whose check answered with a redirect (see checkService). */
+export function isRedirectDetail(detail: string | undefined): boolean {
+  return /^redirect \d{3} → /.test(detail ?? "");
+}
+
 /** A ping result as a ServiceHealthResult health state. */
 export function healthState(r: PingResult): ServiceHealthResult["health"] {
+  // A redirect is a verdict of its own (MCP-2.4): not down, and not a check
+  // still waiting to answer. "unknown", like an unchecked service, so a
+  // caller waiting for health proceeds instead of waiting it out.
+  if (r.ok === null && r.redirect !== undefined) return "unknown";
   return r.ok === true ? "ok" : r.ok === false ? "error" : "pending";
 }
 
@@ -814,6 +884,9 @@ export async function checkServiceHealth(
     ...placed,
     health: healthState(result),
     healthDetail:
+      (result.redirect !== undefined
+        ? `redirect ${result.status} → ${result.redirect}`
+        : undefined) ??
       result.error ??
       (!result.ok && result.status !== undefined
         ? `http ${result.status}`
@@ -899,6 +972,7 @@ export function rollupRepoHealth(
         service: r.subsystem,
         ok: r.health === "ok" ? true : r.health === "error" ? false : null,
         isEntrypoint: !!entrypoint && r.subsystem === entrypoint,
+        redirect: isRedirectDetail(r.healthDetail),
       })),
     );
     const lead =

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

@@ -877,3 +877,57 @@ export function generateVSCodeWorkspace(
   );
   return outPath;
 }
+
+/** The key of workspace `ws`'s runtime path, as a refusal names it. */
+export const workspaceBinKey = (ws: string, id: string) =>
+  `workspaces.${ws}.agents.runtimes.${id}.bin`;
+
+/**
+ * `<ws>.agents.runtimes.<id>.bin` in config/local/workspaces.yml (AG-0.5),
+ * as written (checked where it is used); undefined when unset or when the
+ * file can't be read. A block that is no mapping is `{ why }`.
+ */
+export function workspaceRuntimeBin(
+  ws: string,
+  id: string,
+  read: () => WorkspacesFile = readWorkspacesFile,
+): unknown {
+  try {
+    const rts = read().workspaces[ws]?.agents?.runtimes;
+    if (!rts || typeof rts !== "object") return undefined;
+    const block = (rts as Record<string, unknown>)[id];
+    if (block === undefined || block === null) return undefined;
+    if (typeof block !== "object" || Array.isArray(block))
+      return {
+        why: `${workspaceBinKey(ws, id).replace(/\.bin$/, "")} must be a mapping ({ bin: <absolute path> })`,
+      };
+    return (block as { bin?: unknown }).bin;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Set (a path) or clear (null) workspace `ws`'s
+ * `agents.runtimes.<id>.bin`. The caller checks the path first.
+ */
+export function setWorkspaceRuntimeBin(
+  ws: string,
+  id: string,
+  bin: string | null,
+): void {
+  const file = readWorkspacesFile();
+  const cfg = file.workspaces[ws];
+  if (!cfg) throw new Error(`workspace "${ws}" does not exist`);
+  const agents = { ...(cfg.agents ?? {}) };
+  const runtimes = { ...(agents.runtimes ?? {}) };
+  if (bin === null) delete runtimes[id];
+  else runtimes[id] = { ...(runtimes[id] ?? {}), bin };
+  if (Object.keys(runtimes).length) agents.runtimes = runtimes;
+  else delete agents.runtimes;
+  const next = { ...cfg };
+  if (Object.keys(agents).length) next.agents = agents;
+  else delete next.agents;
+  file.workspaces[ws] = next;
+  writeWorkspacesFile(file);
+}

package/src/shared/health/not-checked.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP-2.4: why a service has no health verdict, in words. A row with `ok:
+ * null` and no reason reads as "broken" to an agent (it fell back to
+ * `docker ps`); every unchecked row says which of these it is. One rule for
+ * the web health row (/api/health) and the MCP `status` tool, which derives
+ * it from a row an older web server served without one.
+ */
+import { product } from "../product.js";
+import type { Runs } from "../manifest/placement.js";
+
+export interface NotCheckedInput {
+  /** The env being viewed. */
+  env: string;
+  runs: Runs | undefined;
+  /** A remote service's target (its env), when it has one. */
+  target?: { env?: string } | null;
+  /** false when the repo has no manifest at all. */
+  manifest?: boolean;
+  /** The conventional probe tried (and not answered 2xx), if any. */
+  conventional?: string | null;
+}
+
+export function notCheckedReason(o: NotCheckedInput): string {
+  if (o.manifest === false)
+    return `not checked: the repo has no ${product().manifestYml}`;
+  if (o.runs === "remote") {
+    const where = o.target?.env ?? o.env;
+    return (
+      `not checked: remote (runs in ${where}), and the manifest declares ` +
+      `no health check or target.url for ${where}`
+    );
+  }
+  if (o.runs === "none" || o.runs === undefined)
+    return (
+      `not checked: not deployed in ${o.env} (the manifest has no ` +
+      `commands and no health check for ${o.env})`
+    );
+  return (
+    `not checked: no health check in the manifest for ${o.env}` +
+    (o.conventional ? `, and ${o.conventional} did not answer 2xx` : "")
+  );
+}

package/src/shared/health/rollup.ts

@@ -17,6 +17,8 @@ export interface HealthSignal {
   isEntrypoint?: boolean;
   /** Not answered yet this cycle: the repo stays unknown until it has. */
   awaiting?: boolean;
+  /** The check answered with a redirect (ok null): counted as a redirect. */
+  redirect?: boolean;
 }
 
 export interface RepoRollup {
@@ -29,6 +31,8 @@ export interface RepoRollup {
   unchecked: number;
   /** Checks that haven't answered yet; any holds the state at unknown. */
   awaiting: number;
+  /** Checks that answered with a redirect (not in `unchecked`); absent at 0. */
+  redirected?: number;
 }
 
 export const STATE_RANK: Record<RepoState, number> = rollup.STATE_RANK;