@monster-orange/den 0.4.0 → 0.4.1

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

@@ -1,7 +1,9 @@
 /**
  * `<cli> agents list|start|stop|resume|personas` (AG-2a, AG spec §5c):
  * an agent is a persona and a workspace, run by a runtime in a session of
- * the AG-3a host.
+ * the AG-3a host. This is the CLI's front: it parses the arguments and
+ * prints; what each operation does is agent-ops.ts, which the Workspaces
+ * page's routes (server/agent-routes.ts) call too.
  *
  *   start   resolves the persona (Den's default pack, then
  *           agents.persona_packs) and the runtime, asks the runtime for argv,
@@ -26,62 +28,40 @@
  * Nothing here takes a grant: grants come from the org config only. The
  * host enforces agents.max_concurrent on every start.
  */
-import * as fs from "fs";
-import * as path from "path";
+import { DEFAULT_RUNTIME_ID } from "../../shared/agents/runtimes.js";
+import { HostError } from "../../shared/sessions/client.js";
 import {
-  AGENTS_RESERVED_KEYS,
-  readAgentsConfig,
-  type ResolvedAgentsConfig,
-} from "../../shared/den-config.js";
-import { cliEntrypoint } from "../../shared/engine.js";
-import { getDistRoot } from "../../shared/paths.js";
-import { envKey } from "../../shared/product.js";
-import { redactSecrets } from "../../shared/redact.js";
-import {
-  loadPersonas,
-  resolvePackDirs,
-  type Persona,
-} from "../../shared/agents/personas.js";
-import {
-  AGENT_ID_RE,
-  agentFilesDir,
-  listRecords,
-  readRecord,
-  writeRecord,
-  writeRuntimeFiles,
-  type AgentRecord,
-} from "../../shared/agents/records.js";
-import {
-  agentSessionEnv,
-  DEFAULT_RUNTIME_ID,
-  getRuntime,
-  LaunchError,
-  runtimeIds,
-  type AgentMcp,
-  type LaunchInput,
-  type Runtime,
-} from "../../shared/agents/runtimes.js";
-import { HostError, type HostClient } from "../../shared/sessions/client.js";
-import { DEN_PTY_ID } from "../../shared/sessions/den-pty.js";
-import { inWorkspace, sessionName } from "../../shared/sessions/names.js";
-import type { SessionInfo } from "../../shared/sessions/types.js";
-import { serverSpec } from "../mcp/connect.js";
+  AgentError,
+  listAgents,
+  listPersonas as personaList,
+  loadAgentWorkspaces,
+  resolveAgentsDeps,
+  resumeAgent,
+  startAgent,
+  stopAgent,
+  type AgentsDeps,
+  type AgentsResolved,
+  type EarlyExit,
+  type Started,
+} from "./agent-ops.js";
 import {
   columns,
-  contractInfo,
   guarded,
-  loadWorkspaces,
   noExtra,
   parseArgs,
-  resolveDeps,
-  state,
   UsageError,
-  withClient,
   workspaceFlag,
-  type Resolved,
-  type SessionsDeps,
 } from "./sessions-command.js";
 
+export {
+  agentMcp,
+  agentRows,
+  EXIT_WATCH_MS,
+  plainLines,
+  type AgentRow,
+  type AgentsDeps,
+} from "./agent-ops.js";
+
 export const AGENTS_HELP = {
   usage: "agents <list|start|stop|resume|personas> ...",
   lines: [
@@ -106,193 +86,13 @@ export const AGENTS_HELP = {
   ],
 };
 
-export interface AgentsDeps extends SessionsDeps {
-  agentsConfig?: () => ResolvedAgentsConfig;
-  distRoot?: () => string;
-  /** A workspace's checkout directory: where its agents run. */
-  workspaceDir?: (ws: string) => string;
-  /** The MCP server binary and its env; Den adds the scoped args. */
-  mcpServer?: () => { command: string[] | string; env: Record<string, string> };
-  /**
-   * How long start and resume watch a new session for an early non-zero
-   * exit (default 3000 ms; 0: not at all).
-   */
-  exitWatchMs?: number;
-}
-
-interface AgentsResolved extends Resolved {
-  agentsConfig: () => ResolvedAgentsConfig;
-  distRoot: () => string;
-  workspaceDir: (ws: string) => string;
-  mcpServer: () => { command: string[] | string; env: Record<string, string> };
-  exitWatchMs: number;
-}
-
-/** The early-exit watch: at most this long, polling the host. */
-export const EXIT_WATCH_MS = 3000;
-const EXIT_POLL_MS = 100;
-/** The most lines of an early exit's scrollback printed. */
-const EXIT_TAIL_LINES = 10;
-
-let workspaceDirFn: ((ws: string) => string) | null = null;
-async function loadWorkspaceDir(d: AgentsDeps): Promise<void> {
-  if (d.workspaceDir || workspaceDirFn) return;
-  const ws = await import("../../shared/environment-manager/workspaces.js");
-  const { getReposRoot } = await import("../../shared/den-config.js");
-  workspaceDirFn = (name) => {
-    const cfg = ws.readWorkspacesFile().workspaces[name];
-    if (!cfg) throw new UsageError(`workspace "${name}" does not exist`);
-    return ws.resolveWorkspaceDir(name, cfg, getReposRoot());
-  };
-}
-
-/** The distribution's bin shim (as `mcp connect` registers), else Den's CLI. */
-function defaultMcpServer(cli: string): {
-  command: string[];
-  env: Record<string, string>;
-} {
-  const s = serverSpec({
-    cli,
-    distRoot: getDistRoot(),
-    nodeBinDir: path.dirname(process.execPath),
-    platform: process.platform,
-  });
-  if (fs.existsSync(s.command)) return { command: [s.command], env: s.env };
-  const e = cliEntrypoint();
-  return { command: [e.command, ...e.args], env: s.env };
-}
-
-function resolveAgentsDeps(d: AgentsDeps): AgentsResolved {
-  const base = resolveDeps(d);
-  return {
-    ...base,
-    agentsConfig: d.agentsConfig ?? (() => readAgentsConfig()),
-    distRoot: d.distRoot ?? getDistRoot,
-    workspaceDir:
-      d.workspaceDir ??
-      ((ws) => {
-        if (!workspaceDirFn) throw new Error("workspaces not loaded");
-        return workspaceDirFn(ws);
-      }),
-    mcpServer: d.mcpServer ?? (() => defaultMcpServer(base.cli)),
-    exitWatchMs: d.exitWatchMs ?? EXIT_WATCH_MS,
-  };
-}
-
-// ── the agent's MCP ─────────────────────────────────────────────────────────
-
-/**
- * Where the distribution is, from the caller's env (DEN_ROOT,
- * `<PREFIX>_ROOT`, `<PREFIX>_HOME`): the agent's env is an allowlist, so
- * its MCP server gets them in its own config instead, and reaches the same
- * distribution and state dir as the CLI that started it. Paths, never
- * secrets.
- */
-function distLocationEnv(env: NodeJS.ProcessEnv): Record<string, string> {
-  const out: Record<string, string> = {};
-  for (const k of new Set(["DEN_ROOT", envKey("ROOT"), envKey("HOME")])) {
-    const v = env[k];
-    if (v) out[k] = v;
-  }
-  return out;
-}
-
-/** `<cli> mcp --workspace <ws> --actor agent:<id> [--grant <g>…]`. */
-export function agentMcp(
-  d: AgentsResolved,
-  ws: string,
-  id: string,
-  grants: string[],
-): AgentMcp {
-  const server = d.mcpServer();
-  const bin = Array.isArray(server.command) ? server.command : [server.command];
-  return {
-    name: d.cli,
-    command: [
-      ...bin,
-      "mcp",
-      "--workspace",
-      ws,
-      "--actor",
-      `agent:${id}`,
-      ...grants.flatMap((g) => ["--grant", g]),
-    ],
-    env: { ...distLocationEnv(d.env), ...server.env },
-    scope: ws,
-  };
-}
-
-// ── rows ────────────────────────────────────────────────────────────────────
-
-/**
- * One row per agent of a workspace: each session joined to the agent record
- * that started it (by session id), and each record whose session is gone,
- * as stopped (after `agents stop`) or ended. A session without a record is
- * a plain one (`sessions start`), not an agent: `sessions list` shows it.
- */
-export interface AgentRow {
-  agent: string;
-  persona?: string;
-  runtime?: string;
-  model?: string;
-  workspace?: string;
-  cwd?: string;
-  /** running, exited (<code>), stopped or ended. */
-  state: string;
-  session?: SessionInfo;
-}
-
-function rowState(rec: AgentRecord | undefined, s?: SessionInfo): string {
-  if (s && !s.exited) return "running";
-  if (rec?.stoppedAt) return "stopped";
-  return s ? state(s) : "ended";
-}
-
-export function agentRows(
-  sessions: SessionInfo[],
-  records: AgentRecord[] = [],
-): AgentRow[] {
-  const bySession = new Map(records.map((r) => [r.session.id, r]));
-  const rows: AgentRow[] = [];
-  const shown = new Set<string>();
-  for (const s of sessions) {
-    const rec = bySession.get(s.ref.id);
-    if (!rec) continue;
-    shown.add(rec.id);
-    rows.push({
-      agent: rec.id,
-      ...recordFields(rec),
-      state: rowState(rec, s),
-      session: contractInfo(s),
-    });
-  }
-  for (const rec of records)
-    if (!shown.has(rec.id))
-      rows.push({ agent: rec.id, ...recordFields(rec), state: rowState(rec) });
-  return rows;
-}
-
-function recordFields(rec: AgentRecord): Partial<AgentRow> {
-  return {
-    persona: rec.persona,
-    runtime: rec.runtime,
-    ...(rec.model ? { model: rec.model } : {}),
-    workspace: rec.workspace,
-    cwd: rec.cwd,
-  };
-}
-
 async function list(args: string[], d: AgentsResolved): Promise<number> {
   const where = "agents list";
   const p = parseArgs(where, args, { "--workspace": true, "--json": false });
   noExtra(where, p);
   const ws = workspaceFlag(where, p);
   if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
-  const sessions = (await withClient(d, (c) => c.list())).filter((s) =>
-    inWorkspace(s, d.dist, ws),
-  );
-  const records = listRecords(d.stateDir()).filter((r) => r.workspace === ws);
-  const rows = agentRows(sessions, records);
+  const rows = await listAgents(d, ws);
   if (p.flags["--json"]) {
     d.out(JSON.stringify(rows, null, 2));
     return 0;
@@ -327,210 +127,36 @@ async function list(args: string[], d: AgentsResolved): Promise<number> {
   return 0;
 }
 
-// ── start ───────────────────────────────────────────────────────────────────
-
-/** The agents config; an invalid one is a refusal naming the key. */
-function agentsConfig(d: AgentsResolved): ResolvedAgentsConfig {
-  try {
-    return d.agentsConfig();
-  } catch (e) {
-    throw new Refused((e as Error).message);
+/** An early exit, as the terminal shows it: its code and last lines. */
+function printEarlyExit(d: AgentsResolved, id: string, e: EarlyExit): void {
+  const code = e.exitCode === undefined ? "" : ` (exit ${e.exitCode})`;
+  d.err(`✗ agent ${id} exited at once${code}`);
+  if (e.tail.length) {
+    d.err(`  its last ${e.tail.length === 1 ? "line" : "lines"}:`);
+    for (const l of e.tail) d.err(`  | ${l}`);
   }
+  d.err(`  All of it: ${d.cli} sessions attach ${e.sessionName}`);
 }
 
-/** Every persona; a bad pack or persona file is a refusal naming it. */
-function personas(
-  d: AgentsResolved,
-  cfg: ResolvedAgentsConfig,
-): Map<string, Persona> {
-  try {
-    return loadPersonas(resolvePackDirs(cfg.personaPacks, d.distRoot()));
-  } catch (e) {
-    throw new Refused((e as Error).message);
+/** A start's or resume's warnings and outcome; its exit code. */
+function report(d: AgentsResolved, s: Started, line: string): number {
+  for (const w of s.warnings) d.err(w);
+  if (s.early) {
+    printEarlyExit(d, s.rec.id, s.early);
+    return 1;
   }
+  d.out(line);
+  d.out(`  attach: ${d.cli} sessions attach ${s.rec.sessionName}`);
+  return 0;
 }
 
-function runtimeFor(id: string): Runtime {
-  const rt = getRuntime(id);
-  if (!rt)
-    throw new UsageError(
-      `no runtime "${id}" (runtimes: ${runtimeIds().join(", ")})`,
-    );
-  return rt;
-}
-
-/** The running session of `rec`, if any; else its exited one, if listed. */
-function sessionOf(
-  sessions: SessionInfo[],
-  rec: AgentRecord,
-): SessionInfo | undefined {
-  return sessions.find((s) => s.ref.id === rec.session.id);
-}
-
-/** Refuse: exit 1 with the message (and hints). */
-class Refused extends Error {
-  constructor(
-    message: string,
-    readonly hints: string[] = [],
-  ) {
-    super(message);
-  }
-}
-
-/**
- * The id an agent gets: --id, else the persona's id while it is free (or
- * this workspace's), else `<persona>-<ws>`.
- */
-function defaultId(stateDir: string, persona: string, ws: string): string {
-  const rec = readRecord(stateDir, persona);
-  if (!rec || rec.workspace === ws) return persona;
-  return `${persona}-${ws}`.slice(0, 64);
-}
-
-function checkId(where: string, id: string): void {
-  if (!AGENT_ID_RE.test(id) || AGENTS_RESERVED_KEYS.includes(id))
-    throw new UsageError(
-      `${where}: --id "${id}" must be letters, digits, ".", "_" or "-" (1-64), ` +
-        `and not ${AGENTS_RESERVED_KEYS.join(" or ")}`,
-    );
-}
-
-interface Launch {
-  rec: Omit<AgentRecord, "session" | "startedAt">;
-  argv: string[];
-  env: Record<string, string>;
-  /** The runtime's envPassthrough. */
-  passthrough?: readonly string[];
-  warnings?: string[];
-}
-
-/** Start `launch` as the agent's session (replacing an exited one) and record it. */
-async function startSession(
-  d: AgentsResolved,
-  c: HostClient,
-  launch: Launch,
-  old: SessionInfo | undefined,
-  extra: Partial<AgentRecord>,
-): Promise<{ rec: AgentRecord; info: SessionInfo }> {
-  if (old?.exited) await c.forget(old.ref.id);
-  const tty = d.stdout.isTTY;
-  const info = await c.start(
-    {
-      name: launch.rec.sessionName,
-      cwd: launch.rec.cwd,
-      argv: launch.argv,
-      // Never the caller's whole env: the allowlist, then the runtime's.
-      env: agentSessionEnv(
-        d.env,
-        { envPassthrough: launch.passthrough },
-        launch.env,
-        launch.rec.id,
-      ),
-      cols: (tty && d.stdout.columns) || 80,
-      rows: (tty && d.stdout.rows) || 24,
-    },
-    { limit: d.maxConcurrent() },
-  );
-  const rec: AgentRecord = {
-    ...launch.rec,
-    session: { backend: info.ref.backend, id: info.ref.id },
-    startedAt: info.startedAt,
-    ...extra,
-  };
-  delete rec.stoppedAt;
-  writeRecord(d.stateDir(), rec);
-  for (const w of launch.warnings ?? []) d.err(w);
-  return { rec, info };
-}
-
-/** CSI, OSC (BEL or ST ended), and other two-byte escapes. */
-/* eslint-disable no-control-regex */
-const TERMINAL_ESCAPE =
-  /\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b[@-Z\\-_]/g;
-/* eslint-enable no-control-regex */
-
-/** Printable lines of terminal output: escapes and control bytes removed. */
-export function plainLines(text: string): string[] {
-  return (
-    text
-      .replace(TERMINAL_ESCAPE, "")
-      .split(/\r?\n/)
-      // A carriage return redraws the line: what stays is after the last.
-      .map((l) => l.slice(l.lastIndexOf("\r") + 1))
-      // eslint-disable-next-line no-control-regex
-      .map((l) => l.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "").trimEnd())
-      .filter((l) => l.trim())
-  );
-}
-
-/**
- * Watch a new session for an early exit (d.exitWatchMs, polling the host).
- * A non-zero exit is reported with its code and the last lines it printed
- * (secret-shaped values redacted); true when it did.
- */
-async function exitedAtOnce(
-  d: AgentsResolved,
-  c: HostClient,
-  id: string,
-  info: SessionInfo,
-): Promise<boolean> {
-  const deadline = Date.now() + d.exitWatchMs;
-  while (Date.now() < deadline) {
-    await new Promise((r) =>
-      setTimeout(r, Math.min(EXIT_POLL_MS, Math.max(0, deadline - Date.now()))),
-    );
-    const s = (await c.list()).find((x) => x.ref.id === info.ref.id);
-    if (!s) return false;
-    if (!s.exited) continue;
-    if (s.exitCode === 0) return false;
-    const code = s.exitCode === undefined ? "" : ` (exit ${s.exitCode})`;
-    d.err(`✗ agent ${id} exited at once${code}`);
-    const tail = plainLines(
-      (await c.scrollback(s.ref.id, 64 * 1024)).toString("utf-8"),
-    ).slice(-EXIT_TAIL_LINES);
-    if (tail.length) {
-      d.err(`  its last ${tail.length === 1 ? "line" : "lines"}:`);
-      for (const l of tail) d.err(`  | ${redactSecrets(l)}`);
-    }
-    d.err(`  All of it: ${d.cli} sessions attach ${s.name}`);
-    return true;
-  }
-  return false;
-}
-
-function launchInput(
-  d: AgentsResolved,
-  cfg: ResolvedAgentsConfig,
-  persona: Persona,
-  ws: string,
-  id: string,
-  model: string | undefined,
-): LaunchInput {
-  const grants = cfg.agents[id]?.grants ?? [];
-  for (const g of grants)
-    if (!d.workspaceExists(g))
-      throw new Refused(`agents.${id}.grants: workspace "${g}" does not exist`);
-  const dir = d.workspaceDir(ws);
-  if (!fs.statSync(dir, { throwIfNoEntry: false })?.isDirectory())
-    throw new Refused(`workspace ${ws}'s directory ${dir} does not exist`);
-  return {
-    persona,
-    workspace: { name: ws, dir },
-    agentId: id,
-    worktree: dir,
-    ...(model ? { model } : {}),
-    mcp: agentMcp(d, ws, id, grants),
-    filesDir: agentFilesDir(d.stateDir(), id),
-    env: d.env,
-  };
-}
-
-function ptyOrRefuse(d: AgentsResolved): void {
-  const pty = d.pty();
-  if (!pty.available)
-    throw new Refused(`${DEN_PTY_ID} is unavailable: ${pty.reason}`, [
-      `\`${d.cli} doctor\` shows the session backend's state.`,
-    ]);
+/** A flag's string value, or undefined. */
+function str(
+  p: ReturnType<typeof parseArgs>,
+  flag: string,
+): string | undefined {
+  const v = p.flags[flag];
+  return typeof v === "string" ? v : undefined;
 }
 
 async function start(args: string[], d: AgentsResolved): Promise<number> {
@@ -545,188 +171,57 @@ async function start(args: string[], d: AgentsResolved): Promise<number> {
   noExtra(where, p);
   const ws = workspaceFlag(where, p);
   if (!ws) throw new UsageError(`${where} needs -w <workspace>`);
-  const personaId = p.flags["--persona"];
-  if (typeof personaId !== "string")
-    throw new UsageError(`${where} needs --persona <p>`);
-  if (!d.workspaceExists(ws))
-    throw new UsageError(`${where}: workspace "${ws}" does not exist`);
-  const cfg = agentsConfig(d);
-  const all = personas(d, cfg);
-  const persona = all.get(personaId);
-  if (!persona)
-    throw new UsageError(
-      `${where}: no persona "${personaId}" (personas: ${[...all.keys()].sort().join(", ")})`,
-    );
-  const idFlag = p.flags["--id"];
-  const id =
-    typeof idFlag === "string"
-      ? idFlag
-      : defaultId(d.stateDir(), persona.id, ws);
-  checkId(where, id);
-  const rtFlag = p.flags["--runtime"];
-  const rt = runtimeFor(
-    typeof rtFlag === "string"
-      ? rtFlag
-      : (persona.runtime ?? DEFAULT_RUNTIME_ID),
-  );
-  const det = rt.detect(d.env);
-  if (!det.available)
-    throw new Refused(`${rt.id} is unavailable: ${det.why ?? "unknown"}`);
-  const modelFlag = p.flags["--model"];
-  const model = typeof modelFlag === "string" ? modelFlag : persona.model;
-
-  const prev = readRecord(d.stateDir(), id);
-  if (prev && prev.workspace !== ws)
-    throw new Refused(
-      `agent ${id} belongs to workspace ${prev.workspace}; give this one another --id`,
-    );
-  ptyOrRefuse(d);
-  const input = launchInput(d, cfg, persona, ws, id, model);
-
-  return withClient(d, async (c) => {
-    const sessions = await c.list();
-    const old = prev ? sessionOf(sessions, prev) : undefined;
-    if (old && !old.exited)
-      throw new Refused(`agent ${id} is running (${old.name})`, [
-        `Attach: ${d.cli} sessions attach ${old.name}`,
-      ]);
-    const out = rt.launch(input);
-    writeRuntimeFiles(input.filesDir, out.files);
-    const { rec, info } = await startSession(
-      d,
-      c,
-      {
-        rec: {
-          id,
-          persona: persona.id,
-          runtime: rt.id,
-          ...(model ? { model } : {}),
-          workspace: ws,
-          cwd: input.worktree,
-          sessionName: sessionName(d.dist, ws, id),
-          ...(out.resumeToken ? { resumeToken: out.resumeToken } : {}),
-        },
-        argv: out.argv,
-        env: out.env,
-        passthrough: rt.envPassthrough,
-        warnings: out.warnings,
-      },
-      old,
-      {},
-    );
-    if (await exitedAtOnce(d, c, id, info)) return 1;
-    d.out(
-      `started agent ${id} (${persona.id}, ${rt.id}) as ${rec.sessionName} in ${rec.cwd}`,
-    );
-    d.out(`  attach: ${d.cli} sessions attach ${rec.sessionName}`);
-    return 0;
+  const persona = str(p, "--persona");
+  if (!persona) throw new UsageError(`${where} needs --persona <p>`);
+  const s = await startAgent(d, {
+    workspace: ws,
+    persona,
+    runtime: str(p, "--runtime"),
+    model: str(p, "--model"),
+    id: str(p, "--id"),
   });
+  return report(
+    d,
+    s,
+    `started agent ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
 }
 
-// ── stop, resume ────────────────────────────────────────────────────────────
-
-function recordFor(
+/** `<id> [-w <ws>]`. */
+function idAndWorkspace(
   where: string,
-  p: ReturnType<typeof parseArgs>,
-  d: AgentsResolved,
-): AgentRecord {
+  args: string[],
+): { id: string; ws?: string } {
+  const p = parseArgs(where, args, { "--workspace": true });
+  noExtra(where, p, 1);
   const id = p.positional[0];
   if (!id) throw new UsageError(`${where} needs <id>`);
-  const rec = readRecord(d.stateDir(), id);
-  if (!rec) throw new Refused(`no agent "${id}"`);
-  const ws = workspaceFlag(where, p);
-  if (ws && ws !== rec.workspace)
-    throw new Refused(
-      `agent ${id} is in workspace ${rec.workspace}, not ${ws}`,
-    );
-  return rec;
+  return { id, ws: workspaceFlag(where, p) };
 }
 
 async function stop(args: string[], d: AgentsResolved): Promise<number> {
-  const where = "agents stop";
-  const p = parseArgs(where, args, { "--workspace": true });
-  noExtra(where, p, 1);
-  const rec = recordFor(where, p, d);
-  return withClient(d, async (c) => {
-    const s = sessionOf(await c.list(), rec);
-    if (s && !s.exited) await c.kill(s.ref.id, "TERM");
-    writeRecord(d.stateDir(), { ...rec, stoppedAt: new Date().toISOString() });
-    d.out(
-      s && !s.exited
-        ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid})`
-        : `agent ${rec.id} was not running; marked stopped`,
-    );
-    return 0;
-  });
+  const { id, ws } = idAndWorkspace("agents stop", args);
+  const { rec, session: s } = await stopAgent(d, id, ws);
+  d.out(
+    s
+      ? `stopped agent ${rec.id} (sent TERM to ${s.name}, pid ${s.pid})`
+      : `agent ${rec.id} was not running; marked stopped`,
+  );
+  return 0;
 }
 
 async function resume(args: string[], d: AgentsResolved): Promise<number> {
-  const where = "agents resume";
-  const p = parseArgs(where, args, { "--workspace": true });
-  noExtra(where, p, 1);
-  const rec = recordFor(where, p, d);
-  const rt = runtimeFor(rec.runtime);
-  if (!rt.resume)
-    throw new Refused(`runtime ${rt.id} does not declare resume`, [
-      `Start it again: ${d.cli} agents start -w ${rec.workspace} --persona ${rec.persona} --id ${rec.id}`,
-    ]);
-  const cfg = agentsConfig(d);
-  const persona = personas(d, cfg).get(rec.persona);
-  if (!persona)
-    throw new Refused(`agent ${rec.id}'s persona "${rec.persona}" is gone`);
-  ptyOrRefuse(d);
-  return withClient(d, async (c) => {
-    const old = sessionOf(await c.list(), rec);
-    if (old && !old.exited)
-      throw new Refused(`agent ${rec.id} is running (${old.name})`, [
-        `Attach: ${d.cli} sessions attach ${old.name}`,
-      ]);
-    const input = launchInput(
-      d,
-      cfg,
-      persona,
-      rec.workspace,
-      rec.id,
-      rec.model,
-    );
-    // Resume in the cwd the agent had, wherever the workspace points now.
-    const at = {
-      ...input,
-      worktree: rec.cwd,
-      ...(rec.resumeToken ? { resumeToken: rec.resumeToken } : {}),
-    };
-    // A session nobody prompted left no conversation: continuing it fails,
-    // so it starts afresh under the same id. A session the host no longer
-    // lists is assumed prompted.
-    const fresh = Boolean(old && !old.prompted && rec.resumeToken);
-    const out = fresh ? rt.launch(at) : rt.resume!(at);
-    if (!out) throw new Refused(`agent ${rec.id} has nothing to resume`);
-    writeRuntimeFiles(input.filesDir, out.files);
-    const { session: _s, startedAt: _t, resumedAt: _r, ...base } = rec;
-    if (fresh)
-      d.out(
-        `agent ${rec.id}: starting fresh: it was never prompted, so there is no conversation to resume`,
-      );
-    const { rec: next, info } = await startSession(
-      d,
-      c,
-      {
-        rec: { ...base, cwd: rec.cwd },
-        argv: out.argv,
-        env: out.env,
-        passthrough: rt.envPassthrough,
-        warnings: out.warnings,
-      },
-      old,
-      fresh ? {} : { resumedAt: new Date().toISOString() },
-    );
-    if (await exitedAtOnce(d, c, rec.id, info)) return 1;
+  const { id, ws } = idAndWorkspace("agents resume", args);
+  const s = await resumeAgent(d, id, ws);
+  if (s.fresh)
     d.out(
-      `${fresh ? "started" : "resumed"} agent ${rec.id} as ${next.sessionName} in ${next.cwd}`,
+      `agent ${s.rec.id}: starting fresh: it was never prompted, so there is no conversation to resume`,
     );
-    d.out(`  attach: ${d.cli} sessions attach ${next.sessionName}`);
-    return 0;
-  });
+  return report(
+    d,
+    s,
+    `${s.fresh ? "started" : "resumed"} agent ${s.rec.id} as ${s.rec.sessionName} in ${s.rec.cwd}`,
+  );
 }
 
 async function listPersonas(
@@ -736,17 +231,9 @@ async function listPersonas(
   const where = "agents personas";
   const p = parseArgs(where, args, { "--json": false });
   noExtra(where, p);
-  const all = [...personas(d, agentsConfig(d)).values()].sort((a, b) =>
-    a.id.localeCompare(b.id),
-  );
+  const all = personaList(d);
   if (p.flags["--json"]) {
-    d.out(
-      JSON.stringify(
-        all.map(({ prompt: _p, ...rest }) => rest),
-        null,
-        2,
-      ),
-    );
+    d.out(JSON.stringify(all, null, 2));
     return 0;
   }
   for (const l of columns([
@@ -778,14 +265,12 @@ export async function cmdAgents(
         case "list":
           return await list(rest, d);
         case "start":
-          await loadWorkspaces(deps);
-          await loadWorkspaceDir(deps);
+          await loadAgentWorkspaces(deps);
           return await start(rest, d);
         case "stop":
           return await stop(rest, d);
         case "resume":
-          await loadWorkspaces(deps);
-          await loadWorkspaceDir(deps);
+          await loadAgentWorkspaces(deps);
           return await resume(rest, d);
         case "personas":
           return await listPersonas(rest, d);
@@ -793,17 +278,14 @@ export async function cmdAgents(
           throw new UsageError(`unknown agents command "${sub}"`);
       }
     } catch (e) {
-      if (e instanceof Refused || e instanceof LaunchError) {
+      if (e instanceof AgentError) {
+        if (e.usage) throw new UsageError(e.message);
         d.err(`✗ ${e.message}`);
-        for (const h of e instanceof Refused ? e.hints : []) d.err(`  ${h}`);
+        for (const h of e.hints) d.err(`  ${h}`);
         return 1;
       }
       if (e instanceof HostError) {
         d.err(`✗ ${e.message}`);
-        if (e.code === "cap")
-          d.err(
-            `  Stop one first (\`${d.cli} agents stop <id>\`), or raise agents.max_concurrent.`,
-          );
         return 1;
       }
       throw e;