@monster-orange/den 0.4.2 → 0.4.4

package/src/shared/agents/runtimes.ts

@@ -1,16 +1,45 @@
 /**
  * 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 { allScrubEnv, registerRuntime, type Runtime } from "./runtime.js";
+import {
+  allScrubEnv,
+  getRuntime,
+  registerRuntime,
+  runtimeIds,
+  unregisterRuntime,
+  type Runtime,
+} from "./runtime.js";
+import { sessionPath, type RuntimeFind } from "./runtime-search.js";
 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,
@@ -25,9 +54,27 @@ export {
   type Runtime,
 } from "./runtime.js";
 
+/** Every registered runtime's find (its well-known directories). */
+export function allRuntimeFinds(): (RuntimeFind | undefined)[] {
+  return runtimeIds().map((id) => getRuntime(id)?.find);
+}
+
+/**
+ * The caller's env with the PATH a session gets (AG-0.1): the login
+ * shell's PATH, the caller's, then every runtime's install directories
+ * that exist, and `extraDirs` (a configured CLI's directory).
+ */
+export function withSessionPath(
+  caller: NodeJS.ProcessEnv,
+  extraDirs: readonly string[] = [],
+): NodeJS.ProcessEnv {
+  const PATH = sessionPath(caller, allRuntimeFinds(), extraDirs);
+  return PATH === caller.PATH ? caller : { ...caller, PATH };
+}
+
 /**
  * An agent's session env, as `agents start` builds it and `doctor --probe`
- * checks it: the allowlist, the runtime's passthrough and launch env, Den's
+ * checks it: the allowlist (its PATH the search's, withSessionPath), the runtime's passthrough and launch env, Den's
  * markers (DEN_AGENT=agent:<id>, and SEC-1c's DEN_ACTOR_TOKEN when one was
  * minted), then every runtime's scrubEnv and any person credential.
  */
@@ -38,9 +85,11 @@ export function agentSessionEnv(
   agentId: string,
   /** SEC-1c: the agent's actor token (`agents start` mints it; the probe has none). */
   actorToken?: string,
+  /** Added to its PATH: the directory of the CLI it runs. */
+  extraDirs: readonly string[] = [],
 ): Record<string, string> {
   return buildSessionEnv({
-    caller,
+    caller: withSessionPath(caller, extraDirs),
     passthrough: rt.envPassthrough,
     launch,
     // The seam for a persona's or runtime's declared env: none yet.

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";
@@ -379,6 +380,17 @@ export interface UserConfig {
    * src/shared/environment-manager/scope.ts.
    */
   view?: { scope?: string };
+  /**
+   * Agents on this machine (AG-0.1): `runtimes.<id>.bin`, the absolute path
+   * of a runtime's CLI, which wins over the search (login shell PATH, PATH,
+   * 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>;
+    /** More runtime catalog entries (AG-0.5, agents/catalog.ts). */
+    runtime_catalog?: unknown;
+  };
 }
 
 const ALL_ENVIRONMENTS: Environment[] = [
@@ -400,6 +412,69 @@ const DEFAULT_CONFIG: DenConfig = {
   environments: ALL_ENVIRONMENTS,
 };
 
+/** The per-engineer user config's path (config/local/user.yml), absolute. */
+export function userConfigPath(): string {
+  return USER_CONFIG_PATH;
+}
+
+/**
+ * `agents.runtimes.<id>.bin` from user.yml, as written (checked where it is
+ * used: runtime-search.ts checkBinSetting; a block that is no mapping is
+ * `{ why }`); undefined when unset or when user.yml can't be read.
+ */
+export function configuredRuntimeBin(
+  id: string,
+  read: () => UserConfig = readUserConfig,
+): unknown {
+  try {
+    const rts = read().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: `agents.runtimes.${id} must be a mapping ({ bin: <absolute path> })`,
+      };
+    return (block as { bin?: unknown }).bin;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 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 {
@@ -754,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
@@ -765,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 {
@@ -780,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. */
@@ -802,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) {
@@ -830,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/render.ts

@@ -70,6 +70,37 @@ export function routeUrl(
   return `https://${routeHost(name, domain)}${p === 443 ? "" : `:${p}`}`;
 }
 
+/**
+ * The edge routes to a web server on one of `ports` (an upstream on the
+ * docker host or loopback), under every edge domain: `{ host, url }`, the
+ * hostname (lowercase) and the URL a browser uses there.
+ */
+export function webRouteHosts(
+  cfg: EdgeConfig,
+  ports: ReadonlySet<number>,
+): { host: string; url: string }[] {
+  return Object.entries(cfg.routes)
+    .filter(([, upstream]) => {
+      try {
+        const u = new URL(upstream);
+        return (
+          ports.has(Number(u.port || (u.protocol === "https:" ? 443 : 80))) &&
+          ["host.docker.internal", "localhost", "127.0.0.1"].includes(
+            u.hostname,
+          )
+        );
+      } catch {
+        return false;
+      }
+    })
+    .flatMap(([name]) =>
+      edgeDomains(cfg).map((d) => ({
+        host: routeHost(name, d).toLowerCase(),
+        url: routeUrl(name, cfg, d),
+      })),
+    );
+}
+
 /** Names that go on the org's certificate. */
 export function certNames(cfg: EdgeConfig): string[] {
   const zones = [...cfg.workspaces, ...(cfg.subzones ?? [])];

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);
+}