@monster-orange/den 0.4.1 → 0.4.3

package/src/shared/sessions/client.ts

@@ -16,6 +16,7 @@ import type {
   AttachHandlers,
   Attachment,
   SessionInfo,
+  SessionPool,
   SessionSignal,
   SessionSpec,
 } from "./types.js";
@@ -125,6 +126,11 @@ export class HostClient extends EventEmitter {
     spec: SessionSpec,
     opts: {
       limit?: number;
+      /**
+       * Which running sessions `limit` counts: agents (agents.max_concurrent)
+       * or plain ones (sessions.max_concurrent). Without it, all of them.
+       */
+      pool?: SessionPool;
       /** `--keep-env` names, for the host's audit line (never values). */
       keptEnv?: { name: string; credentialShaped: boolean }[];
       /** Who asked, for that line. */
@@ -139,6 +145,7 @@ export class HostClient extends EventEmitter {
     const r = await this.request("start", {
       spec,
       ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
+      ...(opts.pool !== undefined ? { pool: opts.pool } : {}),
       ...(opts.keptEnv?.length || opts.refusedEnv?.length
         ? { actor: opts.actor ?? "unknown" }
         : {}),

package/src/shared/sessions/den-pty.ts

@@ -21,6 +21,7 @@ import type {
   Attachment,
   SessionBackend,
   SessionInfo,
+  SessionPool,
   SessionRef,
   SessionSignal,
   SessionSpec,
@@ -32,8 +33,10 @@ export { BACKEND_ID as DEN_PTY_ID };
 export interface DenPtyOptions {
   /** A client of the running host (ensureHost). */
   client: HostClient;
-  /** Applied to every start: agents.max_concurrent. */
+  /** Applied to every start, counting `pool`'s running sessions. */
   limit?: number;
+  /** agents (agents.max_concurrent) or sessions (sessions.max_concurrent). */
+  pool?: SessionPool;
 }
 
 export class DenPtyBackend implements SessionBackend {
@@ -49,7 +52,12 @@ export class DenPtyBackend implements SessionBackend {
   }
 
   async start(spec: SessionSpec): Promise<SessionRef> {
-    return (await this.opts.client.start(spec, { limit: this.opts.limit })).ref;
+    return (
+      await this.opts.client.start(spec, {
+        limit: this.opts.limit,
+        ...(this.opts.pool ? { pool: this.opts.pool } : {}),
+      })
+    ).ref;
   }
   list(): Promise<SessionInfo[]> {
     return this.opts.client.list();

package/src/shared/sessions/host.ts

@@ -29,7 +29,12 @@ import {
   type Request,
 } from "./protocol.js";
 import type { PtyLoad, PtyProcess } from "./pty.js";
-import { SESSION_SIGNALS, type SessionInfo } from "./types.js";
+import {
+  SESSION_POOLS,
+  SESSION_SIGNALS,
+  type SessionInfo,
+  type SessionPool,
+} from "./types.js";
 
 export const BACKEND_ID = "den-pty";
 
@@ -58,6 +63,8 @@ interface Session {
   log: ScrollbackLog;
   /** aid → its connection. */
   attachments: Map<string, Conn>;
+  /** The cap it counts against (start's `pool`), when one was named. */
+  pool?: SessionPool;
 }
 
 class Conn {
@@ -82,6 +89,17 @@ class Refusal extends Error {
 const isInt = (n: unknown, min: number, max: number): n is number =>
   typeof n === "number" && Number.isInteger(n) && n >= min && n <= max;
 
+/**
+ * The cap refusal: "2 agents are running and agents.max_concurrent is 2".
+ * With no pool (an older client's limit) every session counts, and the key
+ * is agents.max_concurrent, as it was.
+ */
+function capMessage(live: number, limit: number, pool?: unknown): string {
+  const noun = pool === "agents" ? "agent" : "session";
+  const key = pool === "sessions" ? "sessions" : "agents";
+  return `${live} ${noun}${live === 1 ? " is" : "s are"} running and ${key}.max_concurrent is ${limit}`;
+}
+
 function pidAlive(pid: number): boolean {
   try {
     process.kill(pid, 0);
@@ -528,20 +546,26 @@ export class SessionHost {
     );
     if (same.some((s) => !s.info.exited))
       throw new Refusal("exists", `${name} is already running`);
-    const live = [...this.sessions.values()].filter(
-      (s) => !s.info.exited,
-    ).length;
+    // A cap counts its own pool's running sessions: agents.max_concurrent
+    // the agents, sessions.max_concurrent the plain ones. A limit with no
+    // pool (an older client) counts every running session, as before.
+    const pool = req.pool;
+    if (pool !== undefined && !SESSION_POOLS.includes(pool as SessionPool))
+      throw new Refusal(
+        "bad-request",
+        `pool must be ${SESSION_POOLS.join(" or ")}`,
+      );
     if (req.limit !== undefined) {
       if (!isInt(req.limit, 1, 100_000))
         throw new Refusal(
           "bad-request",
           "limit must be a whole number of at least 1",
         );
+      const live = [...this.sessions.values()].filter(
+        (s) => !s.info.exited && (pool === undefined || s.pool === pool),
+      ).length;
       if (live >= req.limit)
-        throw new Refusal(
-          "cap",
-          `${live} session${live === 1 ? " is" : "s are"} running and agents.max_concurrent is ${req.limit}`,
-        );
+        throw new Refusal("cap", capMessage(live, req.limit, pool));
     }
     const load = this.opts.pty();
     if (!load.available) throw new Refusal("unavailable", load.reason);
@@ -582,6 +606,7 @@ export class SessionHost {
         },
       ),
       attachments: new Map(),
+      ...(pool !== undefined ? { pool: pool as SessionPool } : {}),
     };
     this.sessions.set(id, s);
     this.persist(s);

package/src/shared/sessions/types.ts

@@ -32,6 +32,14 @@ export interface SessionInfo {
   prompted?: boolean;
 }
 
+/**
+ * The cap a start counts against: `agents` (agents.max_concurrent) or
+ * `sessions` (sessions.max_concurrent, the plain ones), each counting only
+ * its own running sessions.
+ */
+export const SESSION_POOLS = ["agents", "sessions"] as const;
+export type SessionPool = (typeof SESSION_POOLS)[number];
+
 /** What to run. `env` is the whole environment: nothing is inherited. */
 export interface SessionSpec {
   name: string;

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
@@ -32,13 +35,15 @@
  *           actor token; the old one stops working.
  *
  * Nothing here takes a grant: grants come from the org config only. The
- * host enforces agents.max_concurrent on every start.
+ * host enforces agents.max_concurrent on every start, counting agents only.
  */
 import * as fs from "fs";
 import * as path from "path";
 import {
   AGENTS_RESERVED_KEYS,
+  configuredRuntimeBin,
   readAgentsConfig,
+  userConfigPath,
   type ResolvedAgentsConfig,
 } from "../../shared/den-config.js";
 import { cliEntrypoint } from "../../shared/engine.js";
@@ -69,6 +74,12 @@ import {
   type LaunchInput,
   type Runtime,
 } from "../../shared/agents/runtimes.js";
+import type { RuntimeDetect } from "../../shared/agents/runtime.js";
+import {
+  binSettingKey,
+  runtimeVersion,
+  type BinSource,
+} from "../../shared/agents/runtime-search.js";
 import { WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
 import {
   bindActorSession,
@@ -103,6 +114,10 @@ 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;
+  /** The user.yml a person edits to set it (default: config/local/user.yml). */
+  userConfigFile?: () => string;
 }
 
 export interface AgentsResolved extends Resolved {
@@ -111,6 +126,8 @@ export interface AgentsResolved extends Resolved {
   workspaceDir: (ws: string) => string;
   mcpServer: () => { command: string[] | string; env: Record<string, string> };
   exitWatchMs: number;
+  runtimeBin: (id: string) => unknown;
+  userConfigFile: () => string;
 }
 
 /** The early-exit watch: at most this long, polling the host. */
@@ -199,6 +216,8 @@ export function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
       }),
     mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
     exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
+    runtimeBin: d.runtimeBin ?? ((id) => configuredRuntimeBin(id)),
+    userConfigFile: d.userConfigFile ?? userConfigPath,
   };
 }
 
@@ -394,29 +413,84 @@ export function listPersonas(d: AgentsResolved): ListedPersona[] {
 
 export interface RuntimeChoice {
   id: string;
+  /** Its name for people ("Claude Code"). */
+  label?: string;
   available: boolean;
   /** Why it is unavailable. */
   why?: string;
   version?: string;
+  /** The CLI it runs (AG-0.2). */
+  path?: string;
+  /** Where that path came from: setting, login-shell, well-known or PATH. */
+  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;
   /** 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,
-    };
-  });
+/**
+ * Whether runtime `rt` can run here (AG-0.1): its setting
+ * (`agents.runtimes.<id>.bin`, from d.runtimeBin), else the search. Runs
+ * nothing.
+ */
+export function detectRuntime(d: AgentsResolved, rt: Runtime): RuntimeDetect {
+  return rt.detect(d.env, { bin: d.runtimeBin(rt.id) ?? null });
+}
+
+/**
+ * Every registered runtime, and whether it can run here, 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.
+ */
+export async function listRuntimes(
+  d: AgentsResolved,
+): Promise<RuntimeChoice[]> {
+  return Promise.all(
+    runtimeIds().map(async (id) => {
+      const rt = getRuntime(id)!;
+      const det = detectRuntime(d, rt);
+      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 } : {}),
+        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) }
+          : {}),
+        resume: Boolean(rt.resume),
+        default: id === DEFAULT_RUNTIME_ID,
+      };
+    }),
+  );
+}
+
+/** Refused unless `rt` can run here; its detect result when it can. */
+function availableOrRefuse(d: AgentsResolved, rt: Runtime): RuntimeDetect {
+  const det = detectRuntime(d, rt);
+  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 +534,15 @@ 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 configured CLI's directory, for its session's PATH (its own tools). */
+function binDirOf(det: RuntimeDetect): { binDir?: string } {
+  return det.source === "setting" && det.path
+    ? { binDir: path.dirname(det.path) }
+    : {};
 }
 
 /** The host's cap refusal as an AgentError (its hint says what to do). */
@@ -511,11 +594,12 @@ 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,
         },
-        { limit: d.maxConcurrent() },
+        { limit: d.maxConcurrent(), pool: "agents" },
       )
       .catch((e: unknown) => capOrThrow(d, e));
   } catch (e) {
@@ -601,6 +685,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 +708,7 @@ function launchInput(
     filesDir: agentFilesDir(d.stateDir(), id),
     stateDir: d.stateDir(),
     env: d.env,
+    ...(bin ? { bin } : {}),
   };
 }
 
@@ -681,9 +767,7 @@ export async function startAgent(
   const id = req.id ?? defaultId(d.stateDir(), persona.id, ws);
   checkId(where, id);
   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 = availableOrRefuse(d, rt);
   const model = req.model ?? persona.model;
 
   const prev = readRecord(d.stateDir(), id);
@@ -692,7 +776,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 +805,7 @@ export async function startAgent(
         env: out.env,
         passthrough: rt.envPassthrough,
         grants: cfg.agents[id]?.grants ?? [],
+        ...binDirOf(det),
       },
       old,
       {},
@@ -795,6 +880,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 = availableOrRefuse(d, rt);
   ptyOrRefuse(d);
   return withClient(d, async (c) => {
     const old = sessionOf(await c.list(), rec);
@@ -809,6 +895,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 +920,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,25 @@
  *           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) each runtime: its status, the CLI it runs and where
+ *           that came from (setting, login-shell, PATH, well-known), 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.
+ * 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 +51,7 @@ import {
   type AgentsDeps,
   type AgentsResolved,
   type EarlyExit,
+  type RuntimeChoice,
   type Started,
 } from "./agent-ops.js";
 import {
@@ -63,7 +73,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 +88,16 @@ 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 [--json]",
+    "    each runtime: 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",
     "",
-    "Runtimes: den-claude (default; needs claude on PATH) and generic (the",
+    "Runtimes: den-claude (default; Claude Code's claude) and generic (the",
     "persona's argv template). Attach with `{cli} sessions attach <ws>:<id>`.",
+    "A runtime's CLI is found as your terminal finds it: agents.runtimes.<id>.bin",
+    "in config/local/user.yml (an absolute path) wins, then the login shell's PATH,",
+    "this PATH, and its install directories (~/.local/bin, ~/.claude/local,",
+    "/opt/homebrew/bin, /usr/local/bin, npm's global bin).",
     "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 +267,87 @@ 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> = {
+  setting: "agents.runtimes setting",
+  "login-shell": "login shell PATH",
+  PATH: "PATH",
+  "well-known": "install directory",
+};
+
+/** `agents doctor`'s lines for one runtime (names and paths, never env values). */
+export function doctorLines(
+  r: RuntimeChoice,
+  cli: string,
+  userConfig: string,
+): string[] {
+  const lines = [
+    `${r.id}${r.label ? ` (${r.label})` : ""}${r.default ? "  [default]" : ""}`,
+    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)
+    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, { "--json": false });
+  noExtra(where, p);
+  await (deps.loginPath ?? (() => initLoginPath({ env: d.env })))();
+  const rts = await listRuntimes(d);
+  const def = rts.find((r) => r.default);
+  const code = def?.available ? 0 : 1;
+  if (p.flags["--json"]) {
+    d.out(
+      JSON.stringify(
+        { runtimes: rts, userConfig: d.userConfigFile() },
+        null,
+        2,
+      ),
+    );
+    return code;
+  }
+  rts.forEach((r, i) => {
+    if (i) d.out("");
+    for (const l of doctorLines(r, d.cli, d.userConfigFile())) 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 +368,8 @@ export async function cmdAgents(
           return await resume(rest, d);
         case "personas":
           return await listPersonas(rest, d);
+        case "doctor":
+          return await doctor(rest, d, deps);
         default:
           throw new UsageError(`unknown agents command "${sub}"`);
       }

package/src/ui/cli/index.ts

@@ -2711,8 +2711,11 @@ class DenCLI {
     );
     console.log();
     console.log(chalk.bold("  Flags:"));
+    // Two spaces at least between a flag and its text, a long one too.
     const row = (f: string, d: string) =>
-      console.log(`    ${chalk.cyan(f.padEnd(20))}${d}`);
+      console.log(
+        `    ${chalk.cyan(f.padEnd(Math.max(20, f.length + 2)))}${d}`,
+      );
     row(
       "-x, --exclude",
       "start only the dependencies, not the current/seed repo",
@@ -4660,6 +4663,35 @@ class DenCLI {
         if (!d.available) warn(`edge.tls ${edge.tls.strategy}: ${d.reason}`);
       }
     }
+    // The web keys: a wrong value would stop `web up`; one read and
+    // ignored (the distribution's web.allow_plain_http_remote: only
+    // config/local/user.yml counts) is flagged, as `web up` says it.
+    {
+      const { ignoredConfigWarning, readWebAuthConfig } =
+        await import("../../shared/web-session.js");
+      try {
+        const w = ignoredConfigWarning(
+          readWebAuthConfig(getDistRoot(), product().configFile),
+        );
+        if (w) console.warn(chalk.yellow(`\n  ⚠  ${w}`));
+      } catch (e) {
+        console.error(chalk.red(`\n  ✗  web: ${(e as Error).message}`));
+        process.exitCode = 1;
+      }
+    }
+    // The caps: agents.max_concurrent (agents) and sessions.max_concurrent
+    // (plain sessions). A wrong value would refuse every start.
+    {
+      const { readAgentsConfig, readSessionsConfig } =
+        await import("../../shared/den-config.js");
+      for (const read of [readAgentsConfig, readSessionsConfig])
+        try {
+          read();
+        } catch (e) {
+          console.error(chalk.red(`\n  ✗  ${(e as Error).message}`));
+          process.exitCode = 1;
+        }
+    }
     const positional = args.filter((a) => !a.startsWith("-"));
     const held = args.includes("--held");
     // Bare `validate` in the distribution root (which has no manifest of its